A complete walkthrough of a censhare system installation, with the focus on installing the RPM packages.

Prerequisites

  • You should be familiar with systemd. systemd is a system and service manager for Linux operating systems and is used to run relevant services.
  • You need credentials to access censhare RPM repositories.
    • In case you don't have them, create a ticket with the censhare Service Desk. censhare will create your account and provide you credentials.

Steps

Steps are provided in such an order that reflects their dependencies. This helps you to avoid problems with any missing components when you proceed to the next step.

Some of the instructions are provided in separate tutorials. Please keep the main tutorial open and go back to it once you are finished with other instructions to follow the specified order.

Step 1 : Add repositories

When you use repositories in your system, dependencies get resolved directly from there.

Every minor version of censhare-Server and censhare-Service-Client has their own RPM repository, so you can always receive the latest bugfix release for your censhare version in use. If you want to update to a later minor/major version, you can just change the URL in your configuration.

In order to have all needed tools at your hand, there is a separate repository, that acts independently from which censhare version you are using. It helps you to install all additional tools, the latest image tools and scripts you need to run censhare.

Add the repositories for the RPM packages to the system:

The GPG key file name is not a placeholder. Use it as it is. 


  1. Go to /etc/yum.repos.d/

  2. If no repository for censhare Server exists, create it. Use the .repo suffix in the repo name. For example: censhare-server.repo

    [censhare-server] 
name=censhare-server 
baseurl = https://USER:PASSWORD@rpm.censhare.com/censhare-release-rpm/stable/censhare/2023/1 
enabled=0 
gpgcheck=1 
gpgkey = https://USER:PASSWORD@repos.censhare.com/6CAE093C.pub
    CODE

  3. If no repository for the censhare tools exists, create it. Use the .repo suffix in the repo name. For example: censhare-tools.repo 

    [censhare-tools] 
name=censhare-tools 
baseurl=https://USER:PASSWORD@rpm.censhare.com/tools-release-rpm/ 
enabled=0 
gpgcheck=1 
gpgkey=https://USER:PASSWORD@rpm.censhare.com/public/6CAE093C.pub
    CODE
  4. Optional: add a pre-release repo 

Prereleases (alpha, beta, pre, release candidate) will be distributed with an own repository, so you only receive updates to pre-releases if you add the following configuration to our RPM repositories.

[censhare-tools] 
name=censhare-tools 
baseurl=https://USER:PASSWORD@rpm.censhare.com/tools-release-rpm/ 
enabled=0 
gpgcheck=1 
gpgkey=https://USER:PASSWORD@rpm.censhare.com/public/6CAE093C.pub
CODE


In the above configuration, the censhare repositories are disabled: the parameter enabled is set to 0.

This is done on purpose, so it is save to do updates for system packages, since packages from the censhare repositories are not going to be used.

Step 2: Import GPG key

Import the GPG key into your system. It is required to verify your downloads.

rpm --import https://USER:PASSWORD@rpm.censhare.com/public/6CAE093C.pub
CODE

(Optional) Step 2.1: download the installation packages

using yum is recommended

If you are going to use yum commands, you can skip this step, as yum will download and install packages automatically, including their dependencies.

rpm commands are given for reference. They won‘t download neither the packages, nor their dependencies. They only do the installation.

If you need to install only selected packages, you need to download the packages manually, and then use rpm commands. Please check this article that provides URLs for downloading every necessary component. 

Step 3: Install censhare Server 

Install the latest available version in the censhare-server repository:

rpm -i censhare-Server-<<version>>-<<buildID>>.0.noarch.rpm 
# or yum install --enablerepo="censhare*" censhare-Server 
# or yum update --enablerepo="censhare*" censhare-Server
CODE

Step 4: Configure censhare Server

Please refer to the Initial censhare Server and database configuration for the exact instructions.

Step 5: Install the database

You can use PostgreSQL or Oracle databases. Please download any of them from the official 3d-party download portals and install following their official documentation.

Step 6: Configure the database | Create database user and tables

How to create users might be different for your environment. The provided scripts are just examples. The database tables should be created with that database user.

All example scripts are included in the censhare-Server RPM and can be found in /opt/corpus/css/database/ folder after the installation.

  • For the Postgres database: 
/opt/corpus/css/database/postgresql-create-user.sql 
/opt/corpus/css/database/postgresql-create-db.sql
CODE
  • For the Oracle database: 
    /opt/corpus/css/database/create-user.sql 
/opt/corpus/css/database/create-db.sql
    CODE


Execute them from your SQL Client like in these examples. Please adapt create-user.sql  according to your needs (e.g. Tablespace name, Username, Password, Datafile location):

