Skip to main content
Skip table of contents

Main steps of HCMS Docker installation

This article contains the most essential steps for bringing the HCMS up and running. This is a basic minimum which usually requires some adaption depending on your general setup. Please feel free to read this article to the end and check these two additional ones before proceeding with the actual installation:

The necessity of customizations and other changes is to be judged on a case-by-case basis.

1 - Get the Command Line Tool

Detailed documentation about the hcms CLI is avalaible here. Installation:

  1. Download the CLI client - censhare-HeadlessCMS-CLI-*.tgz - from the Download Portal.

  2. Extract the archive, it always contains just a single file.

  3. Enable executable flag by running the following in the folder where you extracted it:

CODE
chmod a+x hcms

2 - Create the HeadlessCMS configuration on censhare Server

For this, you will need to connect to the censhare Server, so make sure you have the correct host name and credentials at hand.

A new HeadlessCMS configuration is created by the command configuration create. This command has many options: you can check them by adding --help or in the reference documentation. For installation purposes, you only need to supply one argument: an id for this configuration. It can be any non-empty string that is also valid part of a file name.

CODE
./hcms -s frmis://<server-host>:30546/corpus.RMIServerSSL  -u <username>  configuration create <id>  

or, on the same machine:

CODE
./hcms -s frmis://localhost:30546/corpus.RMIServerSSL  -u <username>  configuration create <id>  

Note that unless the local host is used, you will be asked for a password of the specified user each time the tool is invoked.

3 - Note the output for the further steps

Note If you use managed Docker containers, e.g., managed through Kubernetes or AWS ECS service, this step can be skipped.

The Docker container will require the configuration group id and certificate to connect to the censhare Server. The values should be taken from the configuration you created.

Upon creation, the configuration is printed to the console in the YAML format. The group id can be found in the groups:id property. The private certificate is saved as a .pem file in the current directory. Please move it to a safe place.

Below is an example of the console output - i.e., the complete configuration - created with the id sample-01. The group id is sample-01:default1.

CODE
key: sample-01
name: sample-01
write_channel: root.hcms.
read_channels:
  - root.hcms.
domain: root.
domain2: root.
no_new_masterdata: true
update_new_version: false
forwarded: false
storage:
    type: local
authorization_providers:
  - type: basic
    users:
      - name: admin
        password: n),3*$Jr|
        roles:
          - '*'
groups:
  - id: sample-01:default1
    name: sample-01:default1
    certificate:
        subject: CN=sample-01:default1
        valid:
            from: 2019-05-22T06:32:50Z
            until: 2119-05-22T06:32:50Z
        algorithm: SHA256WITHRSA
        issuer: CN=sample-01:default1
        serial: 016ade3e0f44
        signature: 0c5c2e161d3ebe8920e283bab763cdca0061acee2453a2de3f16d8b6380a659e550d4405cdbd3ee7ed97da175e440748851647ef7da659e2defd11d7f0c2d34eb49b662b3ce98f482c1abbf9d74d1b04ead13c3421b783f3aad699f2b68fca294a86b84e0cb930a36c6f8ee96edf9cb4cabff91bfc7d7463d5e062469c032e3c2b851785e454889514de94d4f13766d9ee2e10a39920b1dc4e20674fc655ffd247596dd9b5dfae65ed38aad47f3f4e6afa341d6c9ba9edadb476561e35aab7fcc240590d2431db0bf0b79fb3f0ccfb7e735f45b8e6e7e61db3b73ea1da1717a125fa946e88f1ec19d00d680831dc90fabd34db2cd6e4bfcdc8f5ef5b4fad7212
        pem: |
            -----BEGIN CERTIFICATE-----
            MIICujCCAaKgAwIBAgIGAWrePg9EMA0GCSqGSIb3DQEBCwUAMB0xGzAZBgNVBAMT
            EnNhbXBsZS0wMTpkZWZhdWx0MTAgFw0xOTA1MjIwNjMyNTBaGA8yMTE5MDUyMjA2
            MzI1MFowHTEbMBkGA1UEAxMSc2FtcGxlLTAxOmRlZmF1bHQxMIIBIjANBgkqhkiG
            9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlhOd0IODsSuP6HGqORFToNDBK/SrocBbIOUK
            EIVVDb90tnfQK8eP4MbgYNon0Vsl6u9nUdMA30izFGJcYURV5Q+h04sk4nhjribe
            hYH2JLLulmeKklaJ9Vq0/v1BbQVeQi/zAV6gWZVmaltgmJXnMerVftGnqhekvjM9
            9OaiBE86KiJZr//vIgo45G9tFunp1+pkTC7A8LSUw7+kXpp4cYXpl3LE43O4aD/c
            cTWVx2NbUKNk1T6Vu4gDwQgB7fXaA23J/IMmyi0euwWnYW7tjOd/FkdJu3utQ6Vy
            4psLrPcUwOI8WTSC+Vxf2ofMbi8mV8fEqcYZcpo+852lsy+ePwIDAQABMA0GCSqG
            SIb3DQEBCwUAA4IBAQAMXC4WHT6+iSDig7q3Y83KAGGs7iRTot4/Fti2OAplnlUN
            RAXNvT7n7ZfaF15EB0iFFkfvfaZZ4t79EdfwwtNOtJtmKzzpj0gsGrv5100bBOrR
            PDQht4PzqtaZ8raPyilKhrhODLkwo2xvjulu35y0yr/5G/x9dGPV4GJGnAMuPCuF
            F4XkVIiVFN6U1PE3ZtnuLhCjmSCx3E4gZ0/GVf/SR1lt2bXfrmXtOKrUfz9Oavo0
            HWybqe2ttHZWHjWqt/zCQFkNJDHbC/C3n7PwzPt+c19FuObn5h2ztz6h2hcXoSX6
            lG6I8ewZ0A1oCDHckPq9NNss1uS/zcj171tPrXIS
            -----END CERTIFICATE-----

