RPM installation tutorial

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.
- We provide some advice on using systemd in the Manage censhare services with systemd tutorial.
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

Click here for general info on using 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.

Go to /etc/yum.repos.d/

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

CODE

[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

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

CODE

[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

Optional: add a pre-release repo

Why have 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.

CODE

[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

Why enabled=0? | Update OS without updating censhare

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.

CODE

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

(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:

CODE

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

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:

CODE

/opt/corpus/css/database/postgresql-create-user.sql 
/opt/corpus/css/database/postgresql-create-db.sql

For the Oracle database:

CODE

/opt/corpus/css/database/create-user.sql 
/opt/corpus/css/database/create-db.sql

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

BASH

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

Run Oracle scripts

CODE

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

Step 7: Check the database configuration

Check the database setup as follows, for example:

CODE

[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.

Step 8: Start the censhare Server

CODE

sudo systemctl start censhare.server

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

CODE

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

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

:

BASH

# 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

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

CODE

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

Install Static Resource Server

CODE

rpm -i censhare-static-resource-server-<<version>>-<<buildID>>.0.noarch.rpm 
# or yum install --enablerepo="censhare*" censhare-static-resource-server

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

For initial installation or update of uncustomized webpack bundles, just download and unpack the tar.gz archive from the RPM repo specified on this page, for example, https://rpm.censhare.com/artifactory/webpack-release/2023.1.0/.

BASH

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 -

For updating customized webpack bundles, please refer to the instructions provided in this article: https://partner.censhare.com/documentation/censhare-latest/en/developer-guide/getting-started/release-frontend-bundles/build-release-deploy-bundles (partner login required).

(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.

CODE

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

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

CODE

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

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

CODE

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

Step 18: Check installed packages

List censhare packages

CODE

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

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:

CODE

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

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

To activate it on your installation, do the following:

In the censhare Admin Client, go to Configuration > Services > Webserver and double-click Configuration.
In the Configuration dialog, activate Service enabled and click OK.

You can test if the service is activated using curl:

CODE

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