Manual HCMS Linux Installation

Shows the steps to install the headless cms and the necessary system requirements.

It is recommended to follow the docker based installation. This guide describes how to setup a delivery infrastructure for the censhare Headless CMS by manual installation on Linux systems. 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

censhare Application Server

The Headless CMS can be used with censhare version 2017.1 or later.

Delivery Server

Please note that the installed Java environment must be a full JDK (Java Development Kit). The JRE (Java Runtime Environment) is not sufficient!

• HCMS of version 1.0 to 1.5 (inclusive) required JDK version 8
• HCMS version 1.6 to 3.x require version JDK version 11
• HCMS version 4.0 and higher require JDK version 17

In all cases, the latest patch version is recommended to avoid possible security issues.

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 hcms-configuration-template.censhare-assets. 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 following entry

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

and replace root.hcms. root with a valid value 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 output-channel elements if required. The output channel is used to control which content should be available via the interface, since only assets assigned to one of these output channel values are accessible.

The Admin client can be used to view and edit the list of output channel values available on the system in the Master data/Features section. Search for the feature with the id censhare:output-channel and double-click it. The value list can be found at the bottom of the detail window.

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". Wildcards (*) are not allowed. Assets created through the Headless CMS REST endpoint are automatically tagged with this output channel.

You may configure the default domain used to create assets by setting the optional attributes default-domain and default-domain2 on the element datastore.
When set, they must contain valid and existing domain and domain2 (full pathid). Default ist root..

If you do not want the HCMS to automatically create master data, you can set the optional no-new-masterdata attribute of the schemaregistry element to true.

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 (Satellites)

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 Download Portal. 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/v2.0/schema. E.g.:

curl http://localhost:8080/hcms/v2.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>

Logs

The current log messages can be found in the file logs/satellite.log, older ones in "rotated" files logs/satellite.<date>.log

Internal schema repository (local directory)

Headless CMS by default starts with no schemas and new ones need to be added via the REST API. It is, however, possible to provide schemas directly as files on the filesystem. These files are automatically loaded and compiled on start.

Each schema must be stored as a single file, with its name derived from the schema name: <schemaname>-schema.json or <number>-<schemaname>-schema.json. Examples: image-schema.json or 100-article-schema.json

There is no default directory for these files; it must be manually created and the absolute path provided via environment variable HCMS_DEFAULT_SCHEMA_DIR

Upgrading Delivery Servers (Satellites)

Warning: before upgrading, check whether the new version requires upgrade of JDK (typically from version below 4 to 4.x or higher). If it does, the JDK needs to be upgraded first:

1. Install the new JDK version to the machine (by whatever method appropriate to the distribution).
2. Find the new JAVA_HOME directory.
3. Edit the config.properties file in the satellite directory:
   • Find the line com.censhare.satellite.launcher.Java$home=<old JAVA_HOME> and change the value (after = sign) to the new JAVA_HOME directory.
4. Continue the upgrade process. Note that no shutdown or restart is needed at this point.

The upgrade process is similar to the installation, the beginning is the same:

1. Download the installer and ensure it's executable (see above).
2. Run the installer: ./censhare-HeadlessCMS-Satellite-Installer-${version}.sh
3. Answer the first question by entering the directory of already-existing satellite:
   • Enter the target directory (default /Users/tn/satellite.satellite1):
4. At this point, the installer automatically detects that the satellite already exists and proceeds with upgrade (instead of new installation).
   • It won't ask any further questions, because everything is already know.
   • The satellite can be even running; the installer correctly shuts it down and starts the new upgraded version, as needed.