Installer for eXist-db for ART-DECOR®

To perform the following instructions you need to have root ssh access to your server. Alternatively, you can use the sudo command accordingly.

NOTE

The following instructions are valid for CentOS Linux. The database runs on other Linux systems, too. The commands need to be adapted accordingly, e. g. the package management system yum (Yellowdog Updater, Modified) is not existent on all Linux variants.

Stop eXist

If a previous version of eXist is running on your system, stop that instance first.

systemctl stop exist-db.service

...or, if this works:

service exist-db stop

Place the binary eXist-db installer

We adivice to place ART-DECOR related stuff in /opt. You may choose for another location but our instructions refer to that directory.

First create the art-decor-linux directory and subdiretcories if they do not exist.

mkdir -p /opt/art-decor-linux/tooling/packages

Change directory to packages.

cd /opt/art-decor-linux/tooling/packages

You may check out the whole git repository, or you can download file by file. Choose your eXist-db version from

https://bitbucket.org/art-decor/art-decor-external-tools/src/master/art-decor-exist-db-installer

...and download the installer for linux, e.g. exist-installer-6.2.0_artdecor.jar.

Place the install script and settings file

mkdir -p /opt/art-decor-linux/tooling/scripts
cd /opt/art-decor-linux/tooling/scripts

From https://bitbucket.org/art-decor/art-decor-external-tools/src/master/art-decor-exist-db-installer/scripts/

...fetch the files

install_exist.sh
settings

Make sure the script is executable, e.g. by issuing

chmod +x install_exist.sh

Java openJDK

Update / install the JAVA openJDK version.

yum update java-11-openjdk
yum install java-11-openjdk

Something similar to this output should be shown.

> java --version
openjdk 11.0.16.1 2022-08-12 LTS
OpenJDK Runtime Environment (Red_Hat-11.0.16.1.1-1.el7_9) (build 11.0.16.1+1-LTS)
OpenJDK 64-Bit Server VM (Red_Hat-11.0.16.1.1-1.el7_9) (build 11.0.16.1+1-LTS, mixed mode, sharing)

> ls /usr/lib/jvm
java-11-openjdk-11.0.16.1.1-1.el7_9.x86_64  jre  jre-11  jre-11-openjdk  jre-11-openjdk-11.0.16.1.1-1.el7_9.x86_64  jre-openjdk

Run the installer script

Check settings in file settings

Edit the settings file.

Example output above was: java-11-openjdk-11.0.16.1.1-1.el7_9.x86_64, thus

java_location=/usr/lib/jvm/java-11-openjdk-11.0.16.1.1-1.el7_9.x86_64/

Check memory settings and place them in settings

exist_maxmem=8192
exist_cachemem=1024

This can be changed if your server is "bigger", e.g. for an 32 G memory you may want to switch to

exist_maxmem=10240 :: exist-db max mem = wrapper.java.maxmemory
exist_cachemem=1280 :: exist-db cache

Hints for further tuning in /etc/conf.xml of the eXist-db directory when eXist is installed

2560 : conf.xml: db-connection cacheSize = 1/3 of exist-db max mem
1280 : conf.xml: db-connection collectionCache = 1/6 of exist-db max mem

Also look at http://exist-db.org/exist/apps/doc/tuning.xml?field=all&id=D3.7 for the JAVA_OPTS.

Check whether the installer location is correct. It could be just the folder packages (as assumed above) or a folder with a version, e.g. 6.2.0.

# location where tooling is located
installer_location=../packages

Run the installer

Choose your db admin password ({ENTERYOURPASSHERE} is the placeholder here)

./install_exist.sh -p /usr/local/exist_atp --password {ENTERYOURPASSHERE}

Clean the password from the history

history | grep password
history -d <number>

Backup of raw install (without ART-DECOR)

Create a backup of an empty exist-db

mkdir -p /opt/art-decor-linux/tooling/backups
cd /opt/art-decor-linux/tooling/backups

If you have older eXist-db versions installed under /usr/local/ that you do not wish to backup, move them first.

