Quick Start

• 1. Objectives
• 2. Requirements
• 3. Installing eXist
• 4. Launching eXist
• 5. Accessing the Server
• 6. Installing Sample Applications using the Admin Webpage
• 7. Administering eXist with the Java Admin Client
• 8. Shutting Down the Database
• 9. If Something Goes Wrong ...
• 10. Running Executable Files

1. Objectives

This guide describes the easiest way to install and begin using the eXist-db Open Source Native XML Database.

2. Requirements

eXist can be installed on newer versions of Linux, Windows and Mac OS X. In order to run the eXist installer, it is necessary to have the Java Development Kit (JDK) installed on your operating system. The JDK is pre-installed on Mac OS X through 10.6; for instructions on how to install JDK on Windows, see this guide; for instructions on how to install JDK on Linux, see this guide.

In order to be able to install and start up eXist on Mac OS X and Linux, you need to know the basics of how to use your operating system's terminal (Applications/Utilities/Terminal.app on Mac OS X). On Windows, knowing how to use the command prompt is not required for installing eXist.

Some knowledge of XML and XQuery is required in order to start using eXist to query XML documents. The XQuery Wikibook is a useful resource for learning how to use XQuery with eXist; it also contains references to other resources for learning XQuery.

3. Installing eXist

Download the latest stable release of eXist. The installer is a .jar (Java Archive) file which automatically determines the correct system settings (i.e. paths and environment variables) for eXist. On Windows and Linux, the installer can also create convenient desktop shortcuts for starting eXist.

Once the download has completed, launch the eXist installer by doing one of the following:

Windows and Mac users can also use this procedure, entering the same command in Windows command prompt or in a Unix shell.

After the installer is launched, follow the prompts to complete the installation.

During installation, you are asked to supply a password for the eXist administrator account (the "admin" password). You are strongly encouraged to set the admin password on all installations of eXist, even those without internet access; otherwise the eXist security manager will be disabled. The admin password asked for during the install procedure is not the admin password of your operating system, but the password to be used for the eXist admin account.

eXist, through Jetty, by default uses port 8080. There may be other services on your system using this port. To see whether this is the case, enter http://localhost:8080/ in your browser. If another service occupies this port, you cannot start up eXist unless you shut down the service in question or make eXist use another port. To make eXist use another port, open the file /tools/jetty/etc/jetty.xml inside your eXist installation in a text or XML editor and change the value "8080" in

to a port that is not used, e.g. "8899":

eXist uses port 8443 for confidential communication. Another service may also be using this port. To make eXist use another port, open the file /tools/jetty/etc/jetty.xml and change the value "8443" in

and

to a port that is not used, e.g. "8444".

4. Launching eXist

You should now be ready to launch eXist. If you use Linux or Windows and have allowed the installer to create desktop shortcuts, double-click on the eXist Database Startup icon on your desktop, or select this item from the Start menu.

The installer will not create desktop shortcuts on Macs. If you are a Mac user, or if you wish to start eXist manually on Linux or Windows, do the following:

If these scripts do not launch eXist, you can launch it by changing to the directory where you installed eXist and entering the following into the console:

If you have problems running the shell/batch scripts, read Running Executable Files below.

While eXist starts up, log output appears in the console. If eXist launched properly, you will find output similar to the following (this example output is taken from Mac OS X):

When you see the "eXist-db has started" message, you know that your eXist installation works.

5. Accessing the Server

In the default setup, eXist runs inside a web application served by a pre-configured Jetty webserver. All interfaces are provided as servlets. To test that the server is running, enter the following URL in a web browser:

http://localhost:8080../index.xml

(If you have changed the port used by eXist, you have to change the port value in the URL. In the console output upon start-up, the correct URL is given towards the end.)

You should now see the following web page:

Note that this web page is not the eXist-db.org homepage, but rather a local copy of this homepage included with the eXist installation. This local copy includes the eXist documentation, function libraries, resources, and a collection of XQuery examples that can be installed through the Admin webpage.

6. Installing Sample Applications using the Admin Webpage