Run Postgres scripts

psql -U postgres -f /tmp/postgresql-create-user.sql 
psql -U corpus -f /tmp/postgresql-create-db.sql
BASH

Run Oracle scripts

sqlplus / as sysdba @/tmp/create-user.sql 
sqlplus corpus/corpus @/tmp/create-db.sql
# or sqlplus corpus/corpus @/tmp/create-db-enterprise-edition.sql
CODE

Step 7: Check the database configuration

Check the database setup as follows, for example:

[corpus@censhare-CentOS7 ~]$ CheckJDBC.sh
Starting JDBC check
using oracle JDBC jar file: 'app/common/lib/ojdbc8-18.3.0.0.jar'
using PostgreSQL JDBC jar file: 'app/common/lib/postgresql-42.3.3.jar'
java -Djava.security.egd=file:///dev/urandom -cp bin/censhare-launcher.jar:app/common/lib/*:app/common/lib/ojdbc8-18.3.0.0.jar:app/common/lib/postgresql-42.3.3.jar com.censhare.server.client.CheckJDBC master
Jul 13, 2022 4:59:28 PM com.censhare.server.config.ConfigResolver init
INFO: Using default config dir: /opt/corpus/censhare/censhare-Server/app
Jul 13, 2022 4:59:28 PM com.censhare.server.config.ConfigResolver init
INFO: Using custom config dir : /opt/corpus/censhare/censhare-Custom/censhare-Server/app
Jul 13, 2022 4:59:28 PM com.censhare.server.config.ConfigResolver init
INFO: Using runtime config dir: /opt/corpus/work/runtime.master
Jul 13, 2022 4:59:28 PM com.censhare.server.config.ConfigResolver refresh
INFO: Refreshing last changes
Jul 13, 2022 4:59:29 PM com.censhare.server.config.ConfigResolver scanConfig
INFO: scanned file:///opt/corpus/censhare/censhare-Server/app/ in 130ms
Jul 13, 2022 4:59:29 PM com.censhare.server.config.ConfigResolver scanConfig
INFO: scanned file:///opt/corpus/censhare/censhare-Custom/censhare-Server/app/ in 3ms
Jul 13, 2022 4:59:29 PM com.censhare.server.config.ConfigResolver scanConfig
INFO: scanned file:///opt/corpus/work/runtime.master/ in 23ms
Jul 13, 2022 4:59:29 PM com.censhare.server.config.ConfigResolver refresh
INFO: Refreshing configuration for url: file:services/database/
Jul 13, 2022 4:59:29 PM com.censhare.server.config.ConfigResolver refreshFromDefaultOrCustomScanner
INFO: Found 8 config changes.
Connecting to database with user 'corpus' and url: jdbc:postgresql://10.42.74.174:5432/corpus
Connecting to database with properties: {oracle.jdbc.FreeMemoryOnEnterImplicitCache=true, oracle.jdbc.TcpNoDelay=true, user=corpus}
Connected!
SQL test successful. Found 0 parties.
database.version: 2022.1.0.0000
successfully done.
CODE
Step 8: Start the censhare Server

sudo systemctl start censhare.server
CODE

After the initial setup, it can take up to 15 minutes for the server to start. During the startup you can monitor logs within /opt/corpus/work/logs  directory. For more information, see Monitor and log censhare and Logging (partner login required).

Step 9: Test REST API

curl http://localhost:9000/ws/rest/service/webserver/rest/csLocale -u censhare
CODE

Step 10: Install and configure Keycloak

Follow the instructions on those two pages:

If you already have Keycloak and just need to update, look into this section: Upgrade Keycloak.

Step 11: Install censhare tools | Cloud Gateway and Static Resource Server

  • The Cloud Gateway is used to route the incoming requests from the web browser. 
  • The Static Resource Server distributes webpack bundles.

The censhare-tools are updated continuously. Check the censhare-product/censhare-Server/redistributed.txt of your product delivery to find out which version you should use. 

The following script simplifies the installation by taking the version from the redistributed.txt: 
# Install Cloud Gateway in the right version
yum install $(grep cloud-gateway /opt/corpus/css/redistributed.txt | sed 's/.rpm//') --enablerepo="censhare*"
# Install Static Resource Server in the right version
yum install $(grep static-resource-server /opt/corpus/css/redistributed.txt | sed 's/.rpm//') --enablerepo="censhare*"
# Install ALL services in the right version (just in case you also want google-ai, social-media and core-mail as well)
yum install $(for i in $(cat /opt/corpus/css/redistributed.txt ); do echo ${i/.rpm/}; done) --enablerepo="censhare*"
# If you want only update to the right version, in case you already have them installed
for i in $(cat /opt/corpus/css/redistributed.txt ); do rpm -q ${i/-[0-9]*.*/} && yum update --enablerepo="censhare*" ${i/.rpm/}; done
BASH

