Difference between revisions of "Docker"

From BaseX Documentation
Jump to navigation Jump to search
(Information on changing credentials.)
 
(24 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
This page is part of the [[Developer Section]].
 
This page is part of the [[Developer Section]].
  
The BaseX server is also available as automated build [https://hub.docker.com/r/basex/basexhttp/ {{Code|basex/basexhttp}}] on the Docker Hub, providing both release and nightly builds. All images are automatically rebuilt if Docker provides updated base images.
+
The BaseX server is available as automated build [https://hub.docker.com/r/basex/basexhttp/ basex/basexhttp] on the Docker Hub, providing both release and nightly builds. All images are automatically rebuilt if Docker provides updated base images.
  
 
=Running a BaseX Container=
 
=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 {{Code|BaseXData}} directory, run
+
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 {{Code|data}} directory, run
  
<pre brush="bash">
+
<syntaxhighlight lang="bash">
 
docker run -ti \
 
docker run -ti \
 
     --name basexhttp \
 
     --name basexhttp \
 
     --publish 1984:1984 \
 
     --publish 1984:1984 \
 
     --publish 8984:8984 \
 
     --publish 8984:8984 \
     --volume ~/BaseXData:/srv/BaseXData \
+
     --volume "$(pwd)/basex/data":/srv/basex/data \
     basex/basexhttp:latest</pre>
+
     basex/basexhttp:latest
 +
</syntaxhighlight>
  
 
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:
  
<pre brush="bash">
+
<syntaxhighlight lang="bash">
 
docker run -ti \
 
docker run -ti \
 
     --link basexhttp:basexhttp \
 
     --link basexhttp:basexhttp \
 
     basex/basexhttp:latest basexclient -nbasexhttp
 
     basex/basexhttp:latest basexclient -nbasexhttp
</pre>
+
</syntaxhighlight>
  
BaseX is run under the {{Code|basex}} user with fixed user ID 1984. The user's home directory is {{Code|/srv}}. Several ports are exposed:
+
== Non-privileged User ==
 +
 
 +
BaseX is run under the {{Code|basex}} user with fixed user ID 1984. The user’s home directory is {{Code|/srv}}.  
 +
 
 +
'''Please note''' that, when mounting a data volume from your host operating system, it keep its ownership flags even inside the container.
 +
 
 +
If you encounter errors such as: <code> Resource "/srv/basex/data/mydb/tbl.basex (Permission denied)"</code> make sure to change ownership of your <code>data</code>-Folder
 +
to <code>UID 1984</code>:
 +
 
 +
<syntaxhighlight>
 +
chown -R 1984 ~/my-project/data
 +
</syntaxhighlight>
 +
 
 +
== Networking  ==
 +
 
 +
Several ports are exposed:
  
 
{| class="wikitable"  
 
{| class="wikitable"  
Line 31: Line 47:
 
|-
 
|-
 
| '''1984'''
 
| '''1984'''
| [[Options#SERVERPORT|Server port]]
+
| Port of database server (see {{Option|SERVERPORT}})
 
|-
 
|-
 
| '''8984'''
 
| '''8984'''
| [[Startup#HTTP_Server|HTTP port]]
+
| Port of HTTP server (see [[Web Application]]
 
|-
 
|-
 
| '''8985'''
 
| '''8985'''
| [[Options#STOPPORT|HTTP stop port]]
+
| Stop port of HTTP server (see {{Option|STOPPORT}})
 
|-
 
|-
 
|}
 
|}
  
Leaving BaseX' defaults but {{Code|--publish}}ing them under another external port is recommended if you want to change the ports.
+
Leaving BaseX defaults but {{Code|--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:
 
 
 
<pre brush="bash">
 
docker run -d \
 
    --name basex-dba \
 
    --publix 18984:8984 \
 
    --link basexhttp:basexhttp \
 
    basex/dba
 
</pre>
 
 
 
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 {{Code|basexhttp}} by entering {{Code|basexhttp:1984}} into the ''Address'' field.
 
  
 
=Security Considerations=
 
=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 (see [[BaseX Configuration|Docker#BaseX Configuration]] section for details).
+
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. When publishing ports, consider which interfaces to bind to, paying special attention to the server port.
  
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. If you need to access the command line, you can always {{Code|docker exec}} into the container and run {{Code|basexclient}}.
  
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 {{Code|docker exec}} into the container and run {{Code|basexclient}}.
+
=Running your own Application=
  
=Running your own Application in a Docker Image=
+
If you want to add your own application in a Docker image, create an image {{Code|FROM basex/basexhttp:[tag]}} with {{Code|[tag]}} being the BaseX version you’re developing against.
 
+
Unless configured otherwise, you will add your application code to {{Code|/srv/basex/webapp}} and modules to {{Code|/srv/basex/repo}}.
If you want to add your own application, create an image {{Code|FROM basex/basexhttp:[tag]}} with {{Code|[tag]}} being the BaseX version you're developing against. Usually, you will add your application code to {{Code|/srv/BaseXWeb}} and modules to {{Code|/srv/BaseXModule}}. {{Code|BaseXData}} is persisted as a volume, which means it cannot be preinitialized in the application image.
 
  
 
==Example: DBA==
 
==Example: DBA==
  
An example for creating your own Docker image based on {{Code|basex/basexhttp}} is the [https://github.com/BaseXdb/basex/tree/master/basex-api/src/main/webapp/dba DBA application]. A {{Code|Dockerfile}} was added to the source code's root directory. The very simple file contains only few statements:
+
An example for creating your own Docker image based on {{Code|basex/basexhttp}} is the [https://github.com/BaseXdb/basex/tree/master/basex-api/src/main/webapp/dba DBA application]. A {{Code|Dockerfile}} was added to the source code’s root directory. The very simple file contains only few statements:
  
<pre>
+
<syntaxhighlight>
 
FROM basex/basexhttp:latest
 
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/basex/webapp
</pre>
+
</syntaxhighlight>
  
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.
+
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 contents to the {{Code|webapp}} directory. That’s already it -- you’re ready to run.
  
 
==Advanced Usage==
 
==Advanced Usage==
Line 85: Line 86:
 
===BaseX Configuration===
 
===BaseX Configuration===
  
If you need to adjust BaseX' configuration to tune the default [[Options|options]], add a {{Code|.basex}} file to {{Code|/srv}}:
+
If you need to adjust the BaseX configuration to tune the default [[Options|options]], add a {{Code|.basex}} file to {{Code|/srv}}:
  
<pre>
+
<syntaxhighlight>
COPY .basex /srv
+
COPY .basex /srv/basex
</pre>
+
</syntaxhighlight>
  
Options not defined in the {{Code|.basex}} file with be automatically set to BaseX' default values. Users and passwords can be defined by adding a {{Code|users.xml}} file, which is described on the [[User Management]] page.
+
Options not defined in the {{Code|.basex}} file with be automatically set to the default values. Users and passwords can be defined by adding a {{Code|users.xml}} file, which is described on the [[User Management]] page.
  
 
===Jetty Configuration===
 
===Jetty Configuration===
  
If you need to change the embedded web server's configuration, you can always {{Code|COPY}} a {{Code|WEB-INF}} folder containing the required files and overwrite the predefined configuration.
+
If you need to change the embedded web server configuration, you can always {{Code|COPY}} a {{Code|WEB-INF}} folder containing the required files and overwrite the predefined configuration.
  
 
===Java Runtime Parameters===
 
===Java Runtime Parameters===
Line 101: Line 102:
 
Larger applications and databases might require adjusted JRE parameters like increasing the memory limit. You can change those by setting the {{Code|BASEX_JVM}} environment variable:
 
Larger applications and databases might require adjusted JRE parameters like increasing the memory limit. You can change those by setting the {{Code|BASEX_JVM}} environment variable:
  
<pre>
+
<syntaxhighlight>
 
ENV BASEX_JVM="-Xmx2048m"
 
ENV BASEX_JVM="-Xmx2048m"
</pre>
+
</syntaxhighlight>
  
===Installing Debian Packages===
+
===Installing Additional Packages===
  
The {{Code|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 {{Code|root}} user's context before installing packages and back to the {{Code|basex}} user afterwards. As common in the Docker environment, you need to fetch the package catalog using {{Code|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 {{Code|$CLASSPATH}}:
+
The {{Code|basex/basexhttp}} Docker image is build on the official Maven Docker image {{Code|maven:3-jdk-8-alpine}}, which in turn derives from [https://alpinelinux.org alpine linux].
 +
In [https://alpinelinux.org alpine linux] you can add arbitrary software packages via APK. Make sure to switch to the {{Code|root}} user context before installing packages and back to the {{Code|basex}} user afterwards. As common in the Docker environment, you need to fetch the package catalog–in  [https://alpinelinux.org alpine linux] this is done using {{Code|apk update}}–before installing packages and disable caching to keep the image small. The example installs {{Code|git}} as additional linux package:
  
<pre>
+
<syntaxhighlight>
 
USER root
 
USER root
 
+
RUN apk update && apk add --no-cache git
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
 
USER basex
 
+
</syntaxhighlight>
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" \
 
</pre>
 

Latest revision as of 15:34, 27 February 2020

This page is part of the Developer Section.

The BaseX server is available as automated build basex/basexhttp on the Docker Hub, providing both release and nightly builds. All images are automatically rebuilt if Docker provides updated base images.

Running a BaseX Container[edit]

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 data directory, run

docker run -ti \
    --name basexhttp \
    --publish 1984:1984 \
    --publish 8984:8984 \
    --volume "$(pwd)/basex/data":/srv/basex/data \
    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

Non-privileged User[edit]

BaseX is run under the basex user with fixed user ID 1984. The user’s home directory is /srv.

Please note that, when mounting a data volume from your host operating system, it keep its ownership flags even inside the container.

If you encounter errors such as: Resource "/srv/basex/data/mydb/tbl.basex (Permission denied)" make sure to change ownership of your data-Folder to UID 1984:

chown -R 1984 ~/my-project/data

Networking[edit]

Several ports are exposed:

Port Description
1984 Port of database server (see SERVERPORT)
8984 Port of HTTP server (see Web Application
8985 Stop port of HTTP server (see STOPPORT)

Leaving BaseX defaults but --publishing them under another external port is recommended if you want to change the ports.

Security Considerations[edit]

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. When publishing ports, consider which interfaces to bind to, paying special attention to the server port.

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. If you need to access the command line, you can always docker exec into the container and run basexclient.

Running your own Application[edit]

If you want to add your own application in a Docker image, create an image FROM basex/basexhttp:[tag] with [tag] being the BaseX version you’re developing against. Unless configured otherwise, you will add your application code to /srv/basex/webapp and modules to /srv/basex/repo.

Example: DBA[edit]

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/basex/webapp

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 contents to the webapp directory. That’s already it -- you’re ready to run.

Advanced Usage[edit]

BaseX Configuration[edit]

If you need to adjust the BaseX configuration to tune the default options, add a .basex file to /srv:

COPY .basex /srv/basex

Options not defined in the .basex file with be automatically set to the default values. Users and passwords can be defined by adding a users.xml file, which is described on the User Management page.

Jetty Configuration[edit]

If you need to change the embedded web server configuration, you can always COPY a WEB-INF folder containing the required files and overwrite the predefined configuration.

Java Runtime Parameters[edit]

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 Additional Packages[edit]

The basex/basexhttp Docker image is build on the official Maven Docker image maven:3-jdk-8-alpine, which in turn derives from alpine linux. In alpine linux you can add arbitrary software packages via APK. Make sure to switch to the root user context before installing packages and back to the basex user afterwards. As common in the Docker environment, you need to fetch the package catalog–in alpine linux this is done using apk update–before installing packages and disable caching to keep the image small. The example installs git as additional linux package:

USER root
RUN apk update && apk add --no-cache git
USER basex