In this example, the file has been saved with the file name sample-01:default1.pem.

You can set these values as variables like in the command below. You will need to copy the entire content of the .pem file (not only the key itself!). Also, you may want to pass the censhare Server RMI URL to a local variable just for convenience.

CODE
export SATELLITE_SERVER=frmis://censhare1.local:30546/corpus.RMIServerSSL
export SATELLITE_ID=sample-01:default1
export SATELLITE_KEY="
-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCWE53Qg4OxK4/o
cao5EVOg0MEr9KuhwFsg5QoQhVUNv3S2d9Arx4/gxuBg2ifRWyXq72dR0wDfSLMU
YlxhRFXlD6HTiyTieGOuJt6FgfYksu6WZ4qSVon1WrT+/UFtBV5CL/MBXqBZlWZq
W2CYlecx6tV+0aeqF6S+Mz305qIETzoqIlmv/+8iCjjkb20W6enX6mRMLsDwtJTD
v6RemnhxhemXcsTjc7hoP9xxNZXHY1tQo2TVPpW7iAPBCAHt9doDbcn8gybKLR67
Badhbu2M538WR0m7e61DpXLimwus9xTA4jxZNIL5XF/ah8xuLyZXx8Spxhlymj7z
naWzL54/AgMBAAECggEBAITO3z2C5KuIrVU6ITVXS/ZoRkorvybpHrvBdGKiW15L
K3G+HY5gj8aOuEl9RPdT/f4l1fznCUKPB0rmsHGzE4AdkUuvOvjfKPcYlpr3I2fe
oJyhDFPsGTHzD3EHlTpxIbTY0edIYgZk27kLHDRrk6js8/nCduli+vsGRbHP11iP
mR5p6NlNyuLF6H8fPWNfLbrCXbqmyqzL2LM5lc9yHF5nXv3kQ92xHtXWWoVGp/st
iEUrUqPW5SRN2FHGW1e6YVDPaCBJCwKiuh5QD84jrkmwiGjloMq+QVMpkvfQVsnW
N8CmqSIOMoJFL5WAjcSZk+CRx99zVaSQI4qCMexI6uECgYEAyEJ+75l5L4qDsS57
d2RsDcoTVldJbJ3l1QO9jwh/CbKT60xJpOG1gC8HxeP5oYB1L9Cuj8QvpoVdv3p0
xlDDNiBGJDe2dERdCrEV7q5hyG4B5QKNXHCdXeH5uicyx1JZ9gJ3OHmChGsCJ6j4
DxciRHkFIDE33LsyqHmEJmTXKLUCgYEAv9lSw2XBr0Haazn4kNmdnlqlGjkruDUd
uC32SMhTojrJ0aKQJG4PhmSYeQXkjK3OtWtsfZC1Dx7GXTVLnRX1vRquWBB4P/y0
CV6o6PZXlRvvkYZpxvDuUvon/ttr4AVPsJcxSdxO53ojH5YdMCwPVZ2wb9Bq1M8b
+5DVV3rcx6MCgYA1YryyJQjQaq2my0xwzJ2do3Q6PTS+tu0xNzkOa2ZqcGfMf17W
jLE1BdSdpaPDsRoMcCZI/zTwwHb4d62vvJH92Oa5+vwxzJO9KO4+3dAFfYYVxfNn
ZEIfaAGJ5a88wbBny8p6jLIFmP1PE1VluHYTKOv75AMPXfwoO5TGI3XUTQKBgBoP
JQTRn5t0sHx8JV1XkedenKqRNXUSEfVgmOGOBH42yg8lq7qnEIjKxUM7H65UNY3D
B7uOmmlxXrRudtThlL2ZEDF6Gztl0far2vm57G+emc4Emf2h4F15CVG+8Eo/rnFo
OBO2Tyl2F6tEsrZGZdbVUo/9mWVKtJxZMgFt+OtNAoGBAMYJCvWgBNJ7LfwL5fx1
zg6SkzLdzYTzAcqxejKmN4r0QQXU+d4sTFM8sHpqb8OIep0aSl6+vN92zyyJGT4x
sxCOubGGL8tWV1vNFz3eXLVh0EvBdVZbyA+91PcTMmtSdxiFc4Q2NNm0G8qW2E34
Y2Vaz7ZbCRp9+Tke2zEOxYHl
-----END PRIVATE KEY-----
"

