Register HCMS instance

In this part, you will learn how to create the HCMS configuration on the censhare server.
Steps included in this guide suffice for the purpose of installing the HCMS Client Starter Kit locally. For complete information about installing and configuring HCMS, please refer to this article.

Get the hcms administration tool

This tool is not part of Headless CMS installation and does not have to be run on any specific server. Technically, it is just another variant of Java Admin Client and Java Client and can be replaced by these two applications (but it's much more convenient).

1. Download archive from the Download Portal, it must be unpacked and made executable.

2. Unpack by tar zxvf ; there is only one single file in the archive, called hcms

3. Make the file executable chmod a+x hcms

1 - Connect to the server

Warning: Do not use localhost to connect to the server, always use the real hostname or external IP address! Reason: localhost has quite different meaning inside the docker container.
On Mac OS X, the .local namespace is the most convenient way to use the network address; you can see the correct hostname by invoking command hostname.

./hcms -s frmis://<censhare.server.hostname>:30546/corpus.RMIServerSSL -u censhare  

By default, the tool asks for a password of the user specified by -u. The password can be also provided by an environmental variable or even via commandline option, by adding the -pargument. On Mac OS X, the tool actually first tries to obtain password from the Keychain. It is also possible to enter password once and save it to Keychain, by adding option --save-password.

2 - Create necessary security domains

Any existing domain can be used, including the root. domain. However, on this domain, two special subdomains needbe created. For the purpose of this guide, a new domain tree is created by the sample command below: root.sampleportal1..

domain create root.sampleportal1. -n "Sample HCMS Client Starter Kit application"
domain create root.sampleportal1.system. -n "Sample HCMS Client Starter Kit application - system data"
domain create root.sampleportal1.people. -n "Sample HCMS Client Starter Kit application - users"

The first domain (the parent of both system and people) will be needed later in configuration.

Note that this step can be replaced by the standard solution development technique to deliver masterdata (that is, masterdata.xml in the git repository deployed to the server).

3 - HCMS configuration

Create configuration

The following hcms command automatically calls some other commands which, if needed, create missing output channel and enable required services.

Warning: For readability, the command here is split in several lines; the real command must be entered as one long line!

configuration create sampleportal1 
-wc root.hcms.sampleportal1.
--user-tracking true
--domain root.sampleportal1.
--no-new-masterdata true
--forwarded true --forwarded-levels 1
--image-cache-storage-item dic_master --image-cache-max-age 43200 --image-cache-max-size 5000

The first argument (sampleportal1) serves as the configuration id and must be unique on the given censhare server. It can have any value, but using application name (id) is highly recommended as it is easy to memorize. The value of the --domain argument must be the valid (=already existing) security domain from previous step. The two values do not have to be identical!

Output values you need on the further steps

The output of this command will be required on further steps. It is better to save it somewhere for using or passing back to the solution developer later. In case you do not save it, you can always retrieve this output again using the configuration inspect sampleportal1 command. The sampleportal1 is the configuration id that you want to retrieve. Before running this command, you need to connect to the corresponding censhare server.

• In the yaml output printed to the console, you will need to find the following values:

  • The output channel that is created for this HCMS instance. It is required to be one of the "read channels", and the value must be a valid censhare hierarchical identifier, ie starting with root. and ending with a . (dot):

    CODE

    write_channel: root.hcms.demo1.
    read_channels:
    - root.hcms.demo1.
    

  • Satellite group id, usually in the form of <configuration-id>:default1; using the sample invocation above, satellite id is sampleportal1:default1:

    CODE

    groups:
        - id: sampleportal1:default1
        name: sampleportal1:default1
        certificate:
    

• Satellite key, saved to the .pem file in the current directory (its content is not part of the yaml output).
  no output file specified, using default: sampleportal1:default1.pem

  • Warning: Save this file to some safe and secure location, it is not stored anywhere and if lost, its content cannot be recreated!

  • Note that the private key is never directly displayed, unlike the certificate (which contains public RSA key). The certificate is never actually used by this setup, please don't mix them up!

4 - Enable JWT authorization provider

You need to choose some random secret string and configure JWT. For the secret, please avoid using characters that need escaping in some contexts: "'&<>$.

Note that production setup should use really random secrets with at least 512 bits of random information. Since release 1.13, the commandline tool can generate random secret - but using it can be unwieldy when escaping is needed (like in case of docker-compose).

authorization create --jwt sampleportal1 --cookie access_token --cookie-http-only true --secret <secret>

The --cookie access_token --cookie-http-only true argument is crucial for any HCMS Client Starter Kit application to work (this is the name of the shared cookie).

The generated token will be printed to the console. Save it to avoid losing it if you close the terminal window by mistake.