Environment Variables
These are the environment variables that configure a self-hosted Permiso instance. Variables marked as required must be set; Permiso will fail to start without them.
For variables that contain secrets (like ENCRYPTION_KEY), you can also set a _FILE variant pointing to a file path, e.g. ENCRYPTION_KEY_FILE=/run/secrets/encryption_key. Permiso will read the value from that file at startup.
Core
| Variable | Required | Default | Description |
|---|
APP_URL | Yes | - | The public URL of your Permiso instance, e.g. https://auth.example.com. Must not include a trailing slash or path. |
ENCRYPTION_KEY | Yes | - | A secret key used to encrypt sensitive data in the database. Must be at least 16 bytes. Generate one with openssl rand -hex 32. |
APP_ENV | No | production | Set to development to enable development mode. |
INTERNAL_APP_URL | No | Same as APP_URL | The internal URL used for server-to-server calls. Set this if Permiso can't reach itself via the public URL (e.g. in a Kubernetes cluster). |
AUDIT_LOG_RETENTION_DAYS | No | 90 | How many days to keep audit log entries before they're automatically deleted. |
ANALYTICS_DISABLED | No | false | Set to true to disable anonymous usage analytics. |
VERSION_CHECK_DISABLED | No | false | Set to true to disable automatic version update checks. |
Database
| Variable | Required | Default | Description |
|---|
DB_CONNECTION_STRING | No | data/permiso.db (SQLite) | Database connection string. Use a postgres:// URL to switch to PostgreSQL, e.g. postgres://user:password@host:5432/permiso. |
Network
| Variable | Required | Default | Description |
|---|
PORT | No | 1812 | The port Permiso listens on. |
HOST | No | 0.0.0.0 | The host address to bind to. |
UNIX_SOCKET | No | - | Path to a Unix socket to listen on instead of TCP. |
TRUST_PROXY | No | false | Set to true if Permiso is behind a reverse proxy that sets X-Forwarded-For headers. Required for accurate IP addresses in audit logs. |
TRUSTED_PLATFORM | No | - | Set to cf-connecting-ip (Cloudflare) or x-real-ip (nginx) to use a specific header for the client IP. |
Storage
| Variable | Required | Default | Description |
|---|
FILE_BACKEND | No | filesystem | Where to store uploaded files. Options: filesystem, s3, database. |
UPLOAD_PATH | No | data/uploads | Local directory for uploads when using the filesystem backend. |
S3_BUCKET | For S3 | - | S3 bucket name. |
S3_REGION | For S3 | - | AWS region, e.g. eu-west-1. |
S3_ENDPOINT | For non-AWS S3 | - | Custom S3 endpoint URL for non-AWS providers (Cloudflare R2, MinIO, etc.). |
S3_ACCESS_KEY_ID | For S3 | - | S3 access key ID. |
S3_SECRET_ACCESS_KEY | For S3 | - | S3 secret access key. |
S3_FORCE_PATH_STYLE | No | false | Set to true for providers that require path-style bucket URLs (common with MinIO). |
Security
| Variable | Required | Default | Description |
|---|
STATIC_API_KEY | No | - | A fixed API key that can be used for automated access. Must be at least 16 characters. Useful for provisioning scripts run at deploy time. |
UI_CONFIG_DISABLED | No | false | Set to true to prevent SMTP passwords and other sensitive values from being changed via the UI. Useful when you manage configuration via environment variables and don't want it overwritten. |
DISABLE_RATE_LIMITING | No | false | Set to true to disable rate limiting. Not recommended for production. |
ALLOW_DOWNGRADE | No | false | Set to true to allow running an older version of Permiso against a database that was created by a newer version. |
Geolocation
| Variable | Required | Default | Description |
|---|
MAXMIND_LICENSE_KEY | No | - | A MaxMind license key for downloading the GeoLite2-City database. Enables IP geolocation in audit logs. Get a free key at maxmind.com. |
GEOLITE_DB_PATH | No | data/GeoLite2-City.mmdb | Path to a local GeoLite2 database file. Use this if you want to provide the database yourself instead of having Permiso download it. |
Logging and observability
| Variable | Required | Default | Description |
|---|
LOG_LEVEL | No | info | Log verbosity. Options: debug, info, warn, error. |
LOG_JSON | No | false | Set to true to output logs in JSON format, suitable for structured logging systems. |
METRICS_ENABLED | No | false | Set to true to enable a Prometheus-compatible /metrics endpoint. |
TRACING_ENABLED | No | false | Set to true to enable OpenTelemetry tracing. |