To begin using the database system, you must first create document collections and import files into eXist. To help you in learning these and other basic database operations, a number of simple XQuery web applications have been included with the eXist distribution. These applications are designed to allow users to experiment and query sample XML documents using the eXist database system.

To start using these sample applications, you must log in to the eXist database administration page. To log in, go to the Administration » Admin link located on the sidebar menu on the local eXist homepage. You should now see the login screen as shown on the right. Enter the username "admin" and the password you set during installation (or which you have set by other means).
Once you have logged in, select Examples Setup from the menu on the left. Most of the example data is shipped with eXist, but some files need to be downloaded. Check the "The XML Acronym Demystifier" and "The Mondial Database (Europe)" in order to download these files. Click on the "Import Files" button to import the example data into eXist. After you have imported the files, you can access the collections they are imported into by clicking on "Browse Collections". Here you can upload and delete individual files, as well as view the contents of them.
After the example data has been imported, you can go back to the Home page and you will now be able to query the imported files through a number of small web applications listed in All Examples in the "Examples" tab. The simplest of these applications is the XQuery Sandbox shown on the right which allows users to submit queries to the XML files imported into the database. The XQuery Sandbox provides the easiest way to start experimenting with eXist and XQuery. A number of sample queries are furnished through the dropdown menu. After modifying the queries, you can store them in the slots on the left. Click on an empty slot to store the query in the main query field. If you click on a slot with a stored query, the contents of the stored query and the main query field will be swapped.

7. Administering eXist with the Java Admin Client

In addition to the Admin webpage, eXist provides a Java-based Admin Client. This application enables users to perform more complex administrative tasks, such as user management, security settings, batch import of whole directories, and backup/restore of the database.

Additional information on using the Admin Client from the command line is available in the section on Using the Java Client on the Command Line.

You can launch the client by doing one of the following:

A screenshot of the client login interface is shown on the right. In the login window, you can provide your username and password, and select a server. The client can either connect to a Remote server, or launch an Embedded database (i.e. a database embedded in an application which runs in the same process as the client). For now, you should run the client remotely (running eXist on localhost is also running it remotely). If you connect to a remote database, the URL field specifies the location of the database server. For the standard database setup used here, use the displayed default URI (xmldb:exist://localhost:8080../xmlrpc). More information on server URIs and their function can be found in the guide to Database Deployment.
Once you have logged in, a client window will open. This window is split into two panels, and has a top menu and a toolbar. The top panel lists the database collections; the bottom panel is the "shell" and has a command prompt. This shell allows you to manually enter database commands. Most commands, however, can be entered using the menu. All of the menu and toolbar items have tooltips that explain their functions.
If eXist is online, you expose it to exploitation if you use an empty admin password. If you did not specify an admin password during installation, you are strongly advised to set an admin password as soon as possible. You can do this in the Java Admin Client by following these steps: Open the "Edit Users" window by selecting the "Manage Users" icon (image of a pair of keys) in the toolbar At the top, select the "admin" user in the table of users Type in the new password into the password fields Click the "Modify User" button to apply the changes

8. Shutting Down the Database

It is recommended you properly shut down the database before killing the server process. If you do not do this, data files may become corrupted. There are several ways to trigger a database shutdown:

9. If Something Goes Wrong ...

If you experience any problems while installing eXist, your first step should be to check the log files to get additional information about the source of the problem. eXist uses the log4j-package to write output logs to files. By default, this output is written to the directory webapp/WEB-INF/logs. The main log files for eXist itself are exist.log and xmldb.log.

If you encounter a problem you are unable to fix, check the mailing list archives for postings on similar errors. If you cannot find a posting, or you are still unsure about the problem, consider posting your problem on the list for feedback. If you do decide to post a message, please include any exception message you find, both in the logs and the console.

10. Running Executable Files

Included in the distribution are a number of useful .sh (Unix Shell) and .bat (DOS batch) programs located in the bin directory. If you installed the source distribution or used the installer, you can find this directory in the root directory of the distribution.

If you find the programs do not launch, you can also manually launch these files on the command-line, and specify which application you would like to start.

To manually launch these scripts: