Environment Variables | Pocket ID Docs

Environment Variables | Pocket ID Docs
Getting Started
Introduction
Setup
Installation
Upgrading
Migrate to v2.0
Data Export and Import
User Management
Configuration
Allowed User Groups
Analytics
App Dashboard
Environment Variables
LDAP Integration
SCIM Provisioning
Guides
OIDC Client Authentication
Proxy Services
Advanced
Callback URL Wildcards
Container Security Hardening
Custom Keys
Nginx Reverse Proxy
Troubleshooting
Account Recovery
Common Issues
Helping Out
Contributing
Documentation
Sponsors
Translating
Community
Demo
Discord
Environment Variables
Complete reference for all Pocket ID configuration options
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.
Variable
Default Value
Recommended to change
Description
APP_URL
yes
The URL where you will access the app.
ENCRYPTION_KEY
yes
Key used to encrypt data, including the private keys. It's recommended to use a random sequence of characters, for example generated with
openssl rand -base64 32
See the
Encryption keys
section below for more details.
ENCRYPTION_KEY_FILE
yes
Alternative to passing the encryption key with the
ENCRYPTION_KEY
variable, set to the path of a file containing a random encryption key.
This can be used with Docker secrets too.
TRUST_PROXY
false
yes
Whether the app is behind a reverse proxy.
See the
Reverse proxy settings
section below for more details.
TRUSTED_PLATFORM
yes
The trusted platform header for obtaining the client's real IP.
See the
Reverse proxy settings
section below for more details.
MAXMIND_LICENSE_KEY
yes
License Key for the GeoLite2 Database. The license key is required to retrieve the geographical location of IP addresses in the audit log. If the key is not provided, IP locations will be marked as "unknown." You can obtain a license key for free
here
MAXMIND_LICENSE_KEY_FILE
yes
Alternative to passing the License Key for GeoLite2 Database with the
MAXMIND_LICENSE_KEY
variable, set to the path of a file containing the key.
This can be used with Docker secrets too.
PUID
and
PGID
1000
yes
The user and group ID of the user who should run Pocket ID inside the Docker container and owns the files that are mounted with the volume. You can get the
PUID
and
GUID
of your user on your host machine by using the command
id
. For more information see
this article
DB_CONNECTION_STRING
data/pocket-id.db
no
Specifies the connection string used to connect to the database.
See the
Database connection string
section below for more details.
FILE_BACKEND
filesystem
no
The backend used for file storage. Valid values:
filesystem
s3
database
UPLOAD_PATH
data/uploads
no
The path where the uploaded files are stored. Only has an effect if
FILE_BACKEND
is
filesystem
or
s3
S3_BUCKET
yes
The S3 bucket name. Required if
FILE_BACKEND
is
s3
S3_REGION
yes
The S3 region. Required if
FILE_BACKEND
is
s3
S3_ENDPOINT
yes
The S3 endpoint URL. Required if
FILE_BACKEND
is
s3
S3_ACCESS_KEY_ID
yes
The S3 access key ID. Required if
FILE_BACKEND
is
s3
S3_SECRET_ACCESS_KEY
yes
The S3 secret access key. Required if
FILE_BACKEND
is
s3
S3_FORCE_PATH_STYLE
false
no
Force path style for S3.
S3_DISABLE_DEFAULT_INTEGRITY_CHECKS
false
no
Disable default integrity checks for S3.
LOG_LEVEL
info
no
How verbose the logs should be. Valid values:
debug
info
warn
error
GEOLITE_DB_PATH
data/GeoLite2-City.mmdb
no
The path where the GeoLite2 database should be stored.
GEOLITE_DB_URL
no
The custom download URL for the Geolite DB (default value should be fine for most users.)
PORT
1411
no
The port on which Pocket ID should listen.
HOST
0.0.0.0
no
The address on which Pocket ID should listen.
LOG_JSON
false
no
If true, emit logs formatted as JSON.
UNIX_SOCKET
no
The Unix socket path on which Pocket ID should listen. When set, the server will use a Unix socket instead of TCP, and the
PORT
HOST
parameters are ignored.
UNIX_SOCKET_MODE
no
The Unix socket mode. Only takes effect when
UNIX_SOCKET
is set.
LOCAL_IPV6_RANGES
no
User configured local IPv6 ranges for the audit log.
TLS_CERT
no
Base64-encoded TLS certificate. When set along with
TLS_KEY
, the server enables HTTPS.
TLS_KEY
no
Base64-encoded TLS private key. When set along with
TLS_CERT
, the server enables HTTPS. The server monitors the certificate and key files and will automatically reload them when they change.
UI_CONFIG_DISABLED
false
no
See
Overriding the UI configuration
ANALYTICS_DISABLED
false
no
Disable heartbeat that gets sent every 24 hours to count how many Pocket ID instances are running. This is recommended for air-gapped environments. Read more
about analytics
VERSION_CHECK_DISABLED
false
no
Set to true to disable the automatic version check against GitHub. This is highly recommended for air-gapped environments or deployments without reliable internet access.
INTERNAL_APP_URL
no
Sets the base URL of all URLs that need to be accessible from other clients in
/well-known/ openid-configuration
. This can be useful if
APP_URL
isn't accessible by your OIDC clients.
AUDIT_LOG_RETENTION_DAYS
90
no
Defines how many days it will take before the audit logs are deleted.
STATIC_API_KEY
no
A static API key that grants admin access to the Pocket ID instance. This will create an admin account called "Static API User" under the hood. This API key can be useful for declarative installations. If possible prefer
regular API Keys
DISABLE_RATE_LIMITING
false
no
You can disable the built-in rate limiting if you want to set your own rate limiting policy. Do not disable this if you don't have your own rate limiting configured in your reverse proxy.
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:
Format:
postgresql://[user[:password]@][netloc][:port][/dbname][?param1=value1&...]

