Installation of REWOO Scope

This chapter describes how to install REWOO Scope on a Linux system. In principle, any recent Linux distribution can be used, but the commands may differ from the examples given here.

Debian 12

Requirements

It is assumed that the system requirements are met. In addition, the following things are required:

Debian 12
shell access (e.g. via SSH)
root permissions (e.g. via su or sudo)
Internet access on the Linux server
basic knowledge in using the shell (BASH)

This tutorial does not assume a graphical environment.

Install base packages

Before starting the actual installation of REWOO Scope, all the tools that are needed should be installed. In order for the installation to work properly, we recommend that you perform the following points in the order given here. After the installation is complete, start by checking for any pending updates:

apt update

If there are any pending updates, you should install them using the following command:

apt upgrade

The following basic packages are required for the installation or operation of REWOO Scope and should therefore be installed in advance.

unzip

For unpacking archives.

apt install unzip

Network Security Service - Libraries

apt install libnss3

Perl

For executing various scripts.

apt install perl

ImageMagick

ImageMagick and ghostscript are required for previewing images.

apt install imagemagick ghostscript

To add repositories

apt install software-properties-common

OCRmyPDF

OCRmyPDF adds an OCR text layer to scanned PDF files or images, allowing them to be searched. More information can be found on the official website of OCRmyPDF.

apt install ocrmypdf tesseract-ocr-eng tesseract-ocr-deu tesseract-ocr-spa

ClamAV

ClamAV is a free virus scanner that can be integrated into REWOO Scope to scan documents, email attachments and other files for viruses and malware. More information can be found on the official website of ClamAV.

apt install clamav clamav-update

If SELinux is used, ClamAV must still be allowed to scan all files on the server:

setsebool -P antivirus_can_scan_system 1
setsebool -P clamd_use_jit on

LibreOffice

LibreOffice is required for the preview of Office documents. Here, version 7.6.5 is installed as an example. If you install another/newer version, the respective paths must be adjusted.


wget -c https://download.documentfoundation.org/libreoffice/stable/7.6.5/deb/x86_64/LibreOffice_7.6.5_Linux_x86-64_deb.tar.gz
tar xf LibreOffice_7.6.5_Linux_x86-64_deb.tar.gz
cd LibreOffice_7.6.5.2_Linux_x86-64_deb/DEBS
dpkg -i *.deb
cd -

Note: The link may be outdated. Please check if there is a more recent version for Debian x86_64 on LibreOffice.org before installing.

Java (Corretto JDK)

The REWOO scope server software requires JDK 11. We recommend using the OpenJDK offshoot Corretto from Amazon. Details can be found on the official Corretto website. Add the Corretto repository to the system:

wget -O- https://apt.corretto.aws/corretto.key | sudo apt-key add -

add-apt-repository 'deb https://apt.corretto.aws stable main'

Then install Corretto 11.

apt update; apt install -y java-11-amazon-corretto-jdk

Xvfb X11-Server

This service is required for LibreOffice. Details about Xvfb can be found here. Install the service:

apt install xvfb

Anlegen des Start-Scripts

Create the file /etc/systemd/system/xvfb.service and insert the following content:

[Unit]
Description=xinit - user "rewoo"
[Service]
User=rewoo
Group=rewoo
ExecStart=/usr/bin/Xvfb :14 -nolisten tcp -screen 0 1024x768x24 -fbdir /var/tmp/
ExecStopPost=/usr/bin/killall -u rewoo Xvfb
[Install]
WantedBy=multi-user.target

Activate Xvfb

systemctl enable xvfb.service
systemctl start xvfb

Apache HTTP Server

Installation

apt install apache2

Activate required modules

cd /etc/apache2/mods-enabled
ln -s ../mods-available/headers.load
ln -s ../mods-available/proxy_ajp.load
ln -s ../mods-available/proxy_balancer.conf
ln -s ../mods-available/proxy_balancer.load
ln -s ../mods-available/proxy.conf
ln -s ../mods-available/proxy.load
ln -s ../mods-available/proxy_http.load
ln -s ../mods-available/rewrite.load
ln -s ../mods-available/slotmem_shm.load
ln -s ../mods-available/socache_shmcb.load
ln -s ../mods-available/ssl.conf
ln -s ../mods-available/ssl.load

Configuration

