<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: advanced-installation.xml 18426 2013-05-18 20:35:41Z joewiz $ --><book><bookinfo><productname>eXist-db – Open Source Native XML Database</productname><title>Advanced Installation Methods</title><date>October 2012</date></bookinfo><chapter><title>Advanced Installation Methods</title><section><title>Introduction</title><para>The eXist-db <ulink url="quickstart.xml">Quick Start</ulink> document contains
                basic instructions for installing eXist. This article explains more advanced methods
                of installing and running eXist. </para></section><section id="headless"><title>Headless Installation</title><para>The eXist-db installer requires a graphical desktop in order to launch. However,
                If you wish to install eXist-db on a headless system, use the
                    <command>-console</command> parameter when launching the installer from the
                command line. For example:</para><synopsis>java -jar eXist-{version}.jar -console</synopsis><para>In console mode, the installer will prompt for several parameters. It first asks
                for an installation directory. Please don't be confused if the output stops after
                showing the line "Select target path [...]": you are expected to enter a path or
                confirm the default by pressing <keysym>Enter</keysym>. A dump of a sample
                interaction is shown below:</para><screen>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 ]</screen></section><section id="service"><title>Running eXist-db as a Service</title><para>Instead of manually running the eXist-db server in a shell window, you may prefer
                to run it as a background service which is automatically launched during system
                startup. This can be convenient, because eXist-db can continue to run even after
                users have logged off of the system.</para><para>eXist-db 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>. 
                    </para><section id="windows"><title>Windows</title><para>
                    On Windows, you can simply choose the option
                to <emphasis>Install eXist-db as Service</emphasis> from the eXist-db menu created
                in the start menu. You can also call
                    <filename>tools/wrapper/bin/install.bat</filename> instead. This will install
                eXist-db and Jetty as a Windows service.</para><note><para>Installing eXist-db as a service on Windows Vista requires full administrator
                    rights. Right click on the start menu item and select "Run as administrator".
                    You may need to do this even if you are already logged in as an
                    administrator.</para></note><para>After executing the install.bat script, you should find eXist-db 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>tools\wrapper\bin\wrapper.exe --start ..\conf\wrapper.conf</synopsis></section><section id="linux"><title>Unix</title><para>For Unix based systems (Linux, Mac OS X) the start/shutdown scripts can be found in
                    <filename>tools/wrapper/bin/</filename>.</para><para>The easiest way to get eXist-db started during 
                    initialization of the system is to run the following command: 
                    <synopsis>sudo tools/wrapper/bin/exist.sh install</synopsis> 
                    This works for Mac OS X and many Linux distributions.</para><para>
                    Please note it might be required to set some variables for the specific system, e.g. "RUN_AS_USER" (to have eXist-db started as a specific user) and "USE_UPSTART" (when using the <ulink url="http://en.wikipedia.org/wiki/Upstart">Upstart</ulink> feature which is available in many Linux variants).
                    Details can be found on the Tankuni website:</para><para><itemizedlist><listitem><para><ulink url="http://wrapper.tanukisoftware.com/doc/english/launch-nix.html#boot">Installing The Application To Start on Reboot</ulink></para></listitem><listitem><para><ulink url="http://wrapper.tanukisoftware.com/doc/english/launch-nix-boot-debian.html">Installing The Application To Start on Reboot (Debian Linux)</ulink></para></listitem><listitem><para><ulink url="http://wrapper.tanukisoftware.com/doc/english/launch-nix-boot-solaris.html">Installing The Application To Start on Reboot (Solaris)</ulink></para></listitem></itemizedlist></para><para>As an advanced alternative it is possible to 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="other"><title>Other platforms</title><para>Out of the box the by eXist-db provided 'wrapper' supports the following mainstream platforms:
                    <itemizedlist><listitem><para>Windows x86 (32bit/64bit)</para></listitem><listitem><para>Linux x86 (32bit/64bit) &amp; IA (64bit) </para></listitem><listitem><para>Mac OS X x86 (32bit/64bit) </para></listitem><listitem><para>Solaris x86 (32bit/64bit) &amp; SPARC (32bit/64bit)</para></listitem></itemizedlist>
                    Support for additional platforms can be obtained by
                    downloading the "Delta Pack" from the
                    <ulink url="http://wrapper.tanukisoftware.org">Tanuki software</ulink> website. 
                    Available platforms are: AIX (PPC), FreeBSD (x86), HPUX and Linux (PPC,ARM). 
                </para></section></section><section id="bin-executables"><title>About the Scripts in the bin Directory</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. Whether you have installed the source distribution or
                used the installer, you can find this directory in the root directory of the
                installation.
                <!-- 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 that 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 --> is 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 -p youradminpassword</synopsis><para>Description: Closes the 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. 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>