Additional HCMS Docker container variables

These variables can be supplied to the HCMS container upon start (as flags to the docker run command). They are not essential for it to run, but some may cause trouble if not set properly.

Volumes

The Headless CMS docker image does not declare any VOLUME configuration. By default, all data is then stored in the ephemeral container filesystem.
Explicitly declared volumes are highly recommended for creating HCMS containers in production environments.

There are two main storage areas that you can specify using -v (--volume) or --mount options:

/opt/corpus/censhare-Satellite/data is the asset data storage. It always contains at least one datastore. Each datastore contains both metadata (CDB) and storage items. Alternatively, the storage items can be stored in Amazon S3, saving significant amount of storage space and reducing HCMS initialization time. See customization article for more details.
/opt/corpus/censhare-Satellite/dic can serve as a dynamic image cache. This directory should only be used if Image Cache is used, i.e., the "cs:media" property in schema is configured, and an Amazon S3 storage is not configured for this purpose.

-v (--volume) and --mount are flags for the docker run command. Read more about their behaviour and differences in the official third-party documentation.

Limit of Open File Descriptors (ulimit)

Purpose

A total number of open file descriptors should be set to at least 16384.

A default configuration of the Docker daemon depends on a specific Linux distribution; in some cases the limit is very low.
For example, in AMI Linux (used by Amazon AWS ECS), such a limit is set to 1024 by default. This value is even not enough for Headless CMS to start properly. Container hosting services (AWS ECS, Kubernetes) allow this limit to be configured for each container; it is important to always use this configuration option.

How to manage

The limit can be managed by the --ulimit option upon container start.

You can check the current limit used by Docker daemon by invoking ulimit -n in the temporary container:

CODE

docker run --rm -it alpine:latest sh -c "ulimit -n"

A higher limit can be set either globally in the Docker daemon service configuration, depending on the specific Linux distribution, or by --ulimit nofile=<hard>:<soft> option for a single Docker container:

CODE

docker run --ulimit nofile=16384:16384 -d  -p 18888:8080 --name sample-01 --restart unless-stopped -e SATELLITE_SERVER -e SATELLITE_ID -e SATELLITE_KEY  docker.censhare.com/censhare/satellite-hcms:latest

Memory size

Purpose

A satellite uses 2 megabytes of heap by default. The total memory limit should be set to 2.5 gigabytes. Depending on the usage, this value might be too big - wasting precious resources - or too low. Before changing the container limit, the heap memory size of the satellite (in megabytes) must be changed by additional environment variable: SATELLITE_APP_MEMORY.

What to keep in mind

This variable should be set to a value lower than the container total memory limit; otherwise, the satellite might be killed by OOM killer!
The value must be a plain number, without a unit as M is added to it automatically.

A detailed information about the heap memory can be found in the official Java (JRE or JDK) documentation on the -Xmx option.

Internal schema repository (local directory)

Headless CMS by default starts with no schemas, and new ones need to be added via the REST API. It is, however, possible to provide schemas directly inside the Docker container: either by a mounted volume, or as additional layer via Dockerfile. These files are automatically loaded and compiled on start.

Each schema must be stored as a single file, with its name derived from the schema name: <schemaname>-schema.json or <number>-<schemaname>-schema.json. Examples: image-schema.json or 100-article-schema.json

Schemas can loaded from several directories, configurable via the following environment variables:

HCMS_DEFAULT_SCHEMA_DIR allows to specify a single absolute path. It also has a default value - /schemas - which is only used when that directory actually exists.
HCMS_DEFAULT_SCHEMA_PATH allows to specify multiple absolute paths, separated by a colon : (just like UNIX/Linux PATH variable). Since no escaping is available, no paths with : in it can be accepted. This variable has no default, and empty paths and non-directories are simply ignored.

Satellite certificate

You may need to set these variables if you're using a centrallized Logging system with a builtin certificate authentication. Otherwise, they are completely optional. The container variableSATELLITE_CERT allows to specify a custom satellite certificate in PEM format (unencrypted).

Without those variables, the normal workflow would be the following. On start, a new temporary certificate is automatically created and signed by the SATELLITE_KEY private key. This is sufficient, because the actual content of the certificate is not checked in this default workflow.

Server connection

Default setting

By default, the certificate of the server provided in the SATELLITE_SERVER variable is not validated. The reason is that, in our experience, most of the time a self-signed certificate is used for the FRMIS connection. This certificate is automatically created upon server installation.

Enforcing server certificate check

Warning only enable this check if you did install a correct certificate on the server! Otherwise, for a self-signed certificate, such a validation will fail.

The certificate check is enab;ed by setting the SATELLITE_VALIDATE_SERVER variable to true .