Basic Installation

(1Q18)


This article describes eXist-db's basic installation procedure. It will help you install and setup eXist-db in a quick and easy way on, for instance, your laptop or a development server. Before you know it you'll be up and running and programming XQuery!

System Requirements

eXist-db runs on any system Java runs on. So all recent versions of Linux, macOS, and Windows are ok. The following requirements must be met:

  • At least Java version 8 (since eXist-db 3.0)

  • About 200Mb of disk space for the installation

  • At least 512Mb memory to run

Administrative privileges are not required to install or run eXist-db, but certain installation procedures are not possible without administrative privileges.

Note: eXist-db and Java

eXist-db is built on Java, a free, cross-platform software development environment. Java comes in a number of versions, so it is important that you use the version that eXist-db requires: Java 8 (since eXist-db 3.0). For instructions about running Java on your operating system, see Oracle's Installing Java page. It is recommended to use the Oracle Java VM, but the OpenJDK 7 is a good open source alternative for the Oracle JVM.

eXist-db runs with both the Java JRE (Java Runtime Environment) and the JDK (Java Development Kit). The JRE usually suffices. You only need the JDK to compile eXist-db from its source code.

Details of the Java installation can be obtained with the java -version command:

…> java -version
java version ""1.8.0_60-ea""
Java(TM) SE Runtime Environment (build 1.8.0_60-ea-b19)
Java HotSpot(TM) 64-Bit Server VM (build 25.60-b19, mixed mode)

For Linux users: Unfortunately, Oracle's own pages (such as the link above) focus on commercial Linux distributions. Users of other distributions are better served by distribution-specific instructions. More information for specific versions of Linux can be found at Amazon Linux, Ubuntu and Debian.

Note for pre eXist-db v2.2 versions: Due to compatibility issues it is NOT recommended to use "OpenJDK6" (IcedTea) and "GNU Compiler for Java" (GCJ) which are shipped by several Linux distributions.

Warning:

If you have installed Saxon as a JRE extension (via the extensions folder), this can cause a critical error during installation. To avoid this error either remove the JRE extension, or install a second JRE just for use with eXist-db and set JAVA_HOME accordingly.

Installing eXist-db

The first steps in installing eXIst-db are downloading the installer and firing it up:

  • Download the installer by following the download link on the eXist-db homepage page. We recommend that you download the latest stable release.

    The installer is a single file called eXist-db-setup-[version].jar (for instance eXist-db-setup-3.6.1.jar).

  • Launch the eXist-db installer:

    • On Mac and Windows, simply double-click the downloaded .jar file.

      On Mac OS X 10.7 and higher, a security feature called Gatekeeper may prevent the installer from running since eXist-db is not registered with Apple. To circumvent the warning dialog and allow the installer to run, right-click or control-click the file and select Open.

    • On Linux distributions with a graphical desktop interface (e.g., Ubuntu), you can launch the installer by making the .jar file executable, right-clicking it, and selecting the "Open With ... Java" option.

    • If necessary you can launch the installer from the command line with the following command:

      java -jar eXist-db-setup-[version].jar
  • More advanced installation methods (like installing on a headless system) are described in the Advanced Installation article.

After the installer is launched, follow the prompts described below to complete the installation. We recommend that you accept the default options, since these are designed to make using eXist-db easy. The installer's dialog panes are as follows:

Installation Directory:

You will be asked where to install eXist-db on your hard disk. The installer will suggest an appropriate directory, but if you want, you can install eXist-db anywhere on your system.

Data Directory

The data directory is where eXist-db keeps its data files. The installer will suggest keeping the data files inside the application directory, but you can select a different location if you want.

Admin Password and Memory Settings:

The Admin Password is a password for the eXist-db administrator account, or more commonly, the "admin" account. This admin account belongs to you, and certain key functions in eXist-db can only be performed by the admin. While you can leave the admin password blank, we strongly recommend setting the password in order to secure access your installation of eXist-db. Why? Keep in mind that while eXist-db is running, it can be accessed by other users on your local network (be it in your home or office, or at a cafe or on a train). So, securing your administrator's account on eXist-db is a good way to protect your data and prevent others from abusing the account.

