Skip to content

Deploying with Docker

This guide shows how to run EventSourcingDB in a production-grade setup using Docker. It covers a minimal secure baseline and explains how to incrementally add features like licensing and the management UI.

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> \
  --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.2.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)

No HTTP in Production

In production, do not enable HTTP. HTTPS is enabled by default, so --http-enabled=false is not required – but specifying it explicitly is recommended for clarity.

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)

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
  • 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
  • Use 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.