# Source: https://langfuse.com/self-hosting/configuration.md

---
title: Configuration via Environment Variables (self-hosted)
description: Langfuse has extensive configuration options via environment variables.
label: "Version: v3"
sidebarTitle: "Environment Variables"
---

# Environment Variables

Langfuse (self-hosted) has extensive configuration options via environment variables. These need to be passed to all application containers.

| 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`, `DATABASE_NAME`, and `DATABASE_ARGS`.                                                                                                                                                                                                             |
| `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](https://www.prisma.io/docs/orm/prisma-migrate/understanding-prisma-migrate/shadow-database#cloud-hosted-shadow-databases-must-be-created-manually) 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_DB`                                 | `default`          | Name of the ClickHouse database to use.                                                                                                                                                                                                                                                                                                                                                               |
| `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`, `REDIS_USERNAME` and `REDIS_AUTH`. To configure TLS check the detailed [Cache Configuration Documentation](/self-hosting/deployment/infrastructure/cache#configuration).                                                                                                 |
| `REDIS_CLUSTER_ENABLED`                         | `false`            | Set to `true` to enable Redis cluster mode. When enabled, you must also provide `REDIS_CLUSTER_NODES`.                                                                                                                                                                                                                                                                                                |
| `REDIS_CLUSTER_NODES`                           |                    | Comma-separated list of Redis cluster nodes in the format `host:port`. Required when `REDIS_CLUSTER_ENABLED` is `true`. Example: `redis-node1:6379,redis-node2:6379,redis-node3:6379`.                                                                                                                                                                                                                |
| `REDIS_SENTINEL_ENABLED`                        | `false`            | Set to `true` to enable Redis Sentinel mode. Cannot be enabled simultaneously with cluster mode. When enabled, you must also provide `REDIS_SENTINEL_NODES` and `REDIS_SENTINEL_MASTER_NAME`.                                                                                                                                                                                                         |
| `REDIS_SENTINEL_NODES`                          |                    | Comma-separated list of Redis Sentinel nodes in the format `host:port`. Required when `REDIS_SENTINEL_ENABLED` is `true`. Example: `sentinel1:26379,sentinel2:26379,sentinel3:26379`.                                                                                                                                                                                                                 |
| `REDIS_SENTINEL_MASTER_NAME`                    |                    | Name of the Redis Sentinel master. Required when `REDIS_SENTINEL_ENABLED` is `true`. This must match the master name configured in your Sentinel setup.                                                                                                                                                                                                                                               |
| `REDIS_SENTINEL_USERNAME`                       |                    | Username for Redis Sentinel authentication (optional). Used when Sentinels require authentication.                                                                                                                                                                                                                                                                                                     |
| `REDIS_SENTINEL_PASSWORD`                       |                    | Password for Redis Sentinel authentication (optional). Used when Sentinels require authentication.                                                                                                                                                                                                                                                                                                     |
| `REDIS_AUTH`                                    |                    | Authentication string for the Redis instance or cluster.                                                                                                                                                                                                                                                                                                                                              |
| `NEXTAUTH_URL`                                  | Required           | URL of your Langfuse web deployment, e.g. `https://yourdomain.com` or `http://localhost:3000`. Required for successful authentication via OAUTH and sending valid Links via Slack integration.                                                                                                                                                                                                        |
| `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.                                                                                                                                                                                                                                                                                                                                     |
| `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_CACHE_API_KEY_ENABLED`                | `true`             | Enable or disable API key caching. Set to `false` to disable caching of API keys. Plain-text keys are never stored in Redis, only hashed or encrypted keys.                                                                                                                                                                                                                                           |
| `LANGFUSE_CACHE_API_KEY_TTL_SECONDS`            | `300`              | Time-to-live (TTL) in seconds for cached API keys. Determines how long API keys remain in the cache before being refreshed.                                                                                                                                                                                                                                                                           |
| `LANGFUSE_CACHE_PROMPT_ENABLED`                 | `true`             | Enable or disable prompt caching. Set to `false` to disable caching of prompts.                                                                                                                                                                                                                                                                                                                       |
| `LANGFUSE_CACHE_PROMPT_TTL_SECONDS`             | `300`              | Time-to-live (TTL) in seconds for cached prompts. Determines how long prompts remain in the cache before being refreshed.                                                                                                                                                                                                                                                                             |
| `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.                                                                                                                                                                                                                                                                                                                                          |
| `LANGFUSE_S3_BATCH_EXPORT_EXTERNAL_ENDPOINT`    |                    | Optional external endpoint for generating presigned URLs. If not provided, the main endpoint is used. Useful, if langfuse traffic to the blobstorage should remain within the VPC.                                                                                                                                                                                                                    |
| `BATCH_EXPORT_PAGE_SIZE`                        | `500`              | Optional page size for streaming exports to S3 to avoid memory issues. The page size can be adjusted if needed to optimize performance.                                                                                                                                                                                                                                                               |
| `BATCH_EXPORT_ROW_LIMIT`                        | `1_500_000`        | Maximum amount of rows that can be exported in a single batch export.                                                                                                                                                                                                                                                                                                                                 |
| `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_S3_CONCURRENT_WRITES`                 | `50`               | Maximum number of concurrent writes to S3. Useful for errors like `@smithy/node-http-handler:WARN - socket usage at capacity=50`.                                                                                                                                                                                                                                                                     |
| `LANGFUSE_S3_CONCURRENT_READS`                  | `50`               | Maximum number of concurrent reads from S3. Useful for errors like `@smithy/node-http-handler:WARN - socket usage at capacity=50`.                                                                                                                                                                                                                                                                    |
| `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`.                                                                                                                                                                                                                                                                                                                           |
| `LANGFUSE_LOG_PROPAGATED_HEADERS`               |                    | Comma-separated list of HTTP header names to propagate through logs via OpenTelemetry baggage. Header names are case-insensitive and will be normalized to lowercase. Useful for debugging and observability. Example: `x-request-id,x-user-id`.                                                                                                                                                      |

### Additional Features

There are additional features that can be enabled and configured via environment variables.



import {
  Lock,
  Shield,
  Network,
  Users,
  Brush,
  Workflow,
  UserCog,
  Route,
  Mail,
  ServerCog,
  Activity,
  Eye,
  Zap,
} from "lucide-react";

import { Cards } from "nextra/components";

<Cards num={3}>
  <Cards.Card
    icon={<Lock size="24" />}
    title="Authentication & SSO"
    href="/self-hosting/security/authentication-and-sso"
    arrow
  />
  <Cards.Card
    icon={<UserCog size="24" />}
    title="Automated Access Provisioning"
    href="/self-hosting/administration/automated-access-provisioning"
    arrow
  />
  <Cards.Card
    icon={<Zap size="24" />}
    title="Caching"
    href="/self-hosting/configuration/caching"
    arrow
  />
  <Cards.Card
    icon={<Route size="24" />}
    title="Custom Base Path"
    href="/self-hosting/configuration/custom-base-path"
    arrow
  />
  <Cards.Card
    icon={<Shield size="24" />}
    title="Encryption"
    href="/self-hosting/configuration/encryption"
    arrow
  />
  <Cards.Card
    icon={<Workflow size="24" />}
    title="Headless Initialization"
    href="/self-hosting/administration/headless-initialization"
    arrow
  />
  <Cards.Card
    icon={<Network size="24" />}
    title="Networking"
    href="/self-hosting/security/networking"
    arrow
  />
  <Cards.Card
    icon={<Users size="24" />}
    title="Organization Creators (EE)"
    href="/self-hosting/administration/organization-creators"
    arrow
  />
  <Cards.Card
    icon={<ServerCog size="24" />}
    title="Instance Management API (EE)"
    href="/self-hosting/administration/instance-management-api"
    arrow
  />
  <Cards.Card
    icon={<Activity size="24" />}
    title="Health and Readiness Check"
    href="/self-hosting/configuration/health-readiness-endpoints"
    arrow
  />
  <Cards.Card
    icon={<Eye size="24" />}
    title="Observability via OpenTelemetry"
    href="/self-hosting/configuration/observability"
    arrow
  />
  <Cards.Card
    icon={<Mail size="24" />}
    title="Transactional Emails"
    href="/self-hosting/configuration/transactional-emails"
    arrow
  />
  <Cards.Card
    icon={<Brush size="24" />}
    title="UI Customization (EE)"
    href="/self-hosting/administration/ui-customization"
    arrow
  />
</Cards>