Difference between revisions of "Docker"
(Adding documentation on Docker usage.) |
(latest instead of nightly.) |
||
Line 11: | Line 11: | ||
--publish 8984:8984 \ | --publish 8984:8984 \ | ||
--volume ~/BaseXData:/srv/BaseXData \ | --volume ~/BaseXData:/srv/BaseXData \ | ||
− | basex/basexhttp: | + | basex/basexhttp:latest</pre> |
− | </pre> | ||
By passing any other BaseX executable, you can also for example run a BaseX client connecting to the linked BaseX server for management operations on the BaseX command line: | By passing any other BaseX executable, you can also for example run a BaseX client connecting to the linked BaseX server for management operations on the BaseX command line: | ||
Line 19: | Line 18: | ||
docker run -ti \ | docker run -ti \ | ||
--link basexhttp:basexhttp \ | --link basexhttp:basexhttp \ | ||
− | basex/basexhttp: | + | basex/basexhttp:latest basexclient -nbasexhttp |
</pre> | </pre> | ||
Line 74: | Line 73: | ||
<pre> | <pre> | ||
− | FROM basex/basexhttp: | + | FROM basex/basexhttp:latest |
MAINTAINER BaseX Team <basex-talk@mailman.uni-konstanz.de> | MAINTAINER BaseX Team <basex-talk@mailman.uni-konstanz.de> | ||
COPY . /srv/BaseXWeb | COPY . /srv/BaseXWeb | ||
</pre> | </pre> | ||
− | For general production usage, you should choose a fixed version instead of {{Code| | + | For general production usage, you should choose a fixed version instead of the development branch behind {{Code|latest}}, so your application does not suddenly break because of unnoticed API changes. The most relevant part happens in the {{Code|COPY}} statement, which adds the file's contents to the {{Code|BaseXWeb}} directory. That's already it -- you're ready to run. |
==Advanced Usage== | ==Advanced Usage== |
Revision as of 22:50, 19 February 2016
The BaseX server is also available as automated build basex/basexhttp
on the Docker Hub, providing both release and nightly builds. All images are automatically rebuild if Docker provides updated base images.
Contents
Running a BaseX Container
To start a BaseX container based on the latest development release publishing the BaseX server and HTTP ports 1984 and 8984 and bind-mounting your user's BaseXData
directory, run
docker run -ti \ --name basexhttp \ --publish 1984:1984 \ --publish 8984:8984 \ --volume ~/BaseXData:/srv/BaseXData \ basex/basexhttp:latest
By passing any other BaseX executable, you can also for example run a BaseX client connecting to the linked BaseX server for management operations on the BaseX command line:
docker run -ti \ --link basexhttp:basexhttp \ basex/basexhttp:latest basexclient -nbasexhttp
BaseX is run under the basex
user with fixed user ID 1984. The user's home directory is /srv
. Several ports are exposed:
Port | Description |
1984 | Server port |
8984 | HTTP port |
8985 | HTTP stop port |
Leaving BaseX' defaults but --publish
ing them under another external port is recommended if you want to change the ports.
Administration with DBA
If you prefer the DBA web interface, this can also be linked against your server container:
docker run -d \ --name basex-dba \ --publix 18984:8984 \ --link basexhttp:basexhttp \ basex/dba
The DBA is now available as http://localhost:8984/dba (adjust host name and port as needed). When logging in, connect to the linked container basexhttp
by entering basexhttp:1984
into the Address field.
Security Considerations
The Docker image ships the unchanged default credentials. Especially if you publish the server port 1984 or link a public DBA instance against the container, make sure to change the default credentials by adding a custom .basex
file.
When publishing ports, consider which interfaces to bind to, paying special attention to the server port 1984 and a possibly linked DBA web interface.
A common use case will be linking a well-researched and mature reverse proxy link nginx against the application container. Goals are to reduce exposure of BaseX and Jetty, adding TLS-encryption, serve static resources like images and perform URL rewrites as needed. For database administration and ad-hoc queries, an instance of the DBA will be linked with restricted access. Port `1984` is not published, but only linked to the DBA; the same applies to the HTTP port 8984 if you use a reverse proxy. If you need to access the command line, you can always docker exec
into the container and run basexclient
.
Running your own Application in a Docker Image
If you want to add your own application, create an image FROM basex/basexhttp:[tag]
with [tag]
being the BaseX version you're developing against. Usually, you will add your application code to /srv/BaseXWeb
and modules to /srv/BaseXModule
. BaseXData
is persisted as a volume, which means it cannot be preinitialized in the application image.
Example: DBA
An example for creating your own Docker image based on basex/basexhttp
is the DBA application. A Dockerfile
was added to the source code's root directory. The very simple file contains only few statements:
FROM basex/basexhttp:latest MAINTAINER BaseX Team <basex-talk@mailman.uni-konstanz.de> COPY . /srv/BaseXWeb
For general production usage, you should choose a fixed version instead of the development branch behind latest
, so your application does not suddenly break because of unnoticed API changes. The most relevant part happens in the COPY
statement, which adds the file's contents to the BaseXWeb
directory. That's already it -- you're ready to run.
Advanced Usage
BaseX Configuration
If you need to adjust BaseX' configuration to tune the [Option option] defaults, add a .basex
file to /srv
:
COPY .basex /srv
Option not defined in the .basex
file with be automatically set to BaseX' default values.
Jetty Configuration
If you need to change the embedded web server's configuration, you can always COPY
a WEB-INF
folder containing the required files and overwrite the predefined configuration.
Java Runtime Parameters
Larger applications and databases might require adjusted JRE parameters like increasing the memory limit. You can change those by setting the BASEX_JVM
environment variable:
ENV BASEX_JVM="-Xmx2048m"
Installing Debian Packages
The basex/basexhttp
Docker image is build own the official Maven Docker image, which again derives from Debian. You can add arbitrary Debian packages. Make sure to switch to the root
user's context before installing packages and back to the basex
user afterwards. As common in the Docker environment, you need to fetch the package catalog using apt-get update
before installing packages and should clean up afterwards to keep the image small. This example installs some libraries required for image manipulation and adds them to the $CLASSPATH
:
USER root RUN apt-get update && \ DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -y libbatik-java libxmlgraphics-commons-java libcommons-codec-java && \ apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* USER basex ENV CLASSPATH="/usr/share/java/xml-commons-external.jar:/usr/share/java/xmlgraphics-commons.jar:/usr/share/java/batik.jar:usr/share/java/commons-codec.jar" \