# 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**:

```shell
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:

```shell
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**:

```shell
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:

```yaml
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:

```shell
./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:

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

In Kubernetes:

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

Then inject it and reference it in `args`:

```yaml
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:

```shell
--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:

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

Mount the secret into the container:

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

Then pass the paths explicitly:

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

If you're using **[cert-manager](https://cert-manager.io/)**, 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.