4 - Prepare Docker host

The docker-compose.yml expects some special files to exist (mainly with certificates) and several environment variables to be set. They are usually passed via an .env file, which is – for your convenience – created by a special script prepare-env.sh.

Important note for Windows OS: this script is a unix shell script and it must be run via WSL!

1. If you don't have it yet, please install following the Microsoft documentation

2. Open the command line, cd into /deployment/standalone and type wsl.

This script is run as ./prepare-env.sh or bash prepare-env.sh and takes several arguments.

Mandatory arguments

All arguments and the whole configuration is validated; please pay attention to any error messages and fix all problems.

The most important and required options are:

• -s, -i and -k correspond to the three necessary variables required by the HeadlessCMS container for the censhare server connection and authorization:

  • -s is the server URL that you – or your admin – used for registering the HCMS instance and preparing censhare server

  • -i is the satellite id that was generated as part of the HCMS instance registration (see aforementioned instructions)

  • -k is the satellite key (see aforementioned instructions)

• -o must be the correct output channel used by the configured HCMS instance (see aforementioned instructions)

  • Warning: using incorrect values will lead to strange errors, because newly created assets (including the system ones) will be automatically hidden by the server.

• The domain (=the URL) comes at the very end without any argument. The domain must conform to all rules of the DNS domain names and it should be recognized so by a browser, but that's the only requirement. In particular, it is not necessary that the domain exists in any DNS server (and it might be better to actually use one that isn't, to avoid confusion). It is recommended that it actually uses a valid top-level domain; at the same time, the domain should NOT actually exist in any DNS server, to avoid confusion. For example, myname.company.com or local.hcms-client.dev. Single-word (without dot) and non-ascii characters are not recommended.

Technically optional, but usually needed

• -I is the name (full tag) of the hcms-client image that you built before

• -d enables the development mode

  • This is required for all developers who need this setup for local development!

• -j is the JWT you generated upon registering your HCMS instance

  • docker compose overrides the already created configuration, including the JWT token. For development, this is not a problem. If you need the local installation for other purposes, such as testing, demonstration, or validation with your stakeholders, you need to use the token you created. For development purpose, you can let docker-composedo the override.

• -D is the security domain you created before upon registering the HCMS instance (the first domain)

  • If you do not specify the -Dargument, the root. will be set in the local configuration override.

Optional arguments

• -c: your TLS certificate for HTTPs connection. This needs to be prepared in advance and is not part of the current guide. When not available, a self-signed certificate is automatically generated by the preparation script and is later mounted inside the HCMS image by docker compose.

  • If a https certificate is provided via -c option, this domain must match the certificate!

• SMTP values

  • Necessary for registration and/or password reset to work (activation link is sent via email). Without SMTP, new user registration fails with a generic error (HTTP 500 from the backend endpoint). The user, however, is still created and it is possible to activate it using the Java Client: open the user's asset metadata and remove the asset feature labelled "Portal: User Confirmation Key" (censhare:module.oc.portal.user-confirmation-key). See also create an administrator account article for complete instructions.

  • Please run ./prepare-env.sh -h to show all available options.

Complete command

An example for the setup without a local configuration override (with all mandatory and semi-optional arguments):

./prepare-env.sh -s frmis://hcms-client-dev.oc.censhare.com:30546/corpus.RMIServerSSL -i dev1.demo:default1 -o root.hcms.dev1. -k ./dev1.demo:default1.pem -j JWT -d -D root.sampleportal1. -I hcms-client:local  dev1.hcms-client.mycompany.com

When everything is done, the .env file is created with the correct values.

Note: this script creates a number of temporary files. If you need to remove them, just run git clean -fdx . in the directory where it is present. This is handy especially if the previous run failed for some reason.