Skip to content

We no longer support building a WAR file #318

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
duncdrum merged 1 commit into from
Apr 2, 2019
Merged

We no longer support building a WAR file #318

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 2 additions & 22 deletions src/main/xar-resources/data/configuration/configuration.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,28 +22,8 @@
<title>Main configuration file</title>

<para>The main configuration file for <literal>eXist-db</literal> is called
<literal>conf.xml</literal>, which is loaded from different directories depending on the
server set-up (see <link xlink:href="deployment">Server Deployment</link> for more
information). Specifically:</para>
<itemizedlist>
<listitem>
<para>If you installed the standalone eXist-db distribution with the installer, the
<literal>conf.xml</literal> file located in the root directory of the
distribution (as specified by the system property
<literal>exist.home</literal>).</para>
<para/>
</listitem>
<listitem>
<para>If eXist-db is installed as a web application (packaged in a
<literal>.war</literal> file) in a servlet engine like tomcat, <literal>
conf.xml</literal> is read from the <literal>WEB-INF</literal> directory of the
web application.</para>
<para>eXist-db normally has no access to files outside the context in which it is
running when it is deployed as part of a web application. Therefore, when eXist
is deployed in this way, the configuration is read from the
<literal>WEB-INF</literal> directory.</para>
</listitem>
</itemizedlist>
<literal>conf.xml</literal>, which is loaded the root directory of the
distribution (as specified by the system property <literal>exist.home</literal>).</para>

<para>The configuration file <literal>conf.xml</literal> is divided into eleven
sections:</para>
Expand Down
48 changes: 1 addition & 47 deletions src/main/xar-resources/data/deployment/deployment.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,52 +143,6 @@

<!-- ================================================================== -->

<sect1 xml:id="deploy-servlet">
<title>Deploying in a Servlet Container</title>

<para>The standard distribution by default launches eXist-db as a web application deployed
in a <link condition="_blank" xlink:href="http://eclipse.org/jetty/">Jetty</link>
servlet container.</para>
<para>The Jetty configuration can be found in
<literal>tools/jetty/webapps/exist-webapp-context.xml</literal>. It defines a single web
application context value <literal>&lt;Set
name="contextPath"&gt;/exist&lt;/Set&gt;</literal>, mapped to the
<literal>webapp</literal> directory. This value can be set to either
<literal>/exist</literal> or <literal>/</literal>. Users modifying this value should
subsequently remove the <literal>portal</literal> folder at <literal>
/tools/jetty/webapps</literal>, which contains the default exist-db splashscreen
displayed during certain redirects.</para>
<para>Jetty is small, efficient and stable, so there is no need to switch to a different
servlet engine unless your server setup requires this. However, it is not difficult to
deploy eXist in a different servlet container, e.g. Apache's Tomcat.</para>
<para>We usually provide a <literal>.war</literal> web archive for all major releases. You
may either download that or, if you already installed the standard distribution, build a
<code>.war</code> archive yourself. For details on how to do this, see <link xlink:href="exist-building">Building eXist-db</link> </para>
<para>To install the <code>.war</code>, just copy it into the corresponding folder below
your servlet engine installation (usually <literal>webapps</literal>) and rename it to
<literal>exist.war</literal>. The servlet engine will normally unpack the file when you
restart the server. To have better control of where the file is unpacked, you can also
create a directory <literal>exist</literal> below the <literal>webapps</literal> folder
and manually extract the <code>.war</code> there. For instance:</para>
<programlisting>jar xfv exist.war</programlisting>
<important>
<para>Please remember that the <literal>data</literal> and <literal>log</literal>
directories need to be writable!</para>
</important>

<para>There are a few differences between the standard distribution and the
<code>.war</code> install. In particular, the configuration files are found in the
<literal>WEB-INF</literal> directory, including the important files
<literal>conf.xml</literal> (eXist configuration) and <literal>log4j.xml</literal>
(logging). The example data is in <literal>samples</literal>.</para>
<para>To start the <link xlink:href="java-admin-client">Java Admin Client</link>, use the
following command (from within <literal>exist</literal> web application's root
directory):</para>
<programlisting>java -jar WEB-INF/lib/start.jar client -ls</programlisting>
</sect1>

