|
| 1 | +<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?> |
| 2 | +<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?> |
| 3 | +<article version="5.0" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> |
| 4 | + |
| 5 | + <info> |
| 6 | + <title>Containerization via Docker</title> |
| 7 | + <date>1Q20</date> |
| 8 | + <keywordset> |
| 9 | + <keyword>application-development</keyword> |
| 10 | + <keyword>operations</keyword> |
| 11 | + </keywordset> |
| 12 | + </info> |
| 13 | + |
| 14 | + <para>This article covers the configuration and use cases of the official |
| 15 | + <link xlink:href="https://hub.docker.com/r/existdb/existdb/">docker images</link> |
| 16 | + for eXist-db</para> |
| 17 | + |
| 18 | + <sect1 xml:id="container-intro"> |
| 19 | + <title>Running exist inside a container</title> |
| 20 | + <para>Container have become a popular means of distributing software without the need to worry hardware and software requirements other then the ability to run containers. Containers offer powerful features for continious deployment of production |
| 21 | + systems, and convenient ways for testing software without interference from external dependencies. How it looks on my computer is how it looks on yours.</para> |
| 22 | + |
| 23 | + <sect2 xml:id="official-images"> |
| 24 | + <title>The official images</title> |
| 25 | + <para>We offer minimal images of eXist-db which are automatically updated as part of the build-test life-cycle. The images are based on Google Cloud Platform's |
| 26 | + <link xlink:href="https://github.com/GoogleCloudPlatform/distroless"> |
| 27 | + Distroless Docker Images</link>. You can find the source code |
| 28 | + <link xlink:href="https://github.com/eXist-db/exist/tree/develop/exist-docker">here</link>.</para> |
| 29 | + <para>Next to fully tagged version, we have two rolling release channels:</para> |
| 30 | + <orderedlist> |
| 31 | + <listitem> |
| 32 | + <para> |
| 33 | + <code>release</code>: for the latest stable releases based on the master branch.</para> |
| 34 | + </listitem> |
| 35 | + <listitem> |
| 36 | + <para> |
| 37 | + <code>latest</code>: for last commit to the develop branch (within minutes of each commit).</para> |
| 38 | + </listitem> |
| 39 | + </orderedlist> |
| 40 | + </sect2> |
| 41 | + </sect1> |
| 42 | + |
| 43 | + <sect1 xml:id="container-how-to"> |
| 44 | + <title>How to get started</title> |
| 45 | + <para>First you need to download an images:</para> |
| 46 | + <para><code>docker pull existdb/existdb:latest</code></para> |
| 47 | + <para>Then you can start the container using that image:</para> |
| 48 | + <para><code>docker run -it -d -p 8080:8080 -p 8443:8443 --name exist existdb/existdb:latest</code></para> |
| 49 | + <sect2 xml:id="docker-what"> |
| 50 | + <title>What does this do?</title> |
| 51 | + <para>You have just download and started eXist-db without launching an installer or having to provide java. More specifically:</para> |
| 52 | + <itemizedlist> |
| 53 | + <listitem> |
| 54 | + <para><code>-it</code>: allocates a <literal>TTY</literal> and keeps <literal>STDIN</literal> open. This allows you to interact with the running Docker container via your console. |
| 55 | + </para> |
| 56 | + </listitem> |
| 57 | + <listitem> |
| 58 | + <para><code>-d</code>: detaches the container from the terminal that started it. So your container won't stop when you close the terminal.</para> |
| 59 | + </listitem> |
| 60 | + <listitem> |
| 61 | + <para><code>-p</code>: maps the Containers internal and external port assignments (we recommend sticking with matching pairs). This allows you to connect to the eXist-db Web Server running in the Docker container.</para> |
| 62 | + </listitem> |
| 63 | + <listitem> |
| 64 | + <para><code>--name</code>: lets you provide a name (instead of using a randomly generated one)</para> |
| 65 | + </listitem> |
| 66 | + </itemizedlist> |
| 67 | + <para>The only required parts are <code>docker run existdb/existdb</code>.</para> |
| 68 | + <para>For a full list of available options see the official <link xlink:href="https://docs.docker.com/engine/reference/commandline/run/">Docker documentation</link>. |
| 69 | + You can now access your running instance by going go <literal>localhost:8080 </literal> inside your browser. To stop the container:</para> |
| 70 | + <para><code>docker stop exist</code></para> |
| 71 | + </sect2> |
| 72 | + </sect1> |
| 73 | + <sect1 xml:id="container-interact"> |
| 74 | + <title>Interacting with the running container</title> |
| 75 | + <para>You can interact with a running container as if it were a regular Linux host. |
| 76 | + <important><para>GCR base images do not contain a shell this is by design. You can issue shell-like commands to the Java admin client, as we do throughout this readme, but you can't open the shell in interactive mode.</para></important> |
| 77 | + We'll continue to use <code>exist</code> as the name of our container:</para> |
| 78 | + <programlisting xlink:href="listings/listing-1.txt"/> |
| 79 | + <para>Containers build from this image run a periodical health-check to make sure that eXist-db is operating normally. If <code>docker ps</code> reports unhealthy you can get a more detailed report with this command:</para> |
| 80 | + <para><code>docker inspect --format='{{json .State.Health}}' exist</code></para> |
| 81 | + <para>To check exist's logs: <code>docker logs exist</code></para> |
| 82 | + </sect1> |
| 83 | + <sect1 xml:id="base-image"> |
| 84 | + <title>Use as Base Image</title> |
| 85 | + <para>A common usage of these images is as a base image for your own applications. We'll take a quick look at three scenarios of increasing complexity, to demonstrate how to achieve common tasks from inside <literal>Dockerfile</literal>.</para> |
| 86 | + <sect2 xml:id="base-simple"> |
| 87 | + <title>A simple base image</title> |
| 88 | + <para>The simplest case assumes that you have a <code>.xar</code> app inside a build folder on the same level as your own <literal>Dockerfile</literal>. To get an image of an eXist-db instance with your app installed and running, you would then:</para> |
| 89 | + <programlisting xlink:href="listings/listing-2.txt"/> |
| 90 | + <para>You should see something like this:</para> |
| 91 | + <programlisting xlink:href="listings/listing-3.txt"/> |
| 92 | + <para>The result is a new image of your app installed into eXist-db. Since you didn't provide further instructions it will simply reuse the <code>EXPOSE, CMD, HEALTHCHECK,</code> etc instructions defined by the base image. You can now publish this image to a docker registry and share it with others.</para> |
| 93 | + </sect2> |
| 94 | + </sect1> |
| 95 | + |
| 96 | + </article> |
0 commit comments