Before installing Content Picker

About the Content Picker prerequisites

Before you install Content Picker, complete these steps:

  • Prepare an HCMS installation.

  • Deploy the HCMS schemas.

  • Provide HTTPS.

  • Enable Dynamic Image Cache.

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 created with the command-line 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 new HTTP Basic 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 Content 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 MB (1 MB = 1,024 × 1,024 bytes) 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 can be a good fit for an environment without a cloud, 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 command-line 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 Content 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 support for multiple asset types, typically subtypes (for example: images are not just picture., but also picture.barcode.).

The current picker filters use one Office Documents group with the subtypes Text documents, Spreadsheets, Presentations, and "Drawings & diagrams". Office Documents includes Word, Excel, and PowerPoint files. The PDF filter returns all PDF files. The generic Documents and ZIP filters are no longer used.

Schemas are deployed via HTTP with HTTP Basic authorization by using the documented Schema Modification endpoints. To deploy all schemas at once, use the script set-schema-mass.sh in the root directory of the Content Picker repository:

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

The script needs the bash shell and the curl utility. Both Linux and macOS are supported, but curl usually has to be installed as an additional package.

Schema update in Content Picker 2.0.0

Use the schemas from the Content Picker repository for the version you install. Since Content Picker 2.0.0, the schema 030-picker_file-schema.json accepts two asset types:

JSON
"cs:asset.type": ["document.", "text."]

With this schema, Office files that Censhare stored with the asset type Text, for example Word documents, appear in the picker and in the Office Documents filter.

When you upgrade from a Content Picker version older than 2.0.0, deploy the schemas again. Without the updated schema, the picker continues to work, but it does not list files with the asset type Text. Deploying the schemas again does no harm if you do not need these files.

The Content Picker repository uses document. in this schema. Do not replace it with the notation document.* that the Marmind schemas of the Censhare Server use.

Marmind tenants

Marmind tenants do not deploy these schemas with set-schema-mass.sh. The Censhare Server ships the schemas for Marmind tenants. In the censhare-product repository, they are in censhare-Server/app/modules/entirely/schemas_marmind/.

Censhare 2026.1 does not include the asset type Text in these schemas. On Censhare 2026.1, Marmind tenants therefore do not list Word files stored with the asset type Text, regardless of the Content Picker version. Censhare 2026.2 adds the asset type Text to these schemas.

Provide HTTPS for a public domain

After installation, HCMS serves only plain HTTP over a nonstandard port (usually 8080, or a random port assigned by Docker). You cannot configure HCMS to provide HTTPS. An additional component must provide it: a 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 is not specific to HCMS or Censhare.

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 Content Picker is the ability to show thumbnails/previews of the media and for this purpose, the "Dynamic Image Cache" is used (cs:media mapping).

Previews of documents and of images without stored dimensions are requested at the largest available size and are no longer blurry. For grayscale images and scans, Content Picker falls back to a format that HCMS can deliver when a usable preview exists.

Enable Dynamic Image Cache

Dynamic Image Cache is not enabled automatically in every installation. Enable it explicitly in the configuration. In the command-line tool, use the options --image-cache-max-size and --image-cache-max-age with the command configuration create or configuration update:

  • --image-cache-max-size Specifies the size of the dynamic image cache in MB. 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 Specifies the 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 the preview storage item (--image-cache-storage-item preview), which is always present and always has a correct type.

  • --image-cache-default-format Specifies the default image format of the generated images; it is either png or jpg. If no value is specified, png is used. 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 the format of generated images should be the same as the format of the 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 the AWS S3 bucket used to store the dynamic image cache content. The region is optional (eu-central-1 is the default value). The keys are optional too, but they must always be specified in pairs (either both of them, or neither of them). If none of them are specified, the dynamic image cache uses a local directory (/opt/corpus/censhare-Satellite/dic) inside the Docker container to store the content.