<!-- ================================================================== -->

<sect1 xml:id="run-stand-alone">
<title>Running as a Stand-alone Server</title>

Expand Down Expand Up @@ -596,4 +550,4 @@
target directory (which we prepared above), and compile and run it with:</para>
<programlisting>javac TestDB.java java -Dexist.initdb=true -Dexist.home=. TestDB</programlisting>
</sect1>
</article>
</article>
4 changes: 2 additions & 2 deletions src/main/xar-resources/data/documentation/documentation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -435,7 +435,7 @@
<varlistentry>
<term> <link xlink:href="exist-building">Building eXist</link> </term>
<listitem>
<para>How to build Java <code>.jar</code> or <code>.war</code> files from an
<para>How to build Java <code>.jar</code> files from an
eXist distribution.</para>
</listitem>
</varlistentry>
Expand Down Expand Up @@ -552,7 +552,7 @@
<varlistentry>
<term> <link xlink:href="exist-building">Building eXist</link> </term>
<listitem>
<para>How to build Java <code>.jar</code> or <code>.war</code> files from an
<para>How to build Java <code>.jar</code> files from an
eXist distribution.</para>
</listitem>
</varlistentry>
Expand Down
67 changes: 26 additions & 41 deletions src/main/xar-resources/data/exist-building/exist-building.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,38 +12,7 @@
</info>
<!-- ================================================================== -->

<para>This article will tell you how to build a Java <code>.war</code> or <code>.jar</code> file for eXist-db. If you are building exist-db from source, please also check the <link xlink:href="https://github.com/eXist-db/exist/blob/develop/BUILD.md">build instructions</link> in the source-code repo.</para>

<!-- ================================================================== -->

<sect1 xml:id="war">
<title>Building a <code>.war</code> file from the Standard Distribution</title>

<para>If you would like to deploy eXist-db into an existing servlet engine (e.g. tomcat), you will need a <literal>.war</literal> file. We no
longer distribute a <literal>.war</literal> build, but it is easy to create one from the standard distribution by
<emphasis>repackaging</emphasis> (not building) it:</para>
<orderedlist>
<listitem>
<para>
<emphasis role="bold">Install the standard distribution</emphasis>
</para>
<para>Get a standard distribution from eXist-db <link xlink:href="http://exist-db.org/exist/apps/homepage/index.html#download" condition="_blank">download
page</link>. Install it into a directory of your choice. Make sure you include the <emphasis>source package</emphasis>.</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">Generate the WAR</emphasis>
</para>
<para>Open a command line prompt and change to the directory where you just installed eXist-db. Call</para>
<programlisting>build.sh dist-war</programlisting>
<para>or</para>
<programlisting>build.bat dist-war</programlisting>
<para>once. This will generate a <literal>.war</literal> archive into directory <literal>dist</literal>.</para>
</listitem>
</orderedlist>
<para>Note that generating a <code>.war</code> archive does only repackage the files in the distribution. So if the distribution worked properly
for you, the <code>.war</code> should as well. You don't need to recompile eXist-db or sign any jars.</para>
</sect1>
<para>This article will tell you how to build a Java <code>.jar</code> file for eXist-db. If you are building exist-db from source, please also check the <link xlink:href="https://github.com/eXist-db/exist/blob/develop/BUILD.md">build instructions</link> in the source-code repo.</para>

<!-- ================================================================== -->

Expand Down Expand Up @@ -92,11 +61,11 @@
<title>Using the Build System</title>

