Prepare installation with RPM

About RPM package preparation.

Prerequisites

Obtain an account to download the RPMs:

• Partners must have a signed Partner contract. In case of doubts, ask our Partner Management.
• Customers must have a signed Project or Support Contract. In case of doubts, ask our Project Management Team or check for an active SLA asset.

RPM repositories

In order to retrieve RPMs, you need access to our RPM repositories. When you use the repository in your system, dependencies get resolved directly from there. You can also download single RPM Files from there. To access these repositories, you need a login and password to download files from there. If you don't have credentials, open a ticket with our Service Desk in order to receive account information. 

All RPMs are signed with a GPG key. To verify your downloads and the repository, you can import the key in your system:

rpm --import https://user:password@rpm.censhare.com/public/6CAE093C.pub

censhare-3rdParty tools repository

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. The following configuration can be used (replace user and password): 

[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

censhare repository

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. The following configuration can be used, just replace user and password  and at the end of the URL you can adjust the version to the one you want to use.

[censhare]
name=censhare
baseurl=https://user:password@rpm.censhare.com/censhare-release-rpm/stable/censhare/<majorversion>/<minorversion>
enabled = 0
gpgcheck=1
gpgkey=https://user:password@rpm.censhare.com/public/6CAE093C.pub

censhare prerelease repository

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. And again, just replace  user  and  password  and at the end of the URL you can change to which version you want to use. 

[censhare-PreRelease]
name=censhare-prerelease
baseurl=https://user:password@rpm.censhare.com/censhare-release-rpm/testing/censhare/<majorversion>/<minorversion> 
enabled = 0
gpgcheck=1
gpgkey=https://user:password@rpm.censhare.com/public/6CAE093C.pub

Install censhare

For RedHat7-Based Linux distributions, there is already a dependency to `java-17-devel` which includes `javac`. If you're running on a different distribution and/or want to use a different JDK version, you can install it and then you have to ignore RPM dependencies on censhare-Server and censhare-Service-Client packages. We recommend using Amazon Corretto JDK.

After you set up the repositories in your Linux Server, the installation is quite simple. The following command will install censhare Server, censhare Service-Client and all needed dependencies you need to have in order to run censhare. censhare Clients (Admin, Client, Render-Client) cannot be installed on Linux with RPM.

yum install censhare-Server censhare-Service-Client --enablerepo="censhare,censhare-PreRelease,censhare-tools"

About the main packages

censhare-Common

It will setup a user  corpus  on your system and create the home directory  /opt/corpus  for the software. It also provides the startup scripts rccss which can be used as an alternative startup method instead of systemd.

censhare-ImageTools

It has all the dependencies to tools that are needed to create image and office previews. So when you install it, it will also require to install LibreOffice-Online, Ghostscript, ImageMagick, wkhtmltoimage and ExifTool. For LibreOffice-Online an own startup service loolwsd will be installed and activated within systemd. Another dependency is censhare-Common, which will be installed via yum as well.

censhare-Service-Client

As dependencies, the packages  censhare-Common  and  censhare-ImageTools  will be installed first. You can install it on the same system with a censhare-Server or standalone on another server. The  censhare.serviceclient systemd serivce will be enabled. The software will be installed below  /opt/corpus  and you can start configure it as user corpus with following command. 

[corpus@server ~]$ service-client/serviceclient.sh setup

censhare-Server

As dependencies, the package  censhare-Common  will be installed first. If you want the censhare-Server to create image previews by itself (recommended only as fallback, if a Service-Client isn't available), you can also install the package  censhare-ImageTools  , but it isn't a required dependency.

The package itself installs the censhare-Server software without any configuration. All links will be created and a  work  directory will be created from the  work-template  . The  censhare.server   systemd service will be enabled.

What the RPM installation does not for you

It does not configure censhare for you! So after installation you have to make configurations for the JVM size, database connection, you also have to set up your PostgreSQL or Oracle database on your own and so on. The RPMs are just installing the software and preparing the environment, so everything is there what is needed in order to run the software.

For further configurations, see  Initial censhare-Server Configuration.

Update censhare

For an update to a new bugfix release, just run the following command, you can do this for censhare-Server and censhare-Service-Client separately. If you want to update to another minor/major version, first you have to change your repository URL like explained before. Be aware, that for minor/major versions also additional steps may be required, such as updating your configuration files. Also keep in mind to have a backup of your Assets and Database, as the RPM may update the Database Schema if necessary, so for a rollback a backup restore may be needed.

yum update censhare-Server censhare-Service-Client --enablerepo="censhare,censhare-PreRelease,censhare-tools"

For a walk-through of the update process, see Updates & Upgrades.

What happens during the update process

1. The state of censhare-Server will be noted and stopped if it is running.

2. The software will be unpacked by the RPM and overrides the current software.

3. The work directory will be synced with changes from work-template.

4. The script  DatabaseUpdate.sh update  will be executed in order to make Database Schema updates. It will log to  ~corpus/work/logs/db-update-<current-date-and-time>.log

5. Files that have been compiled during runtime will be removed

6. censhare-Server will be stared in case it was also running when the update started, otherwise it will remain stopped.

7. Since runtime files has been removed, files will recompile during first startup, which can take up to 15 minutes until the server is fully started and ready.

Uninstall censhare

To uninstall censhare, just run the following command: 

yum remove censhare-Server censhare-Service-Client

This will only remove the software, the configuration files and asset files will remain. If you want to get rid of them you have to remove them manually. If you also want to remove all the dependent packages that have been installed with, you could run this command right after the uninstallation. This will remove all packages where nothing else has a dependency left on:

package-cleanup --leaves --all

Replace an existing censhare installation with RPM

For this you can actually just install the packages on top. Still we recommend to cleanup your old software installation and remove everything, except your configuration and work directory. Just make sure that after the installation of the packages, the files in censhare-Custom will remain below  ~corpus/censhare/censhare-Custom

Install censhare with different user, group and/or home directory

Install on different user/group

Before installing any package, you can set following environment variables on your system

export RPM_CORPUS_USER=corpus 
export RPM_CORPUS_GROUP=corpus 
export RPM_CORPUS_UID=861 
export RPM_CORPUS_GID=861 

If they are not set, the mentioned defaults will be used. You just need to set them, before installing censhare-Common RPM, then these parameters will be saved to /etc/profile.d/censhare.sh and loaded and used for any of the other RPMs.

Relocate installation directory

In order to install censhare to a different directory, it's possible to relocate the package.

If you use relocate, you can only do this with the rpm command, this does not work with yum or zypper.
Once the RPM has been installed with relocation you also have to provide this parameter always when you update with rpm!
Also please be aware to always relocate to the same directory for all your packages (censhare-Common, censhare-Server, censhare-Service-Client), otherwise you could break your installation. For this you need also to already relocate censhare-Common RPM, where this is supported since 1.6. Example command:

rpm -i --relocate /opt/corpus=/home/MyCenshare censhare-Common-1.6-0.x86_64.rpm

Then you can do the same for censhare-Server and censhare-Service-Client. This is not supported for censhare-ImageTools. Example command:

rpm -i --relocate /opt/corpus=/home/MyCenshare censhare-Server-2018.3.0-5758a1.0.x86_64.rpm 
rpm -i --relocate /opt/corpus=/home/MyCenshare censhare-Service-2018.3.0-5758a1.0.x86_64.rpm