Advanced Installation Methods

(1Q18)


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:

Wolfgangs-MacBook-Air:eXist wolf$ java -jar installer/eXist-db-setup-2.0RC2-rev17974.jar -console
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:  [webapp/WEB-INF/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/webapp/WEB-INF/data/dbx_dir.lck
Found a stale lockfile. Trying to remove it:  /Applications/eXist/webapp/WEB-INF/data/dbx_dir.lck
File lock last access timestamp: 30.12.2012 /Applications/eXist/webapp/WEB-INF/data/journal.lck
Found a stale lockfile. Trying to remove it:  /Applications/eXist/webapp/WEB-INF/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/webapp/WEB-INF/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.

eXist-db comes with pre-configured scripts that use YAJSW (Yet Another Java Service Wrapper) to handle the setup procedure. The scripts for this are contained in the directory tools/yajsw.

Out of the box the following mainstream platforms are supported:

  • Windows x86 (32bit/64bit)

  • Linux x86 (32bit/64bit) & IA (64bit)

  • macOS x86 (32bit/64bit)

  • Solaris x86 (32bit/64bit) & SPARC (32bit/64bit)

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.

  • Run tools/yajsw/bin/installService.bat from the command line.

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:

Launch it via the service manager (as shown in the screenshot above) or from the command line:

tools\yaysw\bin\startService.bat

Unix/Linux

The scripts for running eXist-db as a service for Unix and Linux based system (among which MacOS)can be found in the tools/yajsw/bin/ sub-directory.

Run the following command to get eXist-db started during initialization of the system:

tools/yajsw/bin/installDaemon.sh

This works for MacOS and many Linux distributions.

It might be required to set some variables for the specific system. Complete documentation of the configuraiton settings YAJSW can be found at the YAJSW website. Below is a list of some important settings:

  • wrapper.app.account - Allows eXist to be run as a specific user

  • wrapper.plist.template - Used on Mac systems to provide a list of parameters to launchd daemon

  • wrapper.ping.timeout YAJSW pings the application to determine if it has entered and unresponsive state. The ping timeout parameters sets the limit on how long YAJSW will wait. If you have long running queries you may find that you need to increase the value of this parameter to prevent YAJSW from restarting eXist. The parameter value is in seconds and the default value is 30.

If your system supports systemd you can run the service wrapper as a non-privileged user. You will be notified on choosing systemd non-privileged when running the service wrapper installer and uninstaller.

Unattended Installation

The installation script will ask for certain parameters during the installation. In addition to the properties described above, one can set two system variables to omit the interactive input. This can be helpful when you need to install eXist as a service during a process where no interaction is possible.

If the following variables are present, the installation will not ask for input:

  • WRAPPER_UNATTENDED should be non-zero length string

Set either one of the following to determine the init system

  • WRAPPER_USE_SYSTEMD as a non-zero length string

  • WRAPPER_USE_SYSTEMV as a non-zero length string

Other platforms

Support for additional platforms can be bootstrapped by looking at templates in the tools/yajsw/templates sub-directory. Consult the YAJSW documentation for more information.

Alternatives for scripts in the bin Directory

Included in the distribution are a number of useful .sh (Unix Shell) and .bat (DOS 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)
java -jar start.jar jetty

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)
java -jar start.jar shutdown -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.

server.sh (Unix) / server.bat (Windows)
java -jar start.jar standalone

Launches eXist as a stand-alone server process. In this setup, eXist is only accessible through the XMLRPC and the built-in HTTP interface.

client.sh (Unix) / client.bat (Windows)
java -jar start.jar client

Launches the Java Admin Client. This application is also launched if no application is selected on the command-line, like this:

java -jar start.jar