Deploying with Docker

Minimal Secure Setup#

To run EventSourcingDB securely in production, you need:

• A strong API token (minimum 32 characters, mixed-case letters and digits)
• An HTTPS certificate and private key
• A persistent data volume

Use this docker run command as your base:

docker run \
  --init \
  --restart always \
  -p <PORT>:4000 \
  -v <HOST_DATA>:/var/lib/esdb \
  -v <HOST_CONFIG>:/etc/esdb \
  thenativeweb/eventsourcingdb:<VERSION> run \
  --api-token=<API_TOKEN> \
  --data-directory=/var/lib/esdb \
  --https-certificate-file=/etc/esdb/cert.pem \
  --https-private-key-file=/etc/esdb/key.pem

Replace:

• <PORT> with the host port to expose EventSourcingDB (e.g., 4000)
• <VERSION> with the specific version you want to run (e.g., 1.3.0)
• <API_TOKEN> with a secure string
• <HOST_DATA> with the path on your host for persistent storage (e.g., /host/data)
• <HOST_CONFIG> with the path containing your TLS certificate, private key, and (optionally) the license file (e.g., /host/config)

Changed in 1.3The image runs EventSourcingDB as the user nonroot, with the UID and the GID 65532. So <HOST_DATA> has to belong to this user, and the files in <HOST_CONFIG> have to be readable by it. Up to version 1.2, the image ran it as esdb, with the UID 100 and the GID 101, so a data directory that such a version wrote has to be given to the new user first, as described in Upgrading a Docker Deployment From 1.2 or Earlier.

The image creates /var/lib/esdb with 0750, so that only this user and its group can enter it, and so does a volume that Docker creates for it, while a directory of the host that you mount there keeps its own permissions. Within it, EventSourcingDB keeps other users out of its files, as described in Permissions of the Data Directory.

Adding a Commercial License#

If you're using a commercial license, place the license file (e.g., license.lic) in the already mounted directory (e.g. <HOST_CONFIG>). Additionally, provide the --license-file flag:

docker run \
  [...] \
  thenativeweb/eventsourcingdb:<VERSION> run \
  [...] \
  --license-file=/etc/esdb/license.lic

Alternatively, you can provide the license as an inline string using the --license-string flag. In this case, there is no need to store the license as a file:

docker run \
  [...] \
  thenativeweb/eventsourcingdb:<VERSION> run \
  [...] \
  --license-string=<LICENSE_STRING>

Enabling Event Signing (Optional)Added in 1.1#

To enable cryptographic signatures for events, provide the --signing-key-file flag and point it to a valid Ed25519 private key in PKCS#8 PEM format:

docker run \
  [...] \
  thenativeweb/eventsourcingdb:<VERSION> run \
  [...] \
  --signing-key-file=/etc/esdb/signing-key.pem

If no key is provided, the signature field of returned events will be null.

Enabling the Management UI (Optional)#

The management UI provides a visual dashboard but may be unnecessary if you're already using observability tools like Prometheus.

To enable it:

docker run \
  [...] \
  thenativeweb/eventsourcingdb:<VERSION> run \
  [...] \
  --with-ui

Use it if no external monitoring is available, or when you want a quick overview of system status.

Production Checklist#

For secure and stable operation of EventSourcingDB with Docker:

• Always mount a persistent volume at /var/lib/esdb and point the server at it with --data-directory=/var/lib/esdb; mounting the volume alone is not enough, as the server does not start without a data directory

• Mount your config directory to /etc/esdb, containing both TLS certificates and (optionally) the license file

• Use HTTPS with your own certificates

• Disable HTTP (or at least don't enable it)

• Pin the Docker image version

• Add --restart always and --init for production-grade behavior

• Changed in 1.3Give EventSourcingDB time to shut down gracefully, for example with --stop-timeout 60: docker stop sends SIGTERM, on which EventSourcingDB shuts down gracefully, but kills the container after 10 seconds by default, so that the next start has to replay what EventSourcingDB had not yet written to its data files

• Changed in 1.1Use optional flags like --signing-key-file, --with-ui, --license-file or --license-string as needed

This setup keeps your instance secure, observable, and predictable – with all changes under your control.