Backup your fresh installation.

VERSIONSHORT=6.0.1
tar zcvf exist_without_artdecor_${VERSIONSHORT}_$(date '+%Y%m%d%H%M').tgz /usr/local/exist_atp_*

Please check whether the path to the installation (/usr/local/exist_atp_* in the example above) is correct.

Check and start exist_db

Maybe you have to reload your systemctl daemon first

systemctl daemon-reload

The check and start eXist-db

systemctl status eXist-db.service
systemctl start eXist-db.service

And maybe check again whether the service is running.

systemctl status eXist-db.service
● eXist-db.service - eXist-db 6.2.0 Server
   Loaded: loaded (/etc/systemd/system/eXist-db.service; enabled; vendor preset: disabled)
   Active: active (running) since Mon 2022-07-04 11:08:52 CEST; 4s ago
 Main PID: 1288412 (java)
    Tasks: 90 (limit: 822516)
   Memory: 469.7M
   CGroup: /system.slice/eXist-db.service
           └─1288412 /usr/bin/java -Xmx8g -Dorg.exist.db-connection.cacheSize=2700M -Xms128m -Dfile.encoding=UTF-8 -Dlog4j.configurationFile=/usr/local/exist_atp/etc/log4j2.xml -Dexist.home=/usr/local/exist_>

Jul 04 11:08:55 art-decor-open-tools.net startup.sh[1288412]: 04 Jul 2022 11:08:55,828 [main] INFO  (JettyStart.java [run]:287) - -----------------------------------------------------
Jul 04 11:08:55 art-decor-open-tools.net startup.sh[1288412]: 04 Jul 2022 11:08:55,828 [main] INFO  (JettyStart.java [run]:288) - Server has started, listening on:
Jul 04 11:08:55 art-decor-open-tools.net startup.sh[1288412]: 04 Jul 2022 11:08:55,828 [main] INFO  (JettyStart.java [run]:290) - http://62.138.179.44:8877/
Jul 04 11:08:55 art-decor-open-tools.net startup.sh[1288412]: 04 Jul 2022 11:08:55,829 [main] INFO  (JettyStart.java [run]:290) - https://62.138.179.44:8477/
Jul 04 11:08:55 art-decor-open-tools.net startup.sh[1288412]: 04 Jul 2022 11:08:55,829 [main] INFO  (JettyStart.java [run]:293) - Configured contexts:
Jul 04 11:08:55 art-decor-open-tools.net startup.sh[1288412]: 04 Jul 2022 11:08:55,829 [main] INFO  (JettyStart.java [run]:299) - /exist (eXist XML Database)
Jul 04 11:08:55 art-decor-open-tools.net startup.sh[1288412]: 04 Jul 2022 11:08:55,831 [main] INFO  (JettyStart.java [run]:315) - /exist/iprange (IPrange filter)
Jul 04 11:08:55 art-decor-open-tools.net startup.sh[1288412]: 04 Jul 2022 11:08:55,831 [main] INFO  (JettyStart.java [run]:299) - / (eXist-db portal)
Jul 04 11:08:55 art-decor-open-tools.net startup.sh[1288412]: 04 Jul 2022 11:08:55,832 [main] INFO  (JettyStart.java [run]:315) - /iprange (IPrange filter)
Jul 04 11:08:55 art-decor-open-tools.net startup.sh[1288412]: 04 Jul 2022 11:08:55,832 [main] INFO  (JettyStart.java [run]:323) - -----------------------------------------------------

The service file is /etc/systemd/system/eXist-db.service.

Further Installations

To continue with the further installation use the eXist Package Manager.

NOTE

If you have a browser available on the system where the installation just took place, simply contact localhost:8877.

If the installation was done on a distant server, you probably need to etstablish a SSH tunnel, that tunnels a port on your local machine to the localhost:8877 address and port on the distant server. An example

ssh -c {cipher} -f {user}@{distant-server-address} -L {local-port}:127.0.0.1:8877 -N

Please find more information hereopen in new window.

You might also need to trim your firewall configuration to allow access.

