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:
Download the CLI client -
censhare-HeadlessCMS-CLI-*.tgz- from the Download Portal.Extract the archive, it always contains just a single file.
Enable executable flag by running the following in the folder where you extracted it:
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.
./hcms -s frmis://<server-host>:30546/corpus.RMIServerSSL -u <username> configuration create <id>
or, on the same machine:
./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.
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.
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:
./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
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 |
|---|---|
| Makes sure that latest JDK/Linux security updates are in the result image. |
| Will tag the image. It is recommended that the latest images are tagged with the |
| 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
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 |
|---|---|
| Comes before each of the variables required to connect to the censhare Server: |
| Provides the port on which the Headless CMS is accessible; this port must be free. Example: |
| 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 |
|---|---|
| Starts the container in the background. |
| Provides a proper storage for database and local file storage. See the Volumes section for more details. |
| Ensures that the container is automatically started when the host system reboots for any reason. |
| 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.
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:
curl -s http://localhost:18888/hcms/v2.0/entity
Check the logs
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.
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.
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.
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}