If you did not save or lost the .pem file, you need to generate a new key-value pair for the certificate by running the following command:

CODE
./hcms -s frmis://localhost:30546/corpus.RMIServerSSL  -u <username>  group update <id> --new-certificate  

4 - Get the latest HCSM Docker image

The latest HCMS Docker image (censhare-HeadlessCMS-Docker-*.tgz) is available on the download portal as a .tgz archive: censhare-HeadlessCMS-DockerImage-<<version>>-b<<build-number>>.tgz.

Note If you are using Safari, you need to use the right-click menu to download the file since Safari unpacks it automatically which we do not want.

For this, on the Download Portal:

  • Click on the item you need

  • Right-click on "Master"

  • Click on "Download linked file"

At last, extract the archive content

CODE
tar zxvf censhare-HeadlessCMS-DockerImage-<<version>>-b<<build-number>>.tgz

5 - Build the image

Options

While building the image, we recommend using some additional options, but they are not mandatory.

Option

What it does

--pull

Makes sure that latest JDK/Linux security updates are in the result image.

-t

Will tag the image. It is recommended that the latest images are tagged with the latest tag. For cloud installations, you may need to set the tag that is specified by the cloud provider. Please refer to the third-party official documentation.

-f

Allows to specify the build definition file. This may help to avoid a nasty Docker bug that may cause Docker to build an old version instead.

Complete docker build command

CODE
docker build --pull -t satellite-hcms:latest censhare-HeadlessCMS-DockerImage -f - <censhare-HeadlessCMS-DockerImage/Dockerfile>

6 - Start the container

Mandatory options

To start the HCMS Docker container correctly, you need to add the following options to the docker run command.

Option

What it does

-e

Comes before each of the variables required to connect to the censhare Server: SATELLITE_SERVERSATELLITE_IDSATELLITE_KEY

-p

Provides the port on which the Headless CMS is accessible; this port must be free. Example: -p <publicport>:8080.

--ulimit

Ensures that Headless CMS does not run out of file descriptors. See the corresponding section for more details.

Optional options

In addition to the mandatory variables, you can steer your container using the following options.

Option

What it does

-d

Starts the container in the background.

-v

Provides a proper storage for database and local file storage. See the Volumes section for more details.

--restart unless-stopped

Ensures that the container is automatically started when the host system reboots for any reason.

-n or --name

Gives a human-readable name to your container which is helpful for checking its logs etc. later.

Complete docker run command

Below you will find the complete command with all options and some sample values. Please replace the values with the correct ones.

CODE
docker run -d --name sample-01 --restart unless-stopped \
    -p 18888:8080 -v /opt/corpus/censhare-Satellite/data --ulimit nofile=32768:32768 \
    -e SATELLITE_SERVER -e SATELLITE_ID -e SATELLITE_KEY \
    satellite-hcms:latest

7 - Check the container

Check if the container started correctly using the following methods.

By HTTP GET request

Use the following format for the call: http://localhost:<publicport>/hcms/v2.0/entity

Example cUrl call:

CODE
curl -s http://localhost:18888/hcms/v2.0/entity

Check the logs

CODE
docker logs -f <containername>

If the startup was correct, you will observe the following messages.

  • This kind of message indicates that the satellite did connect to the application and received the data from its assigned configuration group.

CODE
2018.06.29-15:52:30.111 INFO  pool-3-thread-2 c.c.s.d.impl.DeployerServiceImpl  - executing updates={
        config state=INSTALL   id=asset:14928 version=9    instance_id: hcms                                  factory_pid: com.censhare.oc.hcms.service.impl.HeadlessCMSServiceImpl
        config state=INSTALL   id=asset:14929 version=9    instance_id: hcms                                  factory_pid: com.censhare.oc.datastore.DataStoreService
        config state=INSTALL   id=asset:14927 version=9    instance_id: hcms                                  factory_pid: com.censhare.oc.webserver.impl.WebServerImpl
}
  • Such a message indicates that the datastore synchronization is active.

CODE
2018.06.29-15:52:30.616 INFO  DataStoreConnectionCheck (hcms-datastore) c.c.o.d.i.synchronisation.Pipeline  - hcms-datastore, #A:    unknown ->           ,   unknown   ( speed: ??  ) -> DB Com.: to mod./add:     0, to del.:     0, modified/added:     0, deleted:     0 -> Change-Events: polls:   0, events:   0, duration:     0
  • And such a message indicates that the webserver did start up and opened the port. The port in the log is not necessarily the same as the public one. This is not an error.

CODE
2018.06.29-15:52:30.841 INFO  CM Configuration Updater (Update: pid=com.censhare.oc.webserver.impl.WebServerImpl.41c6e20c-0fe5-47ad-b5f4-70d7c0bd9107) o.e.jetty.server.AbstractConnector  - Started ServerConnector@33488cbe{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.