After logging in as the admin, you select the eXist Package Manager that shows up as follows.

PREREQUISITES

This step depends on what repository branch you want to follow. There is a stable and a development path.

To use the stable ART-DECOR Release 3 backend use https://repository.art-decor.org/stable3,
to use the development ART-DECOR Release 3 backend use https://repository.art-decor.org/development3.

Unless you are interested in getting and using the most recent develeopment code we recommend to use the stable (master) branch.

Update eXist Apps

Update eXist Apps, e.g. exide etc. from the default repository, specified by default in the file /db/apps/packageservice/configuration.xml. For eXist this is

http://exist-db.org/exist/apps/public-repo

...thus in the config file

<repository active="true" default="true">http://exist-db.org/exist/apps/public-repo</repository>

You must install from eXist:

JWT - Create, read and verify JSON Web Tokens (JWT) in exist-db
roaster - OpenAPI Router

Please check also if the

Shared Resources: jquery, dojo, ace, templating, utilities

... package is listed and install it, if it is missing.

Install ART-DECOR backend packages

To install the ART-DECOR backend, change the repository in file /db/apps/packageservice/configuration.xml to any of the above mentioned paths, depending on stable or development.

ART-DECOR Release 3 backend branch	URL to use
Stable	`https://repository.art-decor.org/stable3`
Development	`https://repository.art-decor.org/development3`

Change the repository element to what you desire, e.g. for the stable branch use

<repository active="true" default="true">https://repository.art-decor.org/stable3</repository>

...and comment out the eXist repository, so that there is only one active repository.

Then install the following packages from the repository in exactly this sequence:

DECOR core files
ADA - ART DECOR Applications
Advanced Requirement Tooling
ART-DECOR API
ART-DECOR System Services
DECOR example files

If you are going to use Terminology Packages install at least

Terminology Applications

... and desired Terminology Data packages, their names start with Terminology Data –.

If problems occur at startup regarding a missing EXPath Cryptographic library, please upload / install

eXist-db EXPath Cryptographic library that can best be optained hereopen in new window.

Optional are (for later):

DECOR services
FHIR 4.0.1 (R4) Server (takes a while)
OID Registry - HL7 International (takes a while)
Temple (ART-DECOR XML Editor)

Setting up the eXist scheduler

There are a couple of scheduled jobs that are required and some that you might consider to add to your installation. To this topic we dedicated a seperate documentation that we strongly recommend to follow, install the required scheduled jobs and check whether you need the recommended ones.

Initial Backup of the full installation

Stop the service

systemctl stop eXist-db.service

...and then backup the new full installation with the ART-DECOR packages installed

cd /opt/art-decor-linux/tooling/backups
VERSIONSHORT=6.0.1
tar zcvf exist_with_artdecor_${VERSIONSHORT}_$(date '+%Y%m%d%H%M').tgz /usr/local/exist_atp_*

Start the system again and check whether it is running properly

systemctl start eXist-db.service
...
systemctl status eXist-db.service

This concludes the database installation.

Toubleshooting

Some pointers for troubleshooting the eXist-db installation.

# check out the status of the eXist-db process
sudo ps aux |grep -i exist
# check out the status of the port that eXist-db is running on
sudo netstat -anp |grep :8877

Besides the systemctl logging above, there are also specific eXist-db logging files.

sudo updatedb
sudo locate exist.log
sudo tail -f /usr/local/exist_atp_${VERSIONSHORT}/logs/*.log
# or just tail: exist.log

konec

Permalink | Updated 2024-02-05 | Visits: 1038

# Installer for eXist-db for ART-DECOR®

# Stop eXist

# Place the binary eXist-db installer

# Place the install script and settings file

# Java openJDK

# Run the installer script

# Check settings in file settings

# Run the installer

# Clean the password from the history

# Backup of raw install (without ART-DECOR)

# Check and start exist_db

# Further Installations

# Update eXist Apps

# Install ART-DECOR backend packages

# Setting up the eXist scheduler

# Initial Backup of the full installation

# Toubleshooting