Configure the maximum amount of memory which will be available to Java (and eXist-db) and the portion of it which will be reserved for internal caches.

Package Installation:
  • The "core" package is required to run eXist-db.

  • The "sources" package is optional. Removing "sources" cuts the installation size considerably, but best to install everything unless you are starved for disk space.

  • The "apps" package allows you to select or deselect a number of applications which will be installed into eXist-db when it starts the first time. If you are new to eXist-db, we recommend to at least select "dashboard", "demo", "doc", "eXide" and "fundocs". You'll need those to make your first steps in XQuery development.

After this the installer will go through a number of additional steps and screens installing files and configuring the system. Once finished you're ready to run!

Note: MacOS users installing via disk image

For macOS users installing via disk image the default data directory will be: /Users/$username$/Library/Application Support/org.exist

Change the default (empty) password via the Open dashboard option from the menubar icon once installation has finished. Watch out: during the initial run of eXist-db its Dock icon may remain active even after eXist-db has been shut down. Simply right-click on the eXist-db Dock icon and select Quit. On subsequent runs the dock icon should behave as expected.

Launching eXist-db

To launch eXist-db:

  • On the Mac, double-click eXist-db's application icon where you installed eXist-db.

  • On Linux or Windows, select the eXist-db Database Start-up desktop shortcut icon or Start Menu entry.

eXist-db can also be run as a background service. For more information see the Advanced Installation article.

A splash screen appears showing the eXist-db logo. Upon first start-up, eXist-db will upload the applications you selected in the installer. This may take a while and is only done once.

Splash screen during start-up
Splash screen during start-up

Once eXist is started, a menu bar icon (Mac) or system tray icon (Linux/Windows) appears. This gives you access to eXist-db's tools and lets you shutdown or restart the database. Click on it to see a menu providing direct access to the most important tools.

Menu bar icon on Mac
Menu bar icon on Mac

Note: Linux Installation

Installing into the system tray does not work equally well on all operating systems. If the system tray icon cannot be installed, you'll see a small toolbar dialog pop up instead.

Also, the desktop integration does not work properly on all versions of Linux. However, you may always use the provided shell scripts (bin/startup.sh) to launch eXist-db without desktop integration.

Launching from the command line

You can also start eXist-db from the command line:

  1. Open your terminal or command prompt.

  2. Change (cd) to the directory where you installed eXist-db (for instance, /usr/local/lib/exist/ for Linux, /Applications/eXist/ for Mac, or C:\Program Files\eXist for Windows).

  3. Simply calling start.jar will start eXist-db via the desktop launcher:

    java -jar start.jar

If you want to launch eXist-db without a GUI, use the shell scripts in the bin/ sub-directory. On Linux or Mac, enter bin/startup.sh, on Windows bin\startup.bat. More information about these start-up scripts in the Advanced Installation article.

Note: Having trouble?

If you're having trouble launching eXist-db, see our articles on Troubleshooting and Advanced Installation.

Diving In

After a successful installation and launch, access eXist-db's Dashboard, the central administration and application hub of eXist-db. If the system tray icon works on your system, select Open Dashboard from the pop-up menu. Or just open a web browser and enter the following URL: http://localhost:8080/exist/

The following page appears:

Seeing it? Congratulations! (Not seeing it? See our article on Troubleshooting).

All right, ready to dive in! Your local installation includes everything you need. Access is easy, through the applications on the Dashboard (see also the article on the Dashboard).

Shutting Down the Database

Improperly shutting down the database can corrupt your data files. Follow one of the following procedures to properly shut down eXist-db:

  • The system tray pop-up menu has an option Stop server. You may also choose Quit (and stop server) to shut down eXist-db and the system tray launcher at the same time.

  • From the Dashboard: select the Shutdown button

  • From the command line, run the bin/shutdown.sh (Linux/Mac) or shutdown.bat (DOS/Windows) shutdown scripts, using your admin account's credentials:

    bin/shutdown.sh -u admin -p youradminpassword
    bin/shutdown.bat -u admin -p youradminpassword
  • From the command line, run the following Java command, using your admin account's credentials:

    java -jar start.jar shutdown -u admin -p youradminpassword
  • From the Java Admin Client: select Connection, Shutdown from the menu.