Example:
postgres://pocketid:123456@localhost:5432/pocketid
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:
openssl rand -base64 32
You can pass the encryption key to Pocket ID in two ways:
Set its value in the
ENCRYPTION_KEY
variable directly
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
# Using the binary directly:
pocket-id encryption-key-rotate --new-key

# In Docker:
docker compose exec -it pocket-id ./pocket-id encryption-key-rotate --new-key
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.
Variable
Default Value
Description
APP_NAME
Pocket ID
The name of the app.
SESSION_DURATION
60
The duration of a session in minutes before the user has to sign in again.
HOME_PAGE_URL
/settings/account
The page users are redirected to after signing in.
EMAILS_VERIFIED
false
When enabled, users' email addresses will be marked as verified by default upon signup or when their email address is changed.
ALLOW_OWN_ACCOUNT_EDIT
true
Whether the users should be able to edit their own account details.
ALLOW_USER_SIGNUPS
disabled
Whether the user signup functionality is enabled. Valid Values:
disabled
withToken
open
SIGNUP_DEFAULT_CUSTOM_CLAIMS
[]
Assign these custom claims automatically to new users upon signup. Example:
[{"key":"claim1","value":"value1"},{"key":"claim2","value":"value2"}]
SIGNUP_DEFAULT_USER_GROUP_IDS
[]
Assign these groups automatically to new users upon signup. Example:
["a3888f2b-4c00-4b23-9c85-a3c8d685eb1f"]
DISABLE_ANIMATIONS
false
Turn off all animations throughout the Admin UI.
ACCENT_COLOR
default
A custom accent color for the UI. Accepts any valid CSS color value such as hex, RGB or HSL.
SMTP_HOST
SMTP server hostname.
SMTP_PORT
SMTP server port.
SMTP_FROM
Sender email address for outgoing emails. Format:
[email protected]
SMTP_USER
SMTP username for authentication.
SMTP_PASSWORD
SMTP password for authentication.
SMTP_PASSWORD_FILE
Alternative to
SMTP_PASSWORD_FILE
variable, set to the path of a file containing the SMTP password.
This can be used with Docker secrets too.
SMTP_TLS
none
Which TLS Option to use. Valid values are:
none
starttls
and
tls
SMTP_SKIP_CERT_VERIFY
false
Whether to skip SMTP certificate verification. This can be useful for self-signed certificates.
EMAIL_LOGIN_NOTIFICATION_ENABLED
false
Send an email to the user when they log in from a new device.
EMAIL_ONE_TIME_ACCESS_AS_ADMIN_ENABLED
false
Allows an admin to send a login code to the user via email.
EMAIL_API_KEY_EXPIRATION_ENABLED
false
Send an email to the user when their API key is about to expire.
EMAIL_ONE_TIME_ACCESS_AS_UNAUTHENTICATED_ENABLED
false
Allows users to bypass passkeys by requesting a login code sent to their email. This reduces the security significantly as anyone with access to the user's email can gain entry.
EMAIL_VERIFICATION_ENABLED
false
Send a verification email to users when they sign up or change their email address.
LDAP_ENABLED
false
Whether LDAP authentication is enabled.
LDAP_URL
LDAP server URL.
LDAP_BIND_DN
LDAP bind distinguished name (DN).
LDAP_BIND_PASSWORD
LDAP bind password.
LDAP_BIND_PASSWORD_FILE
Alternative to
LDAP_BIND_PASSWORD_FILE
variable, set to the path of a file containing the LDAP bind password.
This can be used with Docker secrets too.
LDAP_BASE
LDAP search base DN.
LDAP_USER_SEARCH_FILTER
(objectClass=person)
LDAP user search filter.
LDAP_USER_GROUP_SEARCH_FILTER
(objectClass=groupOfNames)
The Search filter to use to search/sync groups.
LDAP_SKIP_CERT_VERIFY
false
Whether to skip LDAP certificate verification. This can be useful for self-signed certificates.
LDAP_SOFT_DELETE_USERS
false
When enabled, users removed from LDAP will be disabled rather than deleted from the system.
LDAP_ATTRIBUTE_USER_UNIQUE_IDENTIFIER
LDAP attribute for user unique identifier. The value of this attribute should never change.
LDAP_ATTRIBUTE_USER_USERNAME
LDAP attribute for user username.
LDAP_ATTRIBUTE_USER_EMAIL
LDAP attribute for user email.
LDAP_ATTRIBUTE_USER_FIRST_NAME
LDAP attribute for user first name.
LDAP_ATTRIBUTE_USER_LAST_NAME
LDAP attribute for user last name.
LDAP_ATTRIBUTE_USER_PROFILE_PICTURE
LDAP attribute for the profile picture of a user.
LDAP_ATTRIBUTE_GROUP_MEMBER
member
LDAP attribute to use for querying members of a group.
LDAP_ATTRIBUTE_GROUP_UNIQUE_IDENTIFIER
LDAP attribute for group unique identifier. The value of this attribute should never change.
LDAP_ATTRIBUTE_GROUP_NAME
LDAP attribute for group name.
LDAP_ADMIN_GROUP_NAME
Name of the admin group. Members of this group will have Admin Privileges in Pocket ID.
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.
Variable
Default Value
Description
TRACING_ENABLED
false
Enables tracing support
METRICS_ENABLED
false
Enables metrics support
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:
OTEL_METRICS_EXPORTER=prometheus
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
Help improve this page
Edit this page on GitHub