Version: v3
Configuration
Langfuse has extensive configuration options via environment variables. These need to be passed to all application containers.
Environment Variables
Langfuse accepts additional environment variables to fine-tune your deployment. You can use the same environment variables for the Langfuse Web and Langfuse Worker containers.
Core Infrastructure Settings
| Variable | Required / Default | Description |
|---|---|---|
DATABASE_URL | Required | Connection string of your Postgres database. Instead of DATABASE_URL, you can also use DATABASE_HOST, DATABASE_USERNAME, DATABASE_PASSWORD and DATABASE_NAME. |
DIRECT_URL | DATABASE_URL | Connection string of your Postgres database used for database migrations. Use this if you want to use a different user for migrations or use connection pooling on DATABASE_URL. For large deployments, configure the database user with long timeouts as migrations might need a while to complete. |
SHADOW_DATABASE_URL | If your database user lacks the CREATE DATABASE permission, you must create a shadow database and configure the “SHADOW_DATABASE_URL”. This is often the case if you use a Cloud database. Refer to the Prisma docs for detailed instructions. | |
CLICKHOUSE_MIGRATION_URL | Required | Migration URL (TCP protocol) for the clickhouse instance. Pattern: clickhouse://<hostname>:(9000/9440) |
CLICKHOUSE_MIGRATION_SSL | false | Set to true to establish an SSL connection to Clickhouse for the database migration. |
CLICKHOUSE_URL | Required | Hostname of the clickhouse instance. Pattern: http(s)://<hostname>:(8123/8443) |
CLICKHOUSE_USER | Required | Username of the clickhouse database. Needs SELECT, ALTER, INSERT, CREATE, DELETE grants. |
CLICKHOUSE_PASSWORD | Required | Password of the clickhouse user. |
CLICKHOUSE_CLUSTER_ENABLED | true | Whether to run ClickHouse commands ON CLUSTER. Set to false for single-container setups. |
LANGFUSE_AUTO_CLICKHOUSE_MIGRATION_DISABLED | false | Whether to disable automatic ClickHouse migrations on startup. |
REDIS_CONNECTION_STRING | Required | Connection string of your redis instance. Instead of REDIS_CONNECTION_STRING, you can also use REDIS_HOST, REDIS_PORT, and REDIS_AUTH. |
NEXTAUTH_URL | Required | URL of your Langfuse web deployment, e.g. https://yourdomain.com or http://localhost:3000. Required for successful authentication via OAUTH. |
NEXTAUTH_SECRET | Required | Used to validate login session cookies, generate secret with at least 256 entropy using openssl rand -base64 32. |
SALT | Required | Used to salt hashed API keys, generate secret with at least 256 entropy using openssl rand -base64 32. |
ENCRYPTION_KEY | Required | Used to encrypt sensitive data. Must be 256 bits, 64 string characters in hex format, generate via: openssl rand -hex 32. |
LANGFUSE_CSP_ENFORCE_HTTPS | false | Set to true to set CSP headers to only allow HTTPS connections. Needs to be set at build-time. |
PORT | 3000 / 3030 | Port the server listens on. 3000 for web, 3030 for worker. |
HOSTNAME | localhost | In some environments it needs to be set to 0.0.0.0 to be accessible from outside the container (e.g. Google Cloud Run). |
LANGFUSE_S3_EVENT_UPLOAD_BUCKET | Required | Name of the bucket in which event information should be uploaded. |
LANGFUSE_S3_EVENT_UPLOAD_PREFIX | "" | Prefix to store events within a subpath of the bucket. Defaults to the bucket root. If provided, must end with a /. |
LANGFUSE_S3_EVENT_UPLOAD_REGION | Region in which the bucket resides. | |
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT | Endpoint to use to upload events. | |
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID | Access key for the bucket. Must have List, Get, and Put permissions. | |
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY | Secret access key for the bucket. | |
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE | Whether to force path style on requests. Required for MinIO. | |
LANGFUSE_S3_BATCH_EXPORT_ENABLED | false | Whether to enable Langfuse S3 batch exports. This must be set to true to enable batch exports. |
LANGFUSE_S3_BATCH_EXPORT_BUCKET | Required | Name of the bucket in which batch exports should be uploaded. |
LANGFUSE_S3_BATCH_EXPORT_PREFIX | "" | Prefix to store batch exports within a subpath of the bucket. Defaults to the bucket root. If provided, must end with a /. |
LANGFUSE_S3_BATCH_EXPORT_REGION | Region in which the bucket resides. | |
LANGFUSE_S3_BATCH_EXPORT_ENDPOINT | Endpoint to use to upload batch exports. | |
LANGFUSE_S3_BATCH_EXPORT_ACCESS_KEY_ID | Access key for the bucket. Must have List, Get, and Put permissions. | |
LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY | Secret access key for the bucket. | |
LANGFUSE_S3_BATCH_EXPORT_FORCE_PATH_STYLE | Whether to force path style on requests. Required for MinIO. | |
DB_EXPORT_PAGE_SIZE | 1000 | Optional page size for streaming exports to S3 to avoid memory issues. The page size can be adjusted if needed to optimize performance. |
LANGFUSE_S3_MEDIA_UPLOAD_BUCKET | Required | Name of the bucket in which media files should be uploaded. |
LANGFUSE_S3_MEDIA_UPLOAD_PREFIX | "" | Prefix to store media within a subpath of the bucket. Defaults to the bucket root. If provided, must end with a /. |
LANGFUSE_S3_MEDIA_UPLOAD_REGION | Region in which the bucket resides. | |
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT | Endpoint to use to upload media files. | |
LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID | Access key for the bucket. Must have List, Get, and Put permissions. | |
LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY | Secret access key for the bucket. | |
LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE | Whether to force path style on requests. Required for MinIO. | |
LANGFUSE_S3_MEDIA_MAX_CONTENT_LENGTH | 1_000_000_000 | Maximum file size in bytes that is allowed for upload. Default is 1GB. |
LANGFUSE_S3_MEDIA_DOWNLOAD_URL_EXPIRY_SECONDS | 3600 | Presigned download URL expiry in seconds. Defaults to 1h. |
LANGFUSE_AUTO_POSTGRES_MIGRATION_DISABLED | false | Set to true to disable automatic database migrations on docker startup. Not recommended. |
LANGFUSE_LOG_LEVEL | info | Set the log level for the application. Possible values are trace, debug, info, warn, error, fatal. |
LANGFUSE_LOG_FORMAT | text | Set the log format for the application. Possible values are text, json. |
Additional Features
There are additional features that can be enabled and configured via environment variables.
Authentication & SSOEncryptionHeadless InitializationNetworkingOrganization CreatorsUI Customization
Health and Readiness Check Endpoint
Langfuse web includes a health check endpoint at /api/public/health and a readiness check endpoint at /api/public/ready and the
Langfuse worker a health check endpoint at /api/health.
The health check endpoint indicates if the application is alive and the readiness check endpoint indicates if the application is ready to serve traffic.
Access the health and readiness check endpoints:
curl http://localhost:3000/api/public/health
curl http://localhost:3000/api/public/ready
curl http://localhost:3030/api/healthThe potential responses from the health check endpoint are:
200 OK: Both the API is functioning normally and a successful connection to the database was made.503 Service Unavailable: Either the API is not functioning or it couldn’t establish a connection to the database.
The potential responses from the readiness check endpoint are:
200 OK: The application is ready to serve traffic.500 Internal Server Error: The application received a SIGTERM or SIGINT and should not receive traffic.
Applications and monitoring services can call this endpoint periodically for health updates.
Per default, the Langfuse web healthcheck endpoint does not validate if the database is reachable, as there are cases where the
database is unavailable, but the application still serves traffic.
If you want to run database healthchecks, you can add ?failIfDatabaseUnavailable=true to the healthcheck endpoint.