Skip to content

Managing Configuration and Secrets

This guide explains how to manage configuration and secrets when running EventSourcingDB in production. It covers best practices for handling API tokens, licenses, TLS certificates, and runtime arguments across different deployment environments.

Configuration Strategy

EventSourcingDB follows a strict flag-based configuration model. Before diving into specific settings, it's important to understand the general approach.

EventSourcingDB does not support configuration via environment variables. All settings must be passed as command-line flags. If you want to use environment variables (e.g., for secrets), inject them into the container and reference them explicitly in the args section.

This approach ensures clarity and consistency across deployment environments.

API Token Management

EventSourcingDB requires a valid API token for any access, including both read and write operations. While there are no formal constraints on its structure, we recommend:

  • A length of at least 32 characters
  • A mix of uppercase and lowercase letters, and digits

Best Practices

  • Do not hardcode the token in source code or container images
  • Avoid using guessable strings like secret or admin123
  • Pass the token explicitly using the --api-token flag

Docker

You must provide the token via the --api-token flag:

docker run [...] --api-token=<API_TOKEN>

If you're using environment variables in your shell (e.g., via an .env file), you can reference them directly in the command:

docker run [...] --api-token="$API_TOKEN"

No wrapper script is required – standard shell expansion is sufficient.

Kubernetes

To manage the token securely, create a Kubernetes secret:

kubectl create secret generic esdb-secrets \
  --from-literal=api-token=<API_TOKEN>

Then inject it into the container using env and reference it in the args list:

env:
- name: API_TOKEN
  valueFrom:
    secretKeyRef:
      name: esdb-secrets
      key: api-token
args:
- "--api-token=$(API_TOKEN)"
- [...]

License Management

If you want to run EventSourcingDB with a commercial license, you can provide it either as a file or as an inline string.

File-Based License

This is a simple option for local or Docker-based setups:

./eventsourcingdb run --license-file=/etc/esdb/license.lic

Ensure the license file is stored securely and with restricted access (chmod 600).

Inline License String

Inline licenses are well suited for Kubernetes and CI/CD setups:

./eventsourcingdb run --license-string=<LICENSE_STRING>

In Kubernetes:

kubectl create secret generic esdb-secrets \
  --from-literal=license-string=<LICENSE_STRING>

Then inject it and reference it in args:

env:
- name: LICENSE_STRING
  valueFrom:
    secretKeyRef:
      name: esdb-secrets
      key: license-string
args:
- "--license-string=$(LICENSE_STRING)"
- [...]

TLS Certificate and Key

To run EventSourcingDB over HTTPS, you must provide:

  • A certificate file (commonly named cert.pem)
  • A private key file (commonly named key.pem)

Use the following flags:

--https-certificate-file=<PATH>
--https-private-key-file=<PATH>

Best Practices

  • Store TLS files in a secure, read-only location
  • Avoid bundling them into container images
  • Use restrictive permissions (e.g., chmod 600)
  • Rotate certificates before they expire

Kubernetes

We recommend using a Kubernetes tls secret:

kubectl create secret tls esdb-tls \
  --cert=cert.pem \
  --key=key.pem

Mount the secret into the container:

volumeMounts:
- name: tls
  mountPath: /etc/esdb
volumes:
- name: tls
  secret:
    secretName: esdb-tls

Then pass the paths explicitly:

args:
- "--https-certificate-file=/etc/esdb/tls.crt"
- "--https-private-key-file=/etc/esdb/tls.key"
- [...]

If you're using cert-manager, it can manage certificate issuance and rotation automatically. Integrating cert-manager is outside the scope of this documentation.

Best Practices

  • Use secrets and volumes to inject sensitive information securely
  • Do not hardcode tokens or license strings into manifests or scripts
  • Apply strict file permissions to all sensitive files
  • Rotate API tokens and certificates periodically
  • Keep runtime arguments transparent and version-controlled
  • Use consistent naming and mounting patterns across environments

Following these practices will help you manage configuration and secrets in a secure, maintainable, and portable way – whether you're running EventSourcingDB on bare metal, in Docker, or in Kubernetes.