<?xml version="1.0" encoding="UTF-8"?>
<book>
    <bookinfo>
        <graphic fileref="logo.jpg"/>
        <productname>Open Source Native XML Database</productname>
        <title>Quick Start Guide</title>
        <author>
            <firstname>Wolfgang M.</firstname>
            <surname>Meier</surname>
        </author>
    </bookinfo>

    <ci:include xmlns:ci="http://apache.org/cocoon/include/1.0" src="sidebar.xml"/>

    <chapter>
        <title>Quick Start Guide</title>
        <section id="sect1">
            <title>Introduction</title>
            <para>This guide offers the quickest way to install and begin using the eXist XML
                Database system. Although this guide assumes users have a basic knowledge of XQuery
                and XML, eXist can be used as a tool for learning these technologies. However, it is
                recommended that users consult other reference and tutorial resources. Some useful
                resources are suggested at the end of this document. </para>
        </section>
        <section id="sect2">
            <title>Installing eXist</title>
            <para>To begin, download the <ulink url="http://exist-db.org/index.html#download">latest
                    standard distribution</ulink> of eXist. This package is recommended for new
                eXist users and includes a graphical installer that guides you through the
                installation process. This standard distribution comes as an executable
                    <filename>.jar</filename> (Java Archive) file, which automatically determines
                the correct system settings (i.e. paths and environment variables) for eXist. On
                Windows and Linux Operating Systems, the installer can also create desktop
                shortcuts.</para>
            <para>Once the download has completed, start the eXist installation by doing
                    <emphasis>ONE</emphasis> of the following:</para>
            <procedure>
                <step>
                    <para>For Windows and Mac users, double-click on the installer file: <filename>
                            eXist-[version]-build-XXXX.jar</filename></para>
                </step>
                <step>
                    <para>OR enter the following Java command in a Unix shell or Windows command
                        prompt using the <command>-jar</command> option:</para>
                </step>
            </procedure>
            <synopsis format="linespecific">java -jar eXist-[Version].jar</synopsis>

            <para>This will launch the installer. Simply follow the steps to complete the
                installation process.</para>
            <note>
                <para>To run the eXist installer package, ensure that <ulink
                        url="http://java.sun.com/downloads/">JDK (Java Platform)</ulink> 1.4.2 or
                    later is installed on your operating system.</para>
            </note>
            <note>
                <para>The eXist installer requires a graphical desktop in order to launch. However,
                    If you wish to install eXist on a headless system, use the <command>-p</command>
                    parameter when following <emphasis>Option Two</emphasis> above. This will
                    automatically start the installation. Option <command>-p</command> expects a
                    single parameter: the path to the directory where you would like to install
                    eXist. For example:</para>
                <synopsis>java -jar eXist-{version}.jar -p /usr/local/exist</synopsis>
            </note>
        </section>
        <section id="sect3">
            <title>Getting Started</title>
            <para>After the installation has completed, you should now be ready to launch eXist. If
                the installer has created shortcuts, simply double-click on the <emphasis>eXist
                    Database Startup</emphasis> icon or select this item from the start menu located
                on the desktop. </para>
            <para>To start eXist manually, do the following:</para>
            <procedure>
                <step>
                    <para>Open a Unix shell or DOS command prompt</para>
                </step>
                <step>
                    <para>Change to the directory where you installed eXist</para>
                </step>
                <step>
                    <para>If you are a Unix user, enter the following:</para>
                    <synopsis format="linespecific">bin/startup.sh</synopsis>
                    <para>If you are a Windows user, enter the following:</para>
                    <synopsis format="linespecific">bin\startup.bat</synopsis>
                </step>
            </procedure>

            <para>If these scripts do not launch eXist, you can load it directly with the bootstrap
                loader by entering the following into the console:</para>
            <synopsis>java -Xmx128M -Djava.endorsed.dirs=lib/endorsed -jar start.jar jetty</synopsis>
            <note>
                <para>If you have problems understanding or running the shell/batch scripts, read
                <ulink url="#appendix">Running Executable Files</ulink> below.</para>
            </note>
            <para>While eXist starts up, log output might appear in the console. If eXist was
                launched properly, you should see the following:</para>
            <example>
                <title>Console Output</title>
                <screen><![CDATA[
                    [wolf@localhost eXist-trunk]$ bin/startup.sh
WARN: The following JAR file entries from 'org/exist/start/start.config' aren't available (this may NOT be a problem):
    /home/wolf/Devel/eXist/eXist-trunk/examples.jar

Configuring eXist from /home/wolf/Devel/eXist/eXist-trunk/conf.xml
Found 1 catalog entries.
Loading catalog: /home/wolf/Devel/eXist/eXist-trunk/webapp/WEB-INF/catalog.xml
IN CONFIGURE
cluster.journal.maxStore 65000
cluster.journal.shift 100
29 Apr 2006 13:56:00,153 [main] INFO  (FileResource.java [<clinit>]:60) - Checking Resource aliases
29 Apr 2006 13:56:00,474 [main] INFO  (HttpServer.java [setStatsOn]:1068) - Statistics on = false for org.mortbay.jetty.Server@571a75a2
29 Apr 2006 13:56:00,548 [main] INFO  (HttpServer.java [start]:654) - Starting Jetty/5.0.0
29 Apr 2006 13:56:00,554 [main] INFO  (HttpServer.java [start]:669) - Started org.mortbay.http.NCSARequestLog@236acdd1
29 Apr 2006 13:56:01,800 [main] INFO  (HttpContext.java [start]:1604) - Started WebApplicationContext[eXist Server,eXist Server]
Logging already initialized. Skipping...
29 Apr 2006 13:56:03,982 [main] WARN  (JavaUtils.java [isAttachmentSupported]:1305) - Unable to find required classes (javax.activation.DataHandler and javax.mail.internet.MimeMultipart). Attachment support is disabled.
29 Apr 2006 13:56:04,272 [main] INFO  (SocketListener.java [start]:204) - Started SocketListener on 0.0.0.0:8080
29 Apr 2006 13:56:04,273 [main] INFO  (HttpServer.java [start]:690) - Started org.mortbay.jetty.Server@571a75a2
                ]]></screen>
            </example>
        </section>

        <section id="sect4">
            <title>Accessing the Server</title>
            <para>In the default setup, eXist is running inside a web application served by
            a pre-configured <ulink url="http://jetty.mortbay.com/">Jetty</ulink> webserver. All interfaces are provided
            as servlets. To test that the server is running, enter the following URL in a web
                browser:</para>
            <para>
                <ulink url="http://localhost:8080/exist/index.xml"
                    >http://localhost:8080/exist/index.xml</ulink>
            </para>

            <para>You should now see the following web page: </para>
            <screenshot>
                <graphic fileref="resources/index1.png"/>
            </screenshot>
            <para>Note that this is not the eXist site homepage, but a local copy of the website
                included with the eXist installation. These local files include eXist documentation,
                function libraries, resources, and XQuery examples.</para>
            <note>
                <para>If the above start-up fails, ensure the <envar>EXIST_HOME</envar> and
                        <envar>JAVA_HOME</envar> environment variables - the eXist and Java JDK root
                    directory paths - point to the correct locations. Both variables are set in the
                        <filename>startup.bat</filename> and <filename>startup.sh</filename>
                    scripts.</para>
                <itemizedlist>
                    <listitem>
                        <para>
                            <envar>EXIST_HOME</envar> should point to the directory of the
                            configuration file <filename moreinfo="none">conf.xml</filename>, so
                            that the server uses the path <filename>EXIST_HOME/conf.xml</filename>.
                            For example, if the <envar>EXIST_HOME</envar> path is
                                <filename>C:\Program Files\eXist</filename>, the server will look
                            for <filename>C:\Program Files\eXist\conf.xml</filename></para>
                    </listitem>
                    <listitem>
                        <para><envar>JAVA_HOME</envar> should point to the directory where the Java
                            JDK is installed. A common problem is that the path added by the
                            installer points to the JRE, not the JDK.</para>
                    </listitem>
                </itemizedlist>
                <para>Also ensure that you have "write" permissions set for the <filename
                        moreinfo="none">data</filename> directory located in <filename
                        moreinfo="none">webapp/WEB-INF/</filename>.</para>
            </note>
        </section>
        <section id="sect6">
            <title>Using the Admin Database Interface</title>
            <para>To begin using the database system, you must first create document collections and
                import files to 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 the eXist database using sample XML documents. </para>
            <informaltable>
                <tgroup cols="2">
                    <tbody>
                        <tr>
                            <td>
                                <para>To start using these example applications, you must log in to
                                    the eXist database administration page. To log in, go to the
                                        <guimenuitem>Administration &#187; Admin</guimenuitem>
                                    link (<ulink url="http://localhost:8080/exist/admin/admin.xql"
                                        >http://localhost:8080/exist/admin/admin.xql</ulink>)
                                    located on the sidebar menu on the local eXist homepage (<ulink
                                        url="http://localhost:8080/exist/"
                                        >http://localhost:8080/exist/</ulink>)</para>
                                <para>You should now see the login screen as shown on the right.</para>
                                <para>Enter the username "admin" and leave the password field empty.
                                </para>
                            </td>
                            <td>
                                <screenshot><graphic fileref="resources/admin1.png"/></screenshot>
                            </td>
                        </tr>
                        <tr>
                            <td>
                                <para>Once you have logged in, select <guimenuitem>Examples
                                    Setup</guimenuitem> from the menu on the left. Click on the
                                    "Import Example Data" button to start the setup and begin
                                    downloading example data from the Internet. This will produce a
                                    screen asking if you would also like to download additional data
                                    from the web. Since these files are not required for this test,
                                    we can select the "Skip" button. Once you are more familiar with
                                    eXist, you may want to go back and add the "The XML Acronym
                                    Demystifier" and "Mondial Database" data to try other database
                                    queries.</para>
                            </td>
                            <td>
                                <screenshot><graphic fileref="resources/admin2.png"/></screenshot>
                            </td>
                        </tr>
                        <tr>
                            <td>
                                <para>After the example data has been uploaded, you will be able to
                                    query the sample collections on the "Examples Page." Here you
                                    will find a number of small web applications that employ eXist
                                    and XQuery. The simplest of these applications is the "XQuery
                                    Sandbox" shown on the right (<ulink
                                        url="http://localhost:8080/exist/sandbox/"
                                        >http://localhost:8080/exist/sandbox/</ulink>) which allows
                                    users to submit example queries to the database. This program
                                    provides the easiest way for users to start experimenting with
                                    eXist and XQuery. </para>
                            </td>
                            <td>
                                <screenshot><graphic fileref="resources/sandbox.png"/></screenshot>
                            </td>
                        </tr>
                    </tbody>
                </tgroup>
            </informaltable>

        </section>

        <section id="sect7">
            <title>Using the Java Admin Client</title>

            <para>In addition to the web-based eXist interface, eXist provides a Java-based admin
                client. This application enables users to perform more complex administrative tasks,
                such as user management, security settings and backup/restore. </para>
            <para>This GUI client can be used either as a graphical interface, or through a DOS or
                Unix command-line - which uses parameter options for specific tasks. If no action is
                specified on the command-line, the client will enter "interactive mode" and display
                a graphical login interface. Additional information on using the admin client from
                the command line, is available in the <ulink url="client.xml">client
                documentation</ulink>.</para>
            <para>You can launch the client by doing <emphasis>ONE</emphasis> of the following:</para>
            <procedure>
                <step>
                    <para>For Windows and Mac users, double-click on the desktop shortcut icon (if
                        created) or by selecting the shortcut icon from the start menu</para>
                </step>
                <step>
                    <para>OR launch using Java WebStart:</para>

                    <para>
                        <ulink url="webstart/exist.jnlp">
                            <graphic fileref="resources/webstart.small.jpg"/>
                        </ulink>
                    </para>

                    <para>You can also find the Java WebStart launch icon in the
                            <guimenuitem>Administration</guimenuitem> menu in the left sidebar of
                        all documentation pages. NOTE: Java WebStart needs to be found by the web
                        browser and the eXist jars need to be signed (if you compiled them
                        yourself)!</para>
                </step>
                <step>
                    <para>OR enter the following in a Unix shell or DOS/Windows command prompt:</para>
                    <synopsis format="linespecific">bin\client.bat (DOS/Windows)</synopsis>
                    <synopsis format="linespecific">bin\client.sh (Unix)</synopsis>
                </step>
                <step>
                    <para>OR if both of the above approaches fail to launch the client, you can
                        enter the following on the command-line:</para>
                    <synopsis>java -jar start.jar client</synopsis>
                </step>
            </procedure>
            <informaltable>
                <tgroup cols="2">
                    <tbody>
                        <tr>
                            <td>
                                <para>A screenshot of the client login interface is shown on the
                                    right. At 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. embedded
                                    in an application), which runs in the same process as the
                                    client. This option is useful for backup/restore or mass-uploads
                                    of data (writing to an embedded instance avoids the network
                                    overhead).</para>
                                <para>If you connect to a remote database, the URL field specifies
                                    the location of the db server. The URI scheme used here is
                                    standardized, and for standard database setups, use the
                                    displayed default URI
                                    (xmldb:exist://localhost:8080/exist/xmlrpc). More in-depth
                                    information on server URIs and their function can be found in
                                    the <ulink url="deployment.xml">deployment guide</ulink>.</para>
                                <para>To log in to eXist's default administrator account, use the
                                    "admin" username. if you have not yet changed the admin password
                                    (e.g. your first log in), leave the password field empty. After
                                    clicking "OK", the main client window will open (see the next
                                    screenshot).</para>
                            </td>
                            <td>
                                <screenshot><graphic fileref="resources/client1.png"/></screenshot>
                            </td>
                        </tr>
                        <tr>
                            <td>
                                <para>Once you have logged in, a client window will open. This
                                    window is split into two panels, as well as a top menu and
                                    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 mouseover annotations that explain
                                    their functions.</para>
                            </td>
                            <td>
                                <screenshot><graphic fileref="resources/client2.png"/></screenshot>
                            </td>
                        </tr>
                        <tr>
                            <td>
                                <para>eXist can be used for applications intended for online web
                                    publications, or as an embedded library. If you plan to use
                                    eXist for an online application, you expose it to potential
                                    exploitation, and so it is strongly advised that you first
                                    change the admin password. To do this, follow these steps:</para>
                                <orderedlist>
                                    <listitem>
                                        <para>Open the "Edit User" window by selecting the "Manage
                                            Users" icon (image of a pair of keys) in the
                                        toolbar</para>
                                    </listitem>
                                    <listitem>
                                        <para>At the top, select the "admin" user in the table of
                                            users</para>
                                    </listitem>
                                    <listitem>
                                        <para>Type in your password into the corresponding
                                        fields</para>
                                    </listitem>
                                    <listitem>
                                        <para>Click the "Modify User" button to apply the
                                        changes</para>
                                    </listitem>
                                </orderedlist>
                            </td>
                            <td>
                                <screenshot><graphic fileref="resources/client3.png"/></screenshot>
                            </td>
                        </tr>
                    </tbody>
                </tgroup>
            </informaltable>

        </section>
        <section id="sect8">
            <title>Shutting Down the Database</title>
            <para>It is recommended you properly shut down the database before killing the server
                process. By not doing this, data files may become corrupted. There are several ways
                to trigger a shutdown:</para>
            <procedure>
                <step>
                    <para>Admin Client: select <guimenuitem>Connection &#187;
                        Shutdown</guimenuitem> from the menu.</para>
                </step>
                <step>
                    <para>Web Admin Interface: select the <guimenuitem>Shutdown</guimenuitem> link
                            (<ulink url="http://localhost:8080/exist/admin/admin.xql"
                            >http://localhost:8080/admin.xql</ulink>)</para>
                </step>
                <step>
                    <para>Run the <filename>bin/shutdown.sh</filename> (Unix) or
                            <filename>shutdown.bat</filename> (DOS/Windows) scripts.</para>
                </step>
                <step>
                    <para>Manually enter on the command-line:</para>
                    <synopsis>java -jar start.jar shutdown</synopsis>
                    <para>To specify the username and password, pass the <parameter>-u</parameter>
                        and <parameter>-p</parameter> parameters on the command-line. By default,
                        the command attempts to shut down the database running at the default URI:
                        xmldb:exist://localhost:8080/exist/xmlrpc/db. To shutdown a different
                        database, use the corresponding URI and the <parameter>-l</parameter>
                        parameter. For example: </para>
                    <synopsis>java -jar start.jar shutdown -u admin -p adminpass -l xmldb:exist://localhost:8080/exist/xmlrpc/db</synopsis>
                </step>
            </procedure>
            <note>
                <para>If eXist has been deployed as a web application in a web server other than the
                    supplied Jetty server, calling shutdown will close the database instance, but
                    not the server process of the web server. Since eXist does not know in which
                    environment it is running, it can only close itself. Regardless, closing the
                    database explicitly is always a good idea.</para>
            </note>
        </section>
        <section id="sect9">
            <title>Starting eXist as a service</title>
            <para>Instead of manually running the eXist server in a shell window, you may prefer to
                run it as a background service which is automatically launched during system
                startup. eXist comes with pre-configured scripts that use Tanuki Software's <ulink
                    url="http://wrapper.tanukisoftware.org">Java Service Wrapper</ulink> to handle
                the setup procedure. The required scripts are contained in the directory
                    <filename>tools/wrapper</filename>. On Windows, you can simply choose the option
                to <emphasis>Install eXist as Service</emphasis> from the eXist menu created in the
                start menu. You can also call <filename>tools/wrapper/bin/install.bat</filename>
                instead. This will install eXist and Jetty as a Windows service.</para>

            <para>After executing the install.bat script, you should find eXist listed in the
            list of services currently registered with Windows:</para>

            <screenshot>
                <graphic fileref="resources/services.png"/>
            </screenshot>

            <para>Once the service is registered, you can launch it via the service manager as
            shown in the screenshot or from the command line:</para>

            <synopsis>
                cd tools\wrapper\bin
                wrapper.exe --start ..\conf\wrapper.conf
            </synopsis>
            
            <para>For Linux, all of the start/shutdown scripts can be found in
                    <filename>tools/wrapper/bin/exist.sh</filename>. You can create a link to this
                file from the <filename>init.d</filename> directory of your distribution (where all
                of the start/shutdown scripts reside). Normally, the directory will be
                    <filename>/etc/init.d</filename>. For example:</para>

            <synopsis>ln -s $EXIST_HOME/tools/wrapper/bin/exist.sh /etc/init.d/exist</synopsis>

            <para>You can then add the service to the correct system runlevel. Check with your Linux
                distribution for instructions.</para>
        </section>
        <section id="sect10">
            <title>If Something Goes Wrong ...</title>

            <para>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 <emphasis>log4j-package</emphasis> to write output logs to
                files. By default, this output is written to the directory <filename moreinfo="none"
                    >webapp/WEB-INF/logs</filename>. Or, if you are running eXist as a Windows or
                Unix service, check the directory <filename>tools/wrapper/logs</filename>. The main
                log files for eXist itself are <filename>exist.log</filename> and
                    <filename>xmldb.log</filename>. The other log files show output from Cocoon. </para>

            <para>If you encounter a problem you are unable to fix, check the <ulink
                    url="index.xml#mailing">mailing list</ulink> archives for postings on similar
                errors. If you cannot find a posting, or you are still unsure about the problem, you
                might 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, and ensure you post the server-side, and not the client-side messages
                (client-side messages such as browser errors are not useful for
            troubleshooting).</para>
        </section>
        <section id="sect11">
            <title>Resources</title>
            <itemizedlist>
                <listitem>
                    <para>
                        <ulink url="http://www.w3.org/XML/">W3C Extensible Markup Language
                        (XML)</ulink>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <ulink url="http://www.w3.org/TR/xquery/">W3C XML Query Language</ulink>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <ulink url="http://wiki.exist-db.org/space/Tutorials/">User-contributed
                            (Wiki) Tutorials</ulink>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <ulink url="http://wiki.exist-db.org/space/HowTos/">User-contributed (Wiki)
                            How-Tos</ulink>
                    </para>
                </listitem>
            </itemizedlist>
        </section>
        <section id="appendix">
            <title>Running Executable Files</title>
            <para>Included in the distribution are a number of useful <filename>.sh</filename> (Unix
                Shell) and <filename>.bat</filename> (DOS batch) programs located in the
                    <filename>bin</filename> 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 installed the <filename>exist.war</filename> file (Web
                Application Archive), you will find the <filename>bin</filename> directory in the
                location the <filename>.war</filename> file was unpacked.</para>
            <para>These shell and batch scripts are simply wrappers (interfaces between the
                executable Java programs) around the bootstrap loader contained in the jar file
                    <filename>start.jar</filename>.</para>
            <para>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.</para>
            <para>To manually launch these scripts:</para>
            <variablelist>
                <varlistentry>
                    <term>startup.sh (Unix) / startup.bat (Windows)</term>
                    <listitem>
                        <para>Enter on the command-line:</para>
                        <synopsis>java -jar start.jar jetty</synopsis>
                        <para>Description: Starts the included Jetty web server at port 8080. eXist
                            and Cocoon (a web development framework) are installed as a web
                            application, located at <ulink url="http://localhost:8080/exist/"
                                >http://localhost:8080/exist/</ulink>. </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>shutdown.sh (Unix) / shutdown.bat (Windows)</term>
                    <listitem>
                        <para>Enter on the command-line:</para>
                        <synopsis>java -jar start.jar shutdown</synopsis>
                        <para>Description: Closes running instance of eXist. If eXist has been
                            started with <filename>startup.sh</filename>, calling
                                <filename>shutdown.sh</filename> 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.
                            However, you should <emphasis>always</emphasis> call
                            <filename>shutdown</filename> before killing the server process. This
                            issue is discussed in detail in the succeeding section
                                <emphasis>Shutting Down the Database</emphasis>.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>server.sh (Unix) / server.bat (Windows)</term>
                    <listitem>
                        <para>Enter on the command-line:</para>
                        <synopsis>java -jar start.jar server</synopsis>
                        <para>Description: Launches eXist as a stand-alone server process. In this
                            setup, eXist is only accessible through the XMLRPC and the simple,
                            built-in HTTP interface.</para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>client.sh (Unix) / client.bat (Windows)</term>
                    <listitem>
                        <para>Enter on the command-line:</para>
                        <synopsis>java -jar start.jar client</synopsis>
                        <para>Description: Launches the Java Administration Client - a graphical
                            database interface. By default, this application is also launched if no
                            application is selected on the command-line:</para>
                        <synopsis>java -jar start.jar</synopsis>
                        <para>The Java Admin Client is discussed in detail the succeeding section
                                <emphasis>Java Admin Client</emphasis></para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </section>
    </chapter>
</book>
