<?xml version="1.0" encoding="UTF-8"?>
<book><bookinfo><productname>eXist-db – Open Source Native XML Database</productname><title>Quick Start</title><date>October 2012</date></bookinfo><chapter><title>Quick Start</title><section id="overview"><title>Overview</title><para>Installing eXist-db on your computer is quick and easy. First, confirm that your
                system meets the requirements. Next, download the installer and follow the
                installation instructions here. Before you know it you'll be up and running with
                eXist-db.</para></section><section id="system-requirements"><title>System Requirements</title><para>eXist-db is compatible with all recent versions of Linux, Mac OS X, and Windows.
                Out of the box, eXist-db requires at least 512 MB of RAM and about 200 MB of disk
                space. Administrative privileges are not required to install or run eXist-db, but
                certain installation procedures are not possible without administrative privileges.
                The critical requirement is that Java be installed.</para><note id="about-java"><title>eXist-db and Java</title><para>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
                    install the version that eXist-db requires: Java 6 or 7. eXist-db can run with
                    both the Java "JRE" (Java Runtime Environment) and the "JDK" (Java Development
                    Kit). The JRE is adequate for running eXist-db; you do not need the JDK unless
                    you intend to compile eXist-db from its source code. For instructions about
                    running Java on your operating system, see Oracle's <ulink url="http://www.java.com/en/download/help/index_installing.xml">Installing
                        Java</ulink> page.</para><para>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. Instructions that eXist-db users
                    have found useful include: <ulink url="http://livingtao.blogspot.com/2012/01/few-easy-steps-to-install-sunoracle-jdk.html">Amazon Linux</ulink>, <ulink url="http://www.webupd8.org/2012/01/install-oracle-java-jdk-7-in-ubuntu-via.html">Ubuntu</ulink> and <ulink url="http://www.webupd8.org/2012/06/how-to-install-oracle-java-7-in-debian.html">Debian</ulink>.</para><para>Special note: In general it recommended to use the Oracle Java VM, this is the safest choice. The OpenJDK 7 is a good open source alternative for the Oracle JVM. Due to reported compatibility issues it is NOT recommended to use "OpenJDK6" (IcedTea) and "GNU Compiler for Java" (GCJ) which are shipped by several Linux distributions.</para><para>Details of the Java VM can be obtained via the following command (two results displayed):
                        <synopsis format="java">java -version
                        
