Installation tutorial

Installation walkthrough for censhare Server, the database, required censhare tools, the censhare clients and authentication management with Keycloak.

Introduction

Besides the censhare Server, you must set up additional components to enable the communication between the censhare Server, Keycloak, and the censhare clients. 

Prerequisites

You should be familiar with:

• How to administrate Keycloak

• How to install and update RPM packages

• How to administrate services that run with systemd. systemd is used to run the relevant services. systemd is a system and service manager for Linux operating systems. For more information, see Manage censhare services with systemd.

Steps

Prepare for installation with RPM

Ensure that you have an account to access the censhare repositories. In case you don't have an account, create a ticket to the censhare Service Desk. censhare will create the account and provide you with the necessary credentials.

For more information, see Prepare installation with RPM.

Add repositories

For the code samples, replace USER and PASSWORD with your the credentials that you received from the censhare Service Desk.

Add the repositories for the RPM packages to the system:

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

2. If no repository for censhare Server exists, create it with suffix repo. For example: censhare-server.repo
   
   

   CODE

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

3. If no repository for the censhare tools exists, create it with suffix repo. 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

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

Check the installation packages

For more information, see Installation packages.

Install censhare Server 

Install or update 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

Install the database

You can use PostgreSQL or Oracle databases.

1. Set up the database server and create the database. If you already have a running censhare instance, skip this step.

   • PostgreSQL

   • Oracle

Create database user and tables

The censhare-Server RPM includes scripts to initially create a database user and the initial database tables. To create the user might differ in your environment, the provided script is just an example. The database tables should be created within that database user.

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

Create database user and tables for PostgreSQL databases

SQL scripts can be found at the following place.

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

Execute them from your SQL Client like in this example

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

Create database user and tables for Oracle databases

SQL scripts can be found at the following place. Please adapt create-user.sql  according to your needs (e.g. Tablespace name, Username, Password, Datafile location)

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

Execute them from your SQL Client like in this example

sqlplus / as sysdba @/tmp/create-user.sql sqlplus corpus/corpus @/tmp/postgresql-create-db.sql

Systemd and init services configuration

You need the systemd or init services to start, stop, and restart, etc. censhare server and the censhare service client. For more information, see Manage censhare services with systemd.

Initial server configuration and start

If you set up the censhare Server for the first time, follow the steps in Initial censhare Server configuration.

Start the censhare server, for example with this command:

sudo systemctl start censhare.server

After an 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 (2022.1) Logging.

Test REST API

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

Install or update censhare Service 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.

For an initial installation, see Install censhare Service Client.

censhare Service Client configuration

If you have not installed the censhare Service Client on your computer, follow the  Install Service Client guide.

1. Configure the censhare Service Client with the following commands:

   CODE

   ./service-client/serviceclient.sh setup 

   • $ User for autologin [service-client]:

   • $ Password for autologin: create a random password or use the password from the database

   • If the serivce client is locally installed, use:
     $ Url in hosts.xml [frmi://localhost/corpus.RMIServer]:
     If the service cient is not locally installed, use:
     $ Url in hosts.xml [frmi://localhost/corpus.RMIServer]: frmi://masterserverip/corpus.RMIServer

   • $ Name in hosts.xml [localhost]:

   • $ Do you want to update the entries? [Yn]:Y
     Leave all other options as default. The options depend on the desired services or configuration.

2. Start the Service Client with the following command:

   CODE

   systemctl start censhare.serviceclient

3. To update to the latest available version into the censhare-server repository, run:

   CODE

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

Install Keycloak

Keycloak is used as external authentication provider. If you already have a running Keycloak installation, skip this step. 

If you need to install Keycloak, go to the location where you installed censhare:

rpm -i keycloak-16.1.1-2.el7.x86_64.rpm # or yum install --enablerepo="censhare*" keycloak # or yum update --enablerepo="censhare*" keycloak

For more information, see Install Keycloak and Configure Keycloak.

Install the censhare tools

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. 

Install Cloud Gateway

The Cloud Gateway is used to route the incoming requests from the web browser.

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.

rpm -i censhare-core-cloud-gateway-1.0.44-0.noarch.rpm # or yum install --enablerepo="censhare*" censhare-core-cloud-gateway

Install Static Resource Server

The Static Resource Server distributes webpack bundles.

Due to a known issues we are currently using this version:

rpm -i censhare-static-resource-server-2.0.43-0.noarch.rpm # or yum install --enablerepo="censhare*" censhare-static-resource-server

Install or build and release weppack bundels

For more information, see Initial configuration and (2022.1) Build, release & deploy bundles.

Install or update the censhare clients

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 in Install censhare clients to install and configure the clients.

Connect clients to the censhare Server (hosts.xml)

The first installation of a censhare client requires communication parameters to access the censhare Server. Define the communication parameters in a hosts.xml file. Install the hosts file in the correct location before the initial launch of the censhare Client. For more information, see The hosts.xml file and Client Preferences. 

If you install a censhare client on multiple computers, distribute the hosts.xml to the required computers to ensure consistency. Do not set communication parameters individually on each computer. 

When the censhare client cannot locate a valid hosts.xml file, a dialog to create a host definition opens. The censhare client generates a hosts.xml file from the host name and connection string (URL) that you enter in the dialog.

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.

Install optional services

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

rpm -i censhare-google-ai-1.1.2-0.noarch.rpm # or yum install --enablerepo="censhare*" censhare-google-ai

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

rpm -i censhare-social-media-1.0.3-0.noarch.rpm # or yum install --enablerepo="censhare*" censhare-social-media

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

rpm -i censhare-core-mail-0.4.4-0.noarch.rpm # or yum install --enablerepo="censhare*" censhare-core-mail-0.4.4-0

Check installed packages

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

Next steps

1. Configure Keycloak

2. Carry out the initial configuration of the server and the tools.