Docker

This article shows how to run BaseX in a Docker container. Official images are published for every release in the GitHub Container Registry:

ghcr.io/basexdb/basex

The images contain a Java runtime and a full BaseX installation, and they start the HTTP Server. They are provided for linux/amd64 and linux/arm64, and rebuilt weekly, so that they also receive security updates of the underlying Java base image.

Quick Start

docker run -d --name basex \
  -p 8080:8080 \
  -e BASEX_ADMIN_PASSWORD=change-me \
  -v basex-data:/opt/basex/data \
  ghcr.io/basexdb/basex

The DBA, REST and RESTXQ interfaces will now be available at http://localhost:8080.

Image Tags

Tag	Description
latest	Newest BaseX release.
13	Newest release of a major version.
13.0	A specific release. Recommended for reproducible deployments.

Ports

Port	Service
8080	HTTP server: REST, RESTXQ and the DBA web interface.
8081	Stop port (used internally to shut down the HTTP server).
1984	Database server (client/server protocol, Clients). It is closed by default; see Configuration.

Admin Password

BaseX ships with a single admin user. If a password is supplied via the BASEX_ADMIN_PASSWORD environment variable, it will be assigned on the first start of the container. The variable is ignored later on; afterwards, credentials are managed with the User Management commands or the DBA.

If the variable is unset, a random initial password will be generated and written to the log. The image routes the log to standard output, so the password shows up in the container log:

docker logs basex

Initial admin password (change after first login): ...

Persisting Data

BaseX stores its databases and the user registry below the data directory (/opt/basex/data in the image), which is declared as a volume. Mount a named volume or a host directory to this path to keep your data across container updates:

docker run -v basex-data:/opt/basex/data ... ghcr.io/basexdb/basex

Installed XQuery Modules and a custom webapp directory can be persisted the same way by mounting /opt/basex/repo and /opt/basex/webapp.

Configuration

JVM options, such as the maximum heap size, and system properties are supplied through the BASEX_JVM environment variable:

docker run -e BASEX_JVM="-Xmx2g -Dorg.basex.STRIPWS=true" ... ghcr.io/basexdb/basex

All Command-Line Options of the HTTP server can be appended to the container command. For example, the HTTP server is bound to a different port as follows:

docker run -p 9090:9090 ... ghcr.io/basexdb/basex basexhttp -h9090

The HTTP server runs in local mode by default, and port 1984 stays closed. To make the databases accessible to the client APIs, start basexhttp with -L and publish the port:

docker run -p 8080:8080 -p 1984:1984 ... ghcr.io/basexdb/basex basexhttp -L

Static configuration can also be provided by mounting a .basex file or a custom web.xml/jetty.xml.

Docker Compose

For a reproducible local setup, the same image can be described with Docker Compose:

services:
  basex:
    image: ghcr.io/basexdb/basex:13.0
    ports:
      - "8080:8080"   # HTTP: REST, RESTXQ, DBA
    environment:
      BASEX_ADMIN_PASSWORD: "change-me"
    volumes:
      - basex-data:/opt/basex/data
    restart: unless-stopped

volumes:
  basex-data:

Start it with docker compose up -d.

Advanced Usage

Web Applications

The image doubles as a base image for your own Web Applications. Add your RESTXQ modules, static files and permissions on top:

FROM ghcr.io/basexdb/basex:13.0
COPY --chown=basex:basex webapp/ /opt/basex/webapp/

Building Your Own Image

The recipe of the official image is part of the BaseX repository: docker/Dockerfile and docker/docker-entrypoint.sh. Use it as a starting point if you want full control over the image:

git clone https://github.com/BaseXdb/basex.git
docker build -t basex --build-arg BASEX_VERSION=13.0 basex/docker

Some notes on the design of this file:

• It is a multi-stage build: The first stage downloads and unpacks an official release, the second one assembles a minimal runtime image.
• The BaseX version is passed as a build argument (BASEX_VERSION). The download URL is derived from the version number (13.0 → BaseX130.zip).
• Eclipse Temurin is used as a free, multi-platform Java runtime. Any distribution with Java 21 or later will do.
• The container runs as a non-privileged basex user.
• The HEALTHCHECK requests the start page, which is served without authentication. After three consecutive failures, the container is marked as unhealthy.
• The entrypoint sets the admin password on the very first start and routes the log to standard output. To write the log to files below the data/.logs directory instead, override the LOG option through BASEX_JVM.

Images for multiple architectures are built at once with buildx:

docker buildx build --platform linux/amd64,linux/arm64 -t basex basex/docker

Community Images

The community project Quodatum/basex-docker provides alternative images and demonstrates a GitHub Actions workflow for automated builds.

Questions, improvements and further Docker recipes are always welcome on our mailing list.