Create the file /etc/apache2/sites-available/rewoo.conf and insert the following code (Replace $IP and $HOSTNAME with your Server data):

<VirtualHost $IP:80>
        ServerAdmin webmaster@$HOSTNAME
        ServerName $HOSTNAME
        RewriteEngine On
        RewriteCond %{SERVER_PORT} ^80$
        RewriteRule ^(.*)$ https://%{SERVER_NAME}$1 [L,R=301]
        ErrorDocument 503 /errorpages/503.html
        ErrorLog ${APACHE_LOG_DIR}/error_log
        # Possible values include: debug, info, notice, warn, error, crit,
        # alert, emerg.
        LogLevel warn
        CustomLog ${APACHE_LOG_DIR}/access_log combined
</VirtualHost>

Create the file /etc/apache2/sites-available/rewoo-ssl.conf and insert the following code (Replace $IP and $HOSTNAME with your Server data):

LoadModule ssl_module modules/mod_ssl.so
Listen 443
<IfModule mod_ssl.c>
<VirtualHost *:443>
		ServerAdmin webmaster@$HOSTNAME
		ServerName $HOSTNAME
		RewriteEngine On
		RewriteRule ^$ /rewoo [R]
		RewriteRule ^/$ /rewoo [R]
		DocumentRoot /var/www
		<Directory />
						Options FollowSymlinks MultiViews
						AllowOverride None
						Order allow,deny
						Allow from all
		</Directory>
		ErrorDocument 503 /errorpages/503.html
		BrowserMatch "^WebDAVFS/1.[012]" redirect-carefully
		BrowserMatch "Microsoft Data Access Internet Publishing Provider" redirect-carefully
		BrowserMatch "Microsoft-WebDAV-MiniRedir/5.1.2600" redirect-carefully
		BrowserMatch "^WebDrive" redirect-carefully
		BrowserMatch "^WebDAVFS" redirect-carefully
		<IfModule encoding_module>
						EncodingEngine on
						NormalizeUsername on
						<IfModule headers_module>
										Header add Dav "1,2"
										Header add MS-Author-Via "DAV"
						</IfModule>
		</IfModule>
		ErrorLog ${APACHE_LOG_DIR}/error_log
		# Possible values include: debug, info, notice, warn, error, crit,
		# alert, emerg.
		LogLevel warn
		CustomLog ${APACHE_LOG_DIR}/ssl_access_log combined
		BrowserMatch "MSIE [2-6]" \
						nokeepalive ssl-unclean-shutdown \
						downgrade-1.0 force-response-1.0
		# MSIE 7 and newer should be able to use keepalive
		BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown
		# write proxy directives into a single file
		Include /etc/apache2/ProxyPass.conf
</VirtualHost>
</IfModule>

Enable the two configurations by creating links to these files in the /etc/apache2/sites-enabled directory and removing any configurations that are not needed:

cd /etc/apache2/sites-enabled
rm ./*
ln -s ../sites-available/rewoo.conf
ln -s ../sites-available/rewoo-ssl.conf

Change to the /etc/apache2/ directory, create a file named ProxyPass.conf and add the following content:

ProxyTimeout 900
<Location /rewoo>
    Order Deny,Allow
    Allow from All
    ProxyPass http://localhost:7070/rewoo
    ProxyPassReverse http://localhost:7070/rewoo
</Location>

Restart the service

The easiest way to make the changes take effect is to restart the web server.

systemctl restart apache2.service

SSL - Letsencrypt

For the SSL certificates we recommend the project Letsencrypt. More details about the Certbot component can be found here.

Installation of certbot


apt install snapd
snap install core
snap refresh core
snap install --classic certbot

Add a symlink to run Certbot:

ln -s /snap/bin/certbot /usr/bin/certbot

Generate certificates

certbot --apache --cert-name kunde.rewoo.net -d kunde.rewoo.net

Replace kunde.rewoo.net with the domain name under which your server should be accessible in the future

Restarting the web server

systemctl restart apache2.service

Test automatic certificate renewal

Certbot will renew your certificate automatically. To test this feature you can execute the following call:

certbot renew --dry-run

Configure Firewall

Installation of the configuration tool ufw

apt install ufw

Configuration

ufw allow http
ufw allow https
ufw allow ssh

Activate Firewall

ufw enable

PostgreSQL

Installation

wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
RELEASE=$(lsb_release -cs)
echo "deb http://apt.postgresql.org/pub/repos/apt/ ${RELEASE}"-pgdg main | tee  /etc/apt/sources.list.d/pgdg.list
apt update

Now install the latest PostgreSQL version (currently v15). If necessary, adjust the version number of the package name. At least PostgreSQL 12.x is required.

apt install postgresql-15

Configure PostgreSQL

Change to the directory /etc/postgresql/11/main (path name may differ with other PostgreSQL version) and open the file pg_hba.conf. There insert the following lines at the specified position in each case BEFORE the already existing entries:

For IPv4 add as the first line:

host	rewoodb		rewoo	127.0.0.1/32	trust

For IPv6 add as the first line:

host	rewoodb		rewoo	::1/128		password

In the same edit directory you will find the file postgresql.conf. There you have to adjust the following parameters according to your system. The following values can be used as a guideline:

max_connections = Number of CPU cores * 3
shared_buffers = RAM / 4
wal_buffers = 2MB
checkpoint_segments = 32
checkpoint_timeout = 5min
effective_cache_size = RAM / 4
work_mem = RAM / (max_connections * 16)
maintenance_work_mem = RAM / 16

Afterwards, the kernel's shared memory should be set to the same value used above for shared_buffers.

sysctl -w kernel.shmmax=<shared_buffers-Wert>

create rewoo user and rewoodb database

su -l postgres
psql
CREATE USER rewoo WITH CREATEDB PASSWORD 'rewoo';
CREATE DATABASE rewoodb WITH owner=rewoo encoding='utf-8';
\q
exit

This completes the setup of the Postgres database for use with REWOO Scope.

Last preparations

Create system user 'rewoo'

The user rewoo is required for the operation of REWOO Scope.benötigt. You can create the user with the following command:

useradd -m -d /home/rewoo -s /bin/bash -c "REWOO Scope" -U -- rewoo

Increase limit for file opening

Since Java application servers often keep many files open at the same time, they quickly break the usual limits for opening files at the same time. It is therefore necessary to increase the limit on the number of concurrently open files for the rewoo user.

To do this, change to the /etc/security/limits.d, directory, create a file there called rewoo.conf and fill it with the following code:

rewoo   -       nofile  8192

Then edit the /etc/pam.d/su file and remove the comment character before the line:

session         required        pam_limits.so

Note: If the above line does not appear in the /etc/pam.d/su file on your system, simply add it to the end of the file.

You can check if the limit increase is effective by logging in as user rewoo and invoking the ulimit -a command.

Continue with the installation of REWOO Scope server.

Install REWOO Scope

After all the required tools and software packages have been installed, you can start installing the REWOO Scope server software.

REWOO Scope files

Copy the provided files REWOO.war, config-grails5.sh, start-grails5.sh and debug.sh into the directory /home/rewoo/. If you uploaded the files with another user, change the owner of the files to the rewoo user:

chown rewoo:rewoo *.*

Set the permissions:

chmod 0744 *.*

Carry out the further work with the rewoo user. To do this, switch to the account:

su rewoo

If your server cannot connect to the Internet, create a temp directory for the tika server component and then move it there.


mkdir /tmp/rewoo-scoope-tika
cp tika-server-1.28.4.jar /tmp/rewoo-scope-tika/

Configuration

The configuration of the REWOO Scope server software is done via the config-grails5.sh script. Call the script with parameters for the name of the instance (default "rewoo") and the (internal) port used (default 7070):

./config-grails5.sh rewoo 7070

Start REWOO Scope server

After the configuration is complete, start the REWOO Scope server application. As parameters, use the instance name used in the configuration and the max. memory allocation for the server application in GB (recommendation min. 4GB). Example:

./start-grails5.sh rewoo 4G

The server is now started. You get a note that the log output is forwarded to the nohup.out file. With Ctrl+C you can cancel the hint and return to the console. If you want to follow the start process in the log, you can do this with the following call:

tail -f nohup.out

As soon as the entry GlobalTableViewCache refreshed appears in the log. The startup process is complete and the REWOO Scope application can be used. To check the application, open the following address in the browser: https://yourserverdomain.com/rewoo
Now copy the debug.sh file into the correct directory:

cp debug.sh /home/rewoo/rewoo-admin/scripts/