Advanced Installation Methods

(4Q19)


The eXist-db Basic Installation article describes how to install and start eXist-db for basic usage. This article explains more advanced methods of installing and running eXist, for instance for a headless (no GUI) system, running it as a service, etc.

Headless Installation

The Basic Installation of eXist-db requires a graphical desktop. You can also install eXist on a headless (no GUI) system. For this launch the installer from the command line, using the -console option:

java -jar eXist-{version}.jar -console

In console mode, the installer will prompt for several parameters (almost like the GUI version does). A dump of a sample interaction is shown below:

$ java -jar exist-installer/target/exist-installer-5.0.0-RC8-SNAPSHOT.jar
Select target path [/Users/wolf/Source/trunk/eXist] 
/Applications/eXist/
press 1 to continue, 2 to quit, 3 to redisplay
1
Set Data Directory
Please select a directory where eXist will keep its data files. On Vista and Windows 7, this should be outside the usual 'Program Files' directory:
Data dir:  [data] 

press 1 to continue, 2 to quit, 3 to redisplay
1
Set Admin Password
Enter password:  [] 
xyz
Enter password:  [xyz] 
xyz
------------------------------------------

Max memory in mb: [1024] 

Cache memory in mb: [128] 

press 1 to continue, 2 to quit, 3 to redisplay
1
[ Starting to unpack ]
[ Processing package: Core (1/13) ]
[ Processing package: Sources (2/13) ]
[ Processing package: Apps (3/13) ]
[ Processing package: bfDemos (4/13) ]
[ Processing package: bfReferences (5/13) ]
[ Processing package: dashboard (6/13) ]
[ Processing package: demo (7/13) ]
[ Processing package: doc (8/13) ]
[ Processing package: eXide (9/13) ]
[ Processing package: fundocs (10/13) ]
[ Processing package: shared (11/13) ]
[ Processing package: xsltforms (12/13) ]
[ Processing package: xsltforms-demo (13/13) ]
[ Unpacking finished ]
[ Starting processing ]
Starting process Setting admin password ... (1/1)
--- Starting embedded database instance ---
File lock last access timestamp: 30.12.2012 /Applications/eXist/data/dbx_dir.lck
Found a stale lockfile. Trying to remove it:  /Applications/eXist/data/dbx_dir.lck
File lock last access timestamp: 30.12.2012 /Applications/eXist/data/journal.lck
Found a stale lockfile. Trying to remove it:  /Applications/eXist/data/journal.lck
Dez 30, 2012 10:13:26 PM org.expath.pkg.repo.util.Logger info
INFO: Create a new repository with storage: File system storage in /Applications/eXist/data/expathrepo
Setting admin user password...
--- Initialization complete. Shutdown embedded database instance ---
[ Console installation done ]

Running eXist-db as a Service

Instead of manually running the eXist-db server in a shell window, you can run it as a background service which is automatically launched during system start-up. This can be convenient, especially for servers. eXist-db continues to run even after users have logged off.

Windows

On Windows there are three identical options:

  • Choose Install eXist-db as Service from the eXist-db's system tray application.

  • Choose Install eXist-db as Service from eXist-db's entry in the Windows start menu.

Installing eXist-db as a service on Windows requires full administrator rights.

After installing eXist-db as a service, you'll find eXist-db in the list of services registered with Windows:

Unix/Linux

If your system supports systemd you can run the service wrapper as a non-privileged user.

Begin by creating a new user in your system which is being created specifically to run eXist-db as a service. You can do this by typing the following command:

sudo adduser --system --shell /sbin/nologin --comment "eXist-db Service Account" existdb

This command creates a new system user named "existdb" which does not need to login in order to run a service. In order for this new system user to be able to run eXist-db, we need to change the permission of eXist-db to match this new user. You do so by navigating to your $EXIST_HOME folder and typing the following two commands:

sudo chown -R existdb exist-5.0.0
sudo chgrp -R existdb exist-5.0.0

These two commmands modify the ownership and group permissions recursively throughout the whole eXist-db project to your new existdb system user. Now only this user can run eXist-db. Next, navigate to the /etc/systemd/system sub-directory. Once there, create an exist-db.service file which contains the following information at a minimum:

[Unit]
Description=eXist-db 5.0.0 Server
Documentation=
After=syslog.target

[Service]
Type=simple
User=existdb
Group=existdb
ExecStart=/path/to/exist-5.0.0/bin/startup.sh

[Install]
WantedBy=multi-user.target

Once this file is stored in this location, you need to update permissions. Give ownership of this file to the exist user by using the following commands:

sudo chown existdb exist-db.service
sudo chgrp existdb exist-db.service

Below is a list of common commands to interact with the newly created and configured service:

  • sudo systemctl start exist-db.service - Enter command to start eXist-db

  • sudo systemctl stop exist-db.service - Enter command to stop eXist-db

  • sudo systemctl enable exist-db.service - Enter command to enable eXist-db to automatically start running after a reboot of your system

  • sudo systemctl disable exist-db.service - Enter commande to disable eXist-db from automatically starting after a reboot of your system

  • sudo systemctl restart exist-db.service - Enter command to restart eXist-db

  • systemctl status exist-db - Enter command to check the status of eXist-db

  • journalctl - Run the following command to check systemd journal:

Alternatives for scripts in the bin Directory

Included in the distribution are a number of useful .sh (Unix Shell) and .bat (Windows batch) programs located in the bin sub-directory. Their names speak for themselves.

However, if you find that programs do not launch, you can try to manually launch them on the command-line without the scripting wrapper. This often provides useful debugging information.

To manually launch these scripts, give the following commands:

startup.sh (Unix) / startup.bat (Windows)

Starts the included Jetty web server at port 8080. eXist runs as a web application, located at http://localhost:8080/exist/.

shutdown.sh (Unix) / shutdown.bat (Windows)
shutdown.sh -p youradminpassword

Closes the running instance of eXist. If eXist has been started with startup.sh, calling shutdown.sh will also stop the Jetty web server. Otherwise, only the database is stopped by this call (since eXist has no control over the environment in which it is running). You should always call shutdown before killing the server process.

client.sh (Unix) / client.bat (Windows)

Launches the Java Admin Client.