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).
Download archive from the Download Portal, it must be unpacked and made executable.
Unpack by
tar zxvf
; there is only one single file in the archive, calledhcms
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
.
CODE
|
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 -p
argument. 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.
.
CODE
|
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!
CODE
|
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):CODEwrite_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 issampleportal1:default1
:CODEgroups: - 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
).
CODE
|
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.