Update installations may require additional steps due to the change in package naming from cloud-gateway to core-cloud-gateway. If your installation is affected, follow these steps.

For separate installations, see instructions below, but remember that they are just given for reference. When you use the script above, you do not need to install cloud gateway and static resource server one-by-one.

  • Install Cloud Gateway
rpm -i censhare-core-cloud-gateway-<<version>>-<<buildID>>.0.noarch.rpm 
# or yum install --enablerepo="censhare*" censhare-core-cloud-gateway
CODE
  • Install Static Resource Server
rpm -i censhare-static-resource-server-<<version>>-<<buildID>>.0.noarch.rpm 
# or yum install --enablerepo="censhare*" censhare-static-resource-server
CODE

Step 12: Configure CGW and SRS

Please refer to the instructions provided in this article: Initial configuration for CGW, SRS, and additional services.

Step 13: Install or build and release webpack bundles

mkdir /opt/webpack
curl --user repo-user https://rpm.censhare.com/artifactory/webpack-release/2023.1.0/webpack-2023.1.0.tar.gz | tar -C /opt/webpack -xzf -
BASH

(Optional) Step 13.1: Image relocation (branding and favicon images)

For upgrade installations from a censhare release 2021.1.1 or below, you need to relocate your images to work with censhare.

Location 2021.1.1 or below

Current location

censhare-Client5/web/img 

censhare-Client5/web/src/assets/image

Step 14: Install or update censhare clients and connect them to the censhare Server

  • The censhare Client is the censhare desktop application for users.
  • The censhare Admin Client is the administration instance for system administrators and solution developers. From the censhare Admin Client, you can access the censhare Server and database settings and configurations. 

Follow the steps from the Install censhare clients tutorial.

Step 15: Install or update censhare Render Client (optional)

The censhare Render Client is an optional component and is installed as a server in the censhare ecosystem. The censhare Render Client is required to use the fully integrated functionality of desktop publishing and print production with censhare Web. For more information, see censhare clients.

Step 16: censhare Service Client installation and configuration

Please refer to the instructions provided in this article: Install Service Client guide.

Step 17: Install optional services

Check the censhare-product/censhare-Server/redistributed.txt of your product delivery to find out which versions are the latest for these services. 

Install Google Cloud AI. For more information, see Google AI microservice.

rpm -i censhare-google-ai-<<version>-<buildID>>.0.noarch.rpm 
# or yum install --enablerepo="censhare*" censhare-google-ai
CODE

Install Social Media service. For more information, see Installation details.

rpm -i censhare-social-media-<<version>>-<<buildID>>.0.noarch.rpm 
# or yum install --enablerepo="censhare*" censhare-social-media
CODE

Install Mail Service. For more information, see Install Mail service.

rpm -i censhare-core-mail-<version>-<buildID>.0.noarch.rpm 
# or yum install --enablerepo="censhare*" censhare-core-mail
CODE

Step 18: Check installed packages

List censhare packages

rpm -qa "censhare*" 
# or yum list "censhare*"
CODE

Step 19: Install and configure your load balancer

Similar to the database, the load balancer needs to be downloaded and installed by you following the instructions provided by their provider. We recommend using HAProxy and offer a configuration tutorial that can be found here. 

You can use any other alternative that fits your needs, e.g. Nginx or deploy censhare entirely in AWS and use their native load balancer. 

Possible troubleshooting | censhare Server Webserver service

If you did not use censhare Web Client and/or Keycloak before, the censhare Server Webserver service may be deactivated. In this case, you will see the "connection refused" error:

curl -I -k https://localhost:9443/censhare5/client
curl: (7) Failed connect to localhost:9443; Connection refused
CODE

In all "full" RPM installations, the Webserver service is activated by default. 

To activate it on your installation, do the following:

  1. In the censhare Admin Client, go to Configuration > Services > Webserver and double-click Configuration.

  2. In the Configuration dialog, activate Service enabled and click OK.

  3. You can test if the service is activated using curl:

    curl -I -k https://localhost:9443/censhare5/client
HTTP/1.1 301 Moved Permanently
Date: Mon, 01 Aug 2022 10:06:45 GMT
X-Frame-Options: SAMEORIGIN
Location: /censhare5/client/
Content-Length: 0
    CODE