Deploying the Pre-Built Binary

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 directory

Use the following command as a starting point:

./eventsourcingdb run \
  --api-token=<API_TOKEN> \
  --https-certificate-file=<CONFIG_DIR>/cert.pem \
  --https-private-key-file=<CONFIG_DIR>/key.pem \
  --data-directory=<DATA_DIR>

Replace:

• <API_TOKEN> with a secure string
• <CONFIG_DIR> with the directory containing your TLS certificate and private key (e.g., /etc/esdb)
• <DATA_DIR> with the path to your persistent data directory (e.g., /var/lib/esdb)

Permissions of the Data DirectoryAdded in 1.3#

EventSourcingDB creates its files in the data directory with 0640 and its directories with 0750, so that only the user it runs as and its group can read them, for example a tool in that group that backs up the files. At its first start on a data directory, it takes every permission of other users away from all of its files and directories, whichever version created them, and gives each at least 0640 or 0750, which lets the group read files that only their user could read before. What the group may do beyond that, such as writing, as the fsGroup of a Kubernetes Pod allows it, stays as it is. Once it has changed all of them, it records this in the file permissions.esdp in the data directory, and later starts leave the permissions as they are, since going over every file at every start would take the longer the more events the data directory holds. If you copy the data directory with a tool that does not keep permissions, remove permissions.esdp from the copy before you start EventSourcingDB on it, so that it restricts them again.

A stricter umask therefore holds for the files and directories that EventSourcingDB creates from then on, but not for the files that it writes through a temporary file, as it writes most of them, which get 0640 whatever the umask. EventSourcingDB leaves the data directory itself, and anything else that is put into it, as they are, so its permissions are yours to choose.

Where EventSourcingDB cannot change the permissions, for example of files that belong to another user, it goes on working with them as before, and logs a warning as it starts, could not restrict the permissions of entries of the data directory, so other users of the machine may read them, with their number, the first of them, and its error. It tries again at every start, until it has changed all of them. Where it cannot record this, it logs the warning could not record that the permissions of the data directory are restricted, so the next start restricts them again, with its error, and starts all the same. On Windows, where a mode only sets the read-only attribute, EventSourcingDB changes no permissions and leaves them to the ACL of the data directory.

Changing the Port#

By default, EventSourcingDB uses port 4000 for HTTPS. To use a different port, provide the --https-port flag:

./eventsourcingdb run [...] --https-port=443

Adding a Commercial License#

If you're using a commercial license, place the license file (e.g., license.lic) in <CONFIG_DIR>, or another suitable location, and provide the --license-file flag:

./eventsourcingdb 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:

./eventsourcingdb 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:

./eventsourcingdb 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:

./eventsourcingdb 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:

• Use HTTPS with your own certificates

• Store the data in a persistent, monitored directory

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

• Use --https-port to match your infrastructure, if needed

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