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 are a list of some important settings:

*** Unrecognized inline element: itemizedlist

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.

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