java version "1.7.0_21"
Java(TM) SE Runtime Environment (build 1.7.0_21-b12)
Java HotSpot(TM) 64-Bit Server VM (build 23.21-b01, mixed mode
    
java version "1.6.0_27"
OpenJDK Runtime Environment (IcedTea6 1.12.5) (6b27-1.12.5-0ubuntu0.12.04.1)
OpenJDK 64-Bit Server VM (build 20.0-b12, mixed mode)    
</synopsis></para></note></section><section id="installation"><title>Installing eXist-db</title><para>Download the installer for the latest stable release of eXist-db from the <ulink url="download.xml">Downloads</ulink> page. The installer is a single file called
                <filename>eXist-setup-[version]-revXXXXX.jar</filename>. Here, [version] and
                XXXXX reflect the version and revision numbers of eXist-db, and .jar is a Java
                Archive file. We recommend that you download the <emphasis>latest stable
                    release</emphasis>.</para><para>Once the download has completed, launch the eXist-db installer. To launch the
                installer on Mac or Windows, simply double-click the .jar you downloaded. (On Mac OS
                X 10.7 and higher, a security feature called <ulink url="http://support.apple.com/kb/HT5290">Gatekeeper</ulink> 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 on the .jar file, and selecting the "Open With ... Java" option. Or,
                to launch the installer from the command line, enter the following command:
                <synopsis format="linespecific">java -jar eXist-setup-[version]-revXXXXX.jar</synopsis>
                (Windows and Mac users can also use the command line procedure, but most users
                prefer the graphical installer. For installs on a headless system, see <ulink url="advanced-installation.xml#headless">Headless Installation</ulink>.)</para><para>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:</para><procedure><step><para><emphasis>Choose the Installation Directory</emphasis>: 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.</para></step><step><para><emphasis>Choose the Data Directory</emphasis>: 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.</para></step><step><para><emphasis>Choose the Admin Password</emphasis>: 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. Best to choose a unique password.</para><para><emphasis>Memory Settings</emphasis>: 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. </para><graphic fileref="resources/installer1.png"/></step><step><para><emphasis>Select the Packs To Install</emphasis>: 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.</para><graphic fileref="resources/installer2.png"/></step><step><para><emphasis>Installing Files</emphasis>: The installer will now start the
                        install process.</para></step><step><para><emphasis>Processing</emphasis>: Your newly installed eXist-db is started
                        once to configure the admin password.</para></step><step><para>(Windows and Linux only) <emphasis>Start Menu and/or Desktop Shortcut
                            Options</emphasis>: The installer can create convenient desktop
                            shortcuts and Start Menu entries for starting and accessing
                            eXist-db.</para></step></procedure><para>When the installer is finished installing eXist-db, click Quit to close it.</para></section><section id="launching"><title>Launching eXist-db</title><para>On the Mac, double-click eXist-db's application icon where you installed eXist-db.
                On Linux or Windows, select the <emphasis>eXist-db Database Startup</emphasis>
                desktop shortcut icon or Start Menu entry you created at the end of the
                installation. (To run eXist as a background service, see <ulink url="advanced-installation.xml#service">Running eXist-db as a
                Service</ulink>.)</para><para>You'll see a splash screen appear showing the eXist-db logo. Upon first startup,
                eXist-db will upload the applications you selected in the installer into the
                database. This may take a while and is only done the first time.</para><figure><title>Splash Screen during Startup</title><graphic fileref="resources/launch1.png" align="center"/></figure><para>Once eXist is started, you will see a new menu bar icon (Mac) or system tray icon
                (Linux/Windows) for eXist-db. This icon gives you access 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.</para><figure><title>Menu Bar Icon on Mac</title><graphic fileref="resources/launch2.png" align="center"/></figure><note><title>Linux Installation</title><para>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.</para><para>Also, the desktop integration does not work properly on all versions of Linux. When using the desktop
                    launcher, your mileage may vary. However, you may always use the provided shell scripts (<filename>bin/startup.sh</filename>)
                    to launch eXist-db in the normal way without desktop integration.
                    </para></note><para>You can also start eXist-db manually if you feel comfortable with the command
                line:</para><procedure><step><para>Open your terminal or command prompt.</para></step><step><para>Change (cd) to the directory where you installed eXist-db (e.g.,
                        "<filename>/usr/local/lib/exist/</filename>" for Linux,
                        "<filename>/Applications/eXist/</filename>" for Mac, or
                        "<filename>C:\Program Files\eXist</filename>" for Windows).</para></step><step><para>Just calling <filename>start.jar</filename> will start eXist-db via the desktop launcher:</para><synopsis>java -jar start.jar</synopsis><para>If you want to launch eXist-db without a GUI, use the shell scripts in <filename>bin/</filename>. 
                        On Linux or Mac, 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>For more information about these startup scripts, see <ulink url="advanced-installation.xml#bin-executables">About the Scripts in the bin
                    Directory</ulink>.</para><note><title>Having trouble?</title><para>If you suspect you have had a problem launching eXist-db, see our article on
                    <ulink url="troubleshooting.xml">Troubleshooting</ulink>. Also see <ulink url="advanced-installation.xml">Advanced Installation</ulink>.</para></note></section><section id="diving-in"><title>Diving In</title><para>After successful installation, the first thing you'll want to do is to access the
                <ulink url="{dashboard}/">Dashboard</ulink>, the central administration and application hub of eXist-db.
                If the system tray icon works on your system, select "Open Dashboard" from the popup menu. Or just open a web browser
                and enter the following URL:</para><para><ulink url="http://localhost:8080/exist/">http://localhost:8080/exist/</ulink></para><para>You should now see the following web page:</para><screenshot><graphic fileref="resources/index1.png" width="300"/></screenshot><para>See it? Congratulations! (Not seeing it? See our article on <ulink url="troubleshooting.xml">Troubleshooting</ulink>.)</para><para>Do you notice the similarity between the page and the homepage of exist-db.org?
                You are actually now running a complete, local copy of the eXist-db.org website on
                your computer.</para><para>Now that you have successfully installed eXist-db, you are ready to dive in. Your
                local copy includes everything you need to do so: the eXist-db <ulink url="{dashboard}/">Dashboard</ulink> app, which lets you add
                application packages from eXist-db.org's public repository (including all of
                eXist-db's documentation), upload your own data to the database, and perform
                administrative tasks (like creating user accounts). It also includes the <ulink url="{eXide}/">eXide</ulink> web application for querying the database
                and creating your own applications.</para><para>To learn more about the Dashboard app and installing applications from the
                eXist-db public application repository, see the article on the <ulink url="dashboard.xml">Dashboard</ulink>. To learn more about the eXide app, see
                the article on <ulink url="{eXide}/docs/doc.html">eXide</ulink>.</para></section><section id="shutting-down"><title>Shutting Down the Database</title><para>Just as you shouldn't pull the plug on your computer without safely shutting it
                down, you should learn the methods for safely shutting eXist-db down. Improperly
                shutting down the database can corrupt your data files, so follow one of these
                procedures to properly shut down eXist-db.</para><procedure><step><para>The system tray popup menu has an option <guimenuitem>Stop server</guimenuitem>.
                    You may also choose <guimenuitem>Quit (and stop server)</guimenuitem> to shut down
                    eXist-db and the system tray launcher at the same time.</para></step><step><para>From the <ulink url="{dashboard}">Dashboard App</ulink>: select
                        the Shutdown button</para></step><step><para>From the command line, run the <filename>bin/shutdown.sh</filename>
                        (Linux/Mac) or <filename>shutdown.bat</filename> (DOS/Windows) shutdown
                        scripts, using your admin account's username and password.</para><synopsis>bin/shutdown.sh -u admin -p youradminpassword</synopsis><synopsis>bin/shutdown.bat -u admin -p youradminpassword</synopsis></step><step><para>From the command line, run the java command, using your admin account's
                        password:</para><synopsis>java -jar start.jar shutdown -u admin -p youradminpassword</synopsis></step><step><para>From the <ulink url="java-admin-client.xml">Java Admin Client</ulink>: select
                        Connection » Shutdown from the menu.</para></step></procedure></section></chapter></book>