Before installing Content Picker

[]

HCMS installation

There are three basic ways to install and run HCMS. However, not every installation makes sense for using Content Picker. Below you will find references to complete documentation and a few things to know about every type of installation.

1. Satellite as a Docker container: installation guide
   • This is the recommended way, especially for a cloud environment.
   • The crucial part of the installation is configuration, which is stored on the censhare server and create my commandline configuration tool hcms configuration create. This command takes a number of options to configure various aspects, but all of them can also later be changed by configuration update (which takes the same options).
     • Regardless of the selected options, this command always creates a new HTTP basis credentials with username admin and random password. This password can be seen in the output and should be noted. It can be also changed or even removed by command authorization basic.
     • Whole configuration can be at any time shown by the configuration inspect command (including the HTTP Basic password).
     • Since Asset Picker uses "Dynamic Image Cache" to render thumbnails, options --image-cache-max-size and --image-cache-max-age are always required to enable this feature. They specify maximum cache size in MiB and expiration time in minutes.
     • Options --forwarded true and --forwarded-levels 1 are usually needed to support reverse proxy, but technically they are optional.
       
2. Satellite directly installed on Linux server: installation guide
   • This alternative might be a good fit for no-cloud environment, when no convenient docker configuration management is available.
   • The preparation is exactly the same as in the Docker setup, so the same notes as above apply (image cache configuration, auto-generated password)
     
3. Server module installed into censhare server: documentation
   • This is not recommended, as the server module is intended for very different use cases and although using it with Content Picker is theoretically possible, the complete solution might have performance and security issues.
   • Instead of the commandline tool, configuration is done in the censhare Admin Client. All the options mentioned above (and below) have their equivalents in the configuration dialog. The admin password needs to be manually created.
     

Deploying HCMS schemas

Schemas can be found in the Asset Picker source repository, in the schemas/ directory. They can be used as-is, but in many cases they need to be modified to fit the specific use case. The most common modification is a support for multiple asset types, typically subtypes (for example: images are not just picture., but also picture.barcode.).

Schemas are deployed via HTTP (with http basic authorization) by using the documented Schema Modification endpoints. For convenience, shell script is available to deploy them all at once:

./set-schema-mass.sh -u admin:password https://hcms-domain/hcms/v2.0  schemas/*

Note that the script needs bash shell script and curl utility. Both Linux and Mac OS X are supported, but curl usually has to be installed as an additional package.

Public domain / URL: how to get HTTPS

Please note that when installed, HCMS serves just plain HTTP over non-standard port (usually 8080, or even a random one assigned by docker). There is no supported way to provide HTTPS protocol by configuring HCMS, it needs to be provided by an additional component, the so-called "TLS-terminating reverse proxy" (usually called "balancer").

In most cloud environments, this is readily available out-of-the-box and integrated with the docker configuration management (like ALB+ECS in AWS or Ingress in Kubernetes). For a custom Linux-based environment, haproxy and nginx are the most popular solutions.

Details about this topic (including DNS domain and TLS/SSL certificate) are out of scope for this document, because it's nothing HCMS-specific or even censhare-specific.

Trust for the "Forwarded headers"*

Remember that the HCMS configuration needs to explicitly enable trust for the "Forwarded headers" with a correct number of trusted levels (which is the number of trusted reverse proxies that are part of the infrastructure), usually --forwarded true --forwarded-levels 1 . This is also mentioned in the installation manual. Otherwise, all the URLs in HCMS responses will have the wrong protocol and domain.

Dynamic Image Cache

One of the core features of Asset Picker it the ability to show thumbnails/previews of the media and for this purpose, the "Dynamic Image Cache" is used (cs:media mapping).

Enable Dynamic Image Cache

This feature is not automatically enabled in every installation, it needs to be explicitly enabled in configuration; in the commandline tool, this is done by the --image-cache-max-size and --image-cache-max-age options to the command configuration create or configuration update:

• --image-cache-max-size Specifies size of the dynamic image cache, in megabytes. Mandatory, if the cache should be enabled. It is a common practice to add more variants (sizes, defined in the picker_media schema) and use them in the frontend application.
  • --image-cache-max-age 43200 --image-cache-max-size 5000 is the recommended initial value for the cache itself, but it can be tweaked as needed
• --image-cache-max-age Specifieds expiration time of the dynamic image cache records, in minutes. Mandatory, if the cache should be enabled.

Important configuration

• --image-cache-storage-item Specifies storage item used as a source for all image variants. If no value is specified, master is used.
  • --image-cache-storage-item is very important to support images in formats other than JPEG and PNG. It defines which storage item is used as a source to dynamically render the thumbnail. By default, master is used; if the image is neither JPEG nor PNG, the conversion fails and no thumbnail is available! For this reason, it is a common practice to define a new storage item (usually called dic_master) that is filled automatically by automation (in the Image module) as a conversion from the original. This derived image is always JPG or PNG.
  • Another possibility is to use preview storage item (--image-cache-storage-item preview), which is always present and always has a correct type.

Other recommended configuration

• --image-cache-default-format Specifies default image format of the generated images; it is either png or jpg. If no value is specified, png is used. Note that this value is used only when auto-detection is disabled, or if the original image is neither jpg nor png.
• --image-cache-autodetect Specifies whether format of generated images should be the same as the format of original base image (png or jpeg). If no value is specified, automatic format detection is enabled.
• Using S3 is recommended whenever possible:
  • --image-cache-s3bucket, --image-cache-s3region, --image-cache-s3accessKey, --image-cache-s3secretKey Specify AWS S3 bucket used to store the dynamic image cache content. Region is optional (eu-central-1 is the default value), keys are optional too but they must be always specified in pair (either both of them, or neither of them). If none of them are specified, dynamic image cache will use local directory (/opt/corpus/censhare-Satellite/dic) inside docker container to store the content.