<para>You can rebuild all eXist-db packages from the standard distribution or the GitHub repository. You can even create a new distribution from
the one you installed. For example, assume you installed eXist using the installer GUI, but you need to have an exist.war package for deployment
within a different servlet engine. Just call the main build script (<literal>build.sh</literal> or <literal>build.bat</literal>) and pass it the
target <literal>dist-war</literal>:</para>
<programlisting>build.sh dist-war</programlisting>
<para>This will create a fresh <literal>.war</literal> archive in the <literal>dist</literal> directory.</para>
the one you installed. For example, assume you installed eXist using the installer GUI, but you need to have a <literal>.tar.bz2</literal> package for deployment
to a server. Just call the main build script (<literal>build.sh</literal> or <literal>build.bat</literal>) and pass it the
target <literal>dist-bz2</literal>:</para>
<programlisting>build.sh dist-bz2</programlisting>
<para>This will create a fresh <literal>.tar.bz2</literal> archive in the <literal>dist</literal> directory.</para>
<note>
<para>To be able to use the build system, you need to include the "source" module when selecting installable packages in the installer
GUI.</para>
Expand Down Expand Up @@ -181,18 +150,34 @@
</row>
<row>
<entry>
<para>dist-tgz</para>
<para>dist-dir</para>
</entry>
<entry>
<para>Packages eXist-db into a <literal>.tgz</literal> file.</para>
<para>Packages eXist-db into a directory.</para>
</entry>
</row>
<row>
<entry>
<para>dist-bz2</para>
</entry>
<entry>
<para>Packages eXist-db into a <literal>.tar.bz2</literal> file.</para>
</entry>
</row>
<row>
<entry>
<para>dist-war</para>
<para>dist-tar</para>
</entry>
<entry>
<para>Packages eXist-db into a <literal>.war</literal> file for deployment within a servlet engine.</para>
<para>Packages eXist-db into a <literal>.tar</literal> file.</para>
</entry>
</row>
<row>
<entry>
<para>dist-tgz</para>
</entry>
<entry>
<para>Packages eXist-db into a <literal>.tgz</literal> file.</para>
</entry>
</row>
<row>
Expand Down
2 changes: 1 addition & 1 deletion src/main/xar-resources/data/production_good_practice/production_good_practice.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -422,7 +422,7 @@
<sect1 xml:id="web-deploy">
<title>Web Deployments</title>

<para>eXist-db, like any Web Application Server (Tomcat, WebLogic, GlassFish, etc.), should
<para>eXist-db, like any Web Application Server, should
not be directly exposed to the Web. Instead, we strongly recommend proxying eXist-db
through a Web Server such as <link condition="_blank"
xlink:href="http://wiki.nginx.org/Main">Nginx</link> or <link condition="_blank"
Expand Down
23 changes: 0 additions & 23 deletions src/main/xar-resources/data/validation/validation.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -422,29 +422,6 @@
<para>To avoid potential deadlocking it is considered good practice to store XML
instance documents and grammar documents in separate collections.</para>
</listitem>
<listitem>
<para>Tomcat has an long standing bug which makes it impossible to register a custom
protocol handler (object <link condition="_blank"
xlink:href="https://docs.oracle.com/javase/10/docs/api/java/net/URLStreamHandler.html"
><code>URLStreamHandler</code></link>) to the JVM. The alternative is to
register the object by setting the system property
<code>java.protocol.handler.pkgs</code> but this fails as well.</para>
<para>As a result, the validation features are only partly useable in Tomcat. There
are two alternatives: (1) switch to a recent version of Jetty, or (2) use
absolute URLs pointing the REST interface, e.g.
<code>http://localhost:8080/exist/rest/db/mycollection/schema.xsd</code>.</para>
</listitem>
<listitem>
<para>eXist relies heavily on features provided by the Xerces XML parser. Out of the
box the eXist izPack installer provides all required <code>.jar</code> files.
However, when eXist is installed in for instance Tomcat, the required parser
libraries need to be copied manually from the eXist <code>lib/endorsed</code>
directory into the server <link condition="_blank"
xlink:href="http://tomcat.apache.org/tomcat-5.5-doc/class-loader-howto.html"
>endorsed</link> directory.</para>
<para>Required endorsed files: <code>resolver-*.jar xalan-*.jar serializer-*.jar
xercesImpl-*.jar</code> </para>
</listitem>

<listitem>
<para>The explicit validation is performed by <link condition="_blank"
Expand Down