HCMS installation

This guide describes how to setup a delivery infrastructure for the censhare Headless CMS.

Introduction

In order to support horizontal scalability and high availability the censhare Headless CMS uses its own process, separate from the censhare application server, to drive its REST endpoint. This program is called Headless CMS Satellite.

System Requirements

Delivery Server

Installation

Preparing the censhare Server

Start the censhare Admin Client and connect to the censhare Server. Open the following configurations and make sure that the check box "Service enabled" is checked for the following services on the server. You will connect the Headless CMS Satellite to:

• Configuration/Services/Satellite management service
• Configuration/Services/Online channel data store service

You need to activate the changes by pressing "Update server configuration" and if you are in a multi-application server environment you also need to call "Synchronize remote servers" afterwards.

Creating a Headless CMS Configuration

Switch to the Production Client and connect to the censhare Server. Start the action "Import assets" and point the file chooser to the configuration templates. Afterwards locate from the just imported asset name "HCMS Configuration Group" of type Module/Satellite/Satellite Configuration and click on the chevron to make its child assets visible. Open the "Data Store Configuration" master file by double clicking. Search for the entry:

<output-channels>
  <output-channel name="root.hcms."/>
</output-channels>

and replace root.hcms. with the id of the output channel the project shall be associated with. Output channels are the possible values of the feature "Output channel hierarchy". You can also add a wildcard to the end of the value to include child values (e.g. root.customer.*) or add additional output-channel elements. Save the asset when you are done.

Open the "Headless CMS Configuration" master file by double clicking. Search for the entry:

<schemaregistry resourcekey="schema" outputchannel="root.hcms."/>

The value of resourcekey specifies the resource key the assigned satellites use to identify Headless CMS configuration, such as schemas. Since it is highly recommended that the configuration is not shared between different configuration groups, replace this value with a unique value that represents the project, e.g. censhare-website-live. If such an asset does not exists the instances create it if needed. If an existing configuration is to be reused make sure it is flagged with the same output channel as specified by the neighboring attribute outputchannel. The schema asset is not intended to be edited by the client but only through the REST endpoint. The value of outputchannel defines the primary output channel to be used by this configuration and must be one of the output channels defined in the "Data Store Configuration". Assets created through the Headless CMS REST endpoint is automatically be tagged with this output channel. Save the asset when you are done. Open the "WebServer Configuration" master file by double clicking. Search for the entry:

<connectors>
  <connector port="8080"/>
</connectors>

Replace the value of port with the port the REST interface is reachable by. Check in the asset when you are done.

Adding Delivery Servers

Repeat the steps in this section for each delivery server you want to add to the project.

Install Satellite Software on Delivery Server

Download the latest Headless CMS Satellite installer from the download site. After downloading, copy the installer to the target machine and mark it as executable.

chmod +x censhare-HeadlessCMS-Satellite-Installer-${version}.sh

The installer and the start script Satellite.sh must be executed with the same user that the process will be running under later. It is highly recommended to not run it as root.

./censhare-HeadlessCMS-Satellite-Installer-${version}.sh

The Installer will ask you a couple of questions:

1. Enter the target directory (default /Users/tn/satellite.satellite1): Specifies where the satellite will be installed. Accept default by pressing return or enter a custom path. If the destination folder name starts with satellite. the rest of the folder name is automatically be proposed as the satellite-id in the next step.
2. Enter satellite id (default satellite1): Specifies the id under which satellite will appear in the management ui. Accept default by pressing return or enter a custom id. It is recommended that the satellite id reflects the project, environment and satellite instance (${CUSTOMER_HANDLE}-${PROJECT_NAME}-${SERVER_TYPE}[-${HOST_SPECIFICATION}]), e.g. acme-corporate-website-testing-staging-satellite-1.
3. Enter server (default rmis://localhost:30546/corpus.RMIServerSSL): The RMI-URL of the censhare Server the satellite will connect to. Usually it is the same URL as used by the production and admin client.
4. Use RMI public key authentication? (default 1): Press return to enable public key authentication. The installer will later create a public/private key that will be used to authorize the connection towards the censhare Server.
5. Validate Server SSL Certificate? (default 1):If you are unsure that the necessary setup has been implemented enter 0 and press return.
6. Download & Pin Server Certificate? (default 0): If you are unsure that the necessary setup has been implemented enter 0 and press return.
7. Enter Java home (default ): The JVM used to execute the Headless satellite can be specified here. If no JVM is specified the default environment is used.
8. Start satellite afterwards? (default 1): Enter 0 and press return to prevent the immediate start of the satellite.

Adding the Satellite to the Configuration

Select "HCMS Configuration Group" and start the server action "Satellite create". In dialog window that comes up select "with certificate file" and click "OK". In the next step you are asked to select the certificate. Pick the certificate file satellite.cer from the satellite installation target folder. As result a satellite asset with the attached certificate is created and the corresponding satellite instance will download and activate the configuration of the group. Once a satellite is attached to a configuration group all changes to the group are immediately be propagated to it.

Verify the Satellite Installation

Switch to the command line and navigate to the installation target directory. Start the satellite with bin/Satellite.sh start. You can follow the satellites log in the filelogs/satellite.log. You can observe the following messages indicating the correct startup:

2018.06.29-15:52:30.111 INFO  pool-3-thread-2 c.c.s.d.impl.DeployerServiceImpl  - executing updates={
        config state=INSTALL   id=13708   version=1    instance_id: hcms-datastore                        factory_pid: com.censhare.oc.datastore.DataStoreService
        config state=INSTALL   id=13709   version=1    instance_id: hcms                                  factory_pid: com.censhare.oc.hcms.service.impl.HeadlessCMSServiceImpl
        config state=INSTALL   id=13710   version=1    instance_id: hcms-webserver                        factory_pid: com.censhare.oc.webserver.impl.WebServerImpl
}

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

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

Indicates that the datastore synchronization is active.

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}

Indicates that the webserver did start up and opened the port (8080). The response of the satellite can be tested by accessing the URL <base-path>/hcms/v1.0/schema. E.g.:

curl http://localhost:8080/hcms/v1.0/schema

An empty JSON object is returned.

{}

Starting and Stopping the Satellite

You can manually start, stop or check the if the satellite is running with bin/Satellite.sh start, bin/Satellite.sh stop and bin/Satellite.sh status respectively from the satellite directory.

Starting the Satellite on system startup

If you want the satellite to start automatically in the future, you can use one of the generated start scripts available in the bin subdirectory of the satellite directory.

• systemd based distributions
  • Navigate to the satellite directory as the root user
  • Copy bin/censhare.satellite.<satellite-id>.service to /etc/systemd/system
  • Execute systemctl enable censhare.satellite.satellite-id.service
• Debian/Ubuntu before systemd
  • Navigate to the satellite directory as the root user
  • Copy bin/css_satellite.<satellite-id> to /etc/init.d
  • Execute update-rc.d css_satellite.<satellite-id> default
• RedHat/CentOS before systemd
  • Navigate to the satellite directory as the root user
  • Copy bin/css_satellite.<satellite-id> to /etc/init.d
  • Execute chkconfig --add css_satellite.<satellite-id>