This page is part of the Developer Section.
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
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
BaseX is run under the
basex user with fixed user ID 1984. The user’s home directory is
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
chown -R 1984 ~/my-project/data
Several ports are exposed:
|1984||Port of database server (see |
|8984||Port of HTTP server (see Web Application|
|8985||Stop port of HTTP server (see |
Leaving BaseX defaults but
--publishing them under another external port is recommended if you want to change the ports.
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
Running your own Application
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
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 <email@example.com> 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.
If you need to adjust the BaseX configuration to tune the default options, add a
.basex file to
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.
If you need to change the embedded web server configuration, you can always
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:
Installing Additional Packages
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