Environment Variables

Below are all the environment variables supported by Pocket ID. These should be configured in your .env file.

Be cautious when modifying environment variables that are not recommended to change.

Database connection string

The DB_CONNECTION_STRING environmental variable configures how Pocket ID connects to the database.

Pocket ID supports two database providers: SQLite and PostgreSQL. The database provider is automatically inferred from the connection string. By default, Pocket ID uses SQLite with a database file located at data/pocket-id.db.

SQLite

When using SQLite, the connection string is the path to the SQLite database file. Pocket ID automatically adds some parameters to the database path, turning it into a connection string like file:data/pocket-id.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(2500)&_txlock=immediate&_pragma=foreign_keys(1) - you can pass a full connection string if you need to customize the parameters.

[!CAUTION] We do NOT recommend storing the SQLite database inside a networked filesystem, such as a NFS or SMB share. However, if you absolutely must, and are aware of the risks, you need to modify DB_CONNECTION_STRING and disable journaling, by setting _journal_mode=DELETE. Note that this is not a recommended or supported scenario by the SQLite developers, and you should ensure to have proper backups for your database.

PostgreSQL

When using PostgreSQL, the connection string is a DSN as supported by libpq:

Encryption keys

An encryption key of at least 16 bytes is needed to encrypt sensitive data, such as the token signing keys.

A good encryption key is a 32-characters-long random string. You can generate one using tools like OpenSSL:

You can pass the encryption key to Pocket ID in two ways:

1. Set its value in the ENCRYPTION_KEY variable directly
2. Save it to a file mounted inside the container and set ENCRYPTION_KEY_FILE to its path (the file is treated as binary, so any CR/LF line terminator will be treated as part of the key). This also works with Docker Secrets.

Updating the encryption key

To update the encryption key you can use the CLI command encryption-key-rotate:

After running the command, all existing encrypted data will be re-encrypted with the new key. You need to update your environment variable with the new key and restart Pocket ID.

[!CAUTION] If you are using a file mounted inside the container pointed to by the ENCRYPTION_KEY_FILE environment variable, ensure no CR/LF line terminator is appended to the key in the file, as otherwise the key will not match the one passed to ./pocket-id encryption-key-rotate and decryption will fail.

Reverse proxy settings

When running Pocket ID behind a reverse proxy (such as Nginx, Caddy, Traefik, or a cloud load balancer), you need to configure how the application determines the client's real IP address. This is important for security features like rate limiting and audit logging.

Pocket ID uses the Gin web framework, which provides two mechanisms for obtaining the client's real IP:

TRUST_PROXY

When TRUST_PROXY is set to true, it calls gin.Engine.SetTrustedProxies(nil) to clear the list of trusted proxy CIDRs. This effectively tells Gin to trust all proxies and extract the client IP from headers like X-Forwarded-For or X-Real-IP.

• Default: false
• When to use: Set to true when Pocket ID is running behind a reverse proxy that sets standard forwarding headers.

TRUSTED_PLATFORM

When TRUSTED_PLATFORM is set to a non-empty value, it configures gin.Engine.TrustedPlatform. This tells Gin to directly read the client's real IP from a specific HTTP request header set by a trusted platform or CDN, bypassing the X-Forwarded-For parsing logic.

• Default: Not set
• Supported values:
  • X-Appengine-Remote-Addr - For Google App Engine
  • CF-Connecting-IP - For Cloudflare
  • Fly-Client-IP - For Fly.io
  • Any custom header name that your reverse proxy uses to pass the client's real IP

[!TIP] If you're using a CDN or platform that sets a specific header for the client IP, prefer using TRUSTED_PLATFORM over TRUST_PROXY as it provides a more direct and reliable way to obtain the client's real IP address.

Overriding the UI configuration

You can change additional settings directly in the Pocket ID UI. However, if you prefer to configure them via environment variables, you can do so by setting the following variables.

To enable environment variable overrides, set UI_CONFIG_DISABLED to true. When UI_CONFIG_DISABLED is set to true, Pocket ID will use values from the environment variables. If a variable is not set, the system will fall back to its default values.

Observability

Pocket ID offers multiple options for observability, including logs, metrics, and traces.

You can configure Pocket ID to emit metrics and traces.

• Both can be sent to an OpenTelemetry collector.
• For metrics, you can also configure Pocket ID to expose them on a Prometheus-compatible endpoint.

Using OpenTelemetry for logs, metrics, and traces

The behavior of the log, trace, and metric exporters can be controlled using the OTEL_* environment variables. These are documented in the OpenTelemetry SDK environment variables documentation.

Using Prometheus for metrics

If you want to enable the /metrics endpoint for Prometheus metrics scraping instead of using OTLP metrics pushing, you'll need to also set:

This will start a second HTTP server with just the metrics endpoint. It is by default bound to:

• OTEL_EXPORTER_PROMETHEUS_HOST: localhost
• OTEL_EXPORTER_PROMETHEUS_PORT: 9464