Langfuse Self Hosting

https://langfuse.com/self-hosting
Admin
Langfuse Self Hosting provides comprehensive guides and documentation for deploying the open-source...
Tokens:137,740
Snippets:1,103
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Setup Docker apt Repository

Source: https://langfuse.com/self-hosting/deployment/docker-compose

Sets up Docker's apt repository on Ubuntu by adding the official GPG key and repository to Apt sources. Run before installing Docker packages.

```bash
# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
```

--------------------------------

### Clone Langfuse repository and prepare .env

Source: https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v1-to-v2

Clone the Langfuse repository, checkout the v2 branch, install dependencies, and create an .env file from the example.

```bash
# Clone the Langfuse repository
git clone https://github.com/langfuse/langfuse.git

# Navigate to the Langfuse directory
cd langfuse

# Checkout the Langfuse v2 branch
git checkout v2

# Install all dependencies
pnpm i

# Create an .env file
cp .env.dev.example .env
```

--------------------------------

### Start MinIO container with Docker

Source: https://langfuse.com/self-hosting/infrastructure/blobstorage

Starts a local MinIO container with Docker. The console is available at http://localhost:9001, where you must create a bucket named 'langfuse'. This setup uses an ephemeral volume, so data is lost on restart.

```bash
docker run --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -e MINIO_ROOT_USER=minio \
  -e MINIO_ROOT_PASSWORD=miniosecret \
  minio/minio server /data --console-address ":9001"
```

--------------------------------

### Install via legacy Helm repo

Source: https://langfuse.com/self-hosting/deployment/kubernetes-helm

Alternative installation using the legacy Helm repository. Add the repo, update, and install with a values file.

```bash
helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm repo update
helm install langfuse langfuse/langfuse -n langfuse -f values.yaml
```

--------------------------------

### Verify Docker Installation

Source: https://langfuse.com/self-hosting/deployment/docker-compose

Verifies that Docker is installed correctly by running the hello-world container.

```bash
sudo docker run hello-world
```

--------------------------------

### Install Docker Packages

Source: https://langfuse.com/self-hosting/deployment/docker-compose

Installs Docker Engine, CLI, containerd, and the Docker Compose plugin on Ubuntu.

```bash
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

--------------------------------

### Start Langfuse with Docker Compose

Source: https://langfuse.com/self-hosting/deployment/docker-compose

Starts the Langfuse application using Docker Compose. After about 2-3 minutes, the langfuse-web-1 container should log "Ready".

```bash
docker compose up
```

--------------------------------

### Install Langfuse Helm chart

Source: https://langfuse.com/self-hosting/deployment/kubernetes-helm

Installs the Langfuse Helm chart into the 'langfuse' namespace. The chart assumes it is installed as 'langfuse'.

```bash
helm install langfuse langfuse/langfuse -n langfuse
```

--------------------------------

### Minimal installation with pre-created Secret

Source: https://langfuse.com/self-hosting/deployment/kubernetes-helm

Install Langfuse with a minimal configuration using a pre-created Secret for credentials. Edit examples/minimal-installation/secret.yaml first.

```bash
kubectl create namespace langfuse
# Edit examples/minimal-installation/secret.yaml, then:
kubectl apply -f examples/minimal-installation/secret.yaml -n langfuse

helm install langfuse oci://ghcr.io/langfuse/langfuse-k8s/charts/langfuse \
  --version 2.0.0 \
  --namespace langfuse \
  -f examples/minimal-installation/values.yaml
```

--------------------------------

### Install helm-unittest plugin

Source: https://langfuse.com/self-hosting/deployment/kubernetes-helm

Installs the Helm unittest plugin required for running chart tests.

```bash
helm plugin install https://github.com/helm-unittest/helm-unittest.git

```

--------------------------------

### Start Langfuse v3 deployment

Source: https://langfuse.com/self-hosting/upgrade-guides/upgrade-v2-to-v3

Command to start the Langfuse v3 deployment. Replace `docker-compose.v3.yml` with the name of the file created in step 2.

```bash
docker compose -f docker-compose.v3.yml up -d

```

--------------------------------

### Install Velero and create backup schedule

Source: https://langfuse.com/self-hosting/configuration/backups

Installs Velero with AWS plugin and creates a daily backup schedule for the langfuse namespace with a 30-day TTL. Provides comprehensive Kubernetes cluster backups.

```bash
velero install --provider aws --plugins velero/velero-plugin-for-aws:v1.8.0 \
  --bucket langfuse-backups --secret-file ./credentials-velero
```

```bash
velero schedule create langfuse-daily \
  --schedule="0 2 * * *" \
  --include-namespaces langfuse \
  --ttl 720h0m0s
```

--------------------------------

### GET /api/public/ready

Source: https://langfuse.com/self-hosting/configuration/health-readiness-endpoints

Readiness check endpoint for the web container. Verifies that the service is ready to receive traffic.

```APIDOC
## [GET] /api/public/ready

### Description
Checks if the web service is ready to receive traffic. This endpoint is used by load balancers and orchestration systems to determine if the service can accept requests.

### Method
GET

### Endpoint
/api/public/ready

### Response
#### Success Response (200)
- Service is ready to receive traffic

```

--------------------------------

### Check nameserver delegation with dig

Source: https://langfuse.com/self-hosting/deployment/aws

Example dig command and output showing the nameservers returned for the domain, used to set up delegation on the DNS provider.

```bash
$ dig NS langfuse.example.com
ns-1.awsdns-00.org.
ns-2.awsdns-01.net.
ns-3.awsdns-02.com.
ns-4.awsdns-03.co.uk.

```

--------------------------------

### Langfuse S3 event upload environment variables

Source: https://langfuse.com/self-hosting/infrastructure/blobstorage

Environment variables to start Langfuse with SeaweedFS as the S3 event upload backend. The SeaweedFS S3 gateway expects path-style requests, so set FORCE_PATH_STYLE to true for events, media, and batch exports. This example does not mount a persistent volume, so data is discarded when the container is removed.

```bash
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse
LANGFUSE_S3_EVENT_UPLOAD_REGION=us-east-1
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=seaweedfs
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=seaweedfssecret
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=http://seaweedfs:8333
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE=true
LANGFUSE_S3_EVENT_UPLOAD_PREFIX=events/
```

--------------------------------

### Configure instance switcher with LANGFUSE_UI_INSTANCE_LINKS

Source: https://langfuse.com/self-hosting/administration/ui-customization

Set this environment variable to configure the instance switcher in the sidebar user menu. The value must be a JSON array of objects with a unique name and an http(s) url. If the value is not valid JSON in the expected shape, the switcher is hidden and a warning naming the problem is logged; the deployment still starts.

```plaintext
LANGFUSE_UI_INSTANCE_LINKS='[{"name":"Staging","url":"https://langfuse-staging.example.com"},{"name":"Production","url":"https://langfuse.example.com"}]'
```

--------------------------------

### Docker Compose volume configuration for Postgres

Source: https://langfuse.com/self-hosting/upgrade-guides/upgrade-v2-to-v3

Example volume configuration for the Postgres instance in a Langfuse v2 deployment. Note the volume name (e.g., `database_data`) as it is needed in step 2.

```yaml
volumes:
  database_data:
    driver: local

```

--------------------------------

### GET /api/public/ready

Source: https://langfuse.com/self-hosting/configuration/health-readiness-endpoints

Readiness check endpoint for the Langfuse self-hosted web application.

```APIDOC
## GET /api/public/ready

### Description
Checks whether the web application is ready to receive traffic, particularly useful during graceful shutdowns.

### Method
GET

### Endpoint
/api/public/ready

### Response
#### Success Response (200)
- **200 OK** - Application is ready to serve traffic

#### Error Response (500)
- **500 Internal Server Error** - Application has received a shutdown signal (SIGTERM or SIGINT) and should not receive new traffic

```

--------------------------------

### Install cert-manager and clickhouse-operator CRDs

Source: https://langfuse.com/self-hosting/deployment/kubernetes-helm

Install cert-manager and clickhouse-operator CRDs once per cluster before installing the chart. Required when clickhouse.deploy is true (default).

```bash
# 1. cert-manager (skip if already installed)
helm install cert-manager oci://quay.io/jetstack/charts/cert-manager \
  --version v1.20.2 \
  --namespace cert-manager --create-namespace \
  --set crds.enabled=true

kubectl wait --for=condition=Established \
  crd/certificates.cert-manager.io crd/issuers.cert-manager.io \
  --timeout=120s

# 2. clickhouse-operator
helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
  --version 0.0.5 \
  --namespace clickhouse-operator --create-namespace

kubectl wait --for=condition=Established \
  crd/clickhouseclusters.clickhouse.com crd/keeperclusters.clickhouse.com \
  --timeout=120s
```

--------------------------------

### Get DNS name servers

Source: https://langfuse.com/self-hosting/deployment/azure

Outputs the name servers to delegate to on your DNS provider.

```bash
terraform output dns_name_servers

```

--------------------------------

### Create grant on all cluster nodes with ON CLUSTER

Source: https://langfuse.com/self-hosting/deployment/infrastructure/clickhouse

Example of creating a grant on all nodes of a cluster by adding ON CLUSTER. Grants are local to the node they are created on unless the cluster uses a replicated access storage backend.

```sql
GRANT ON CLUSTER default SELECT ON system.query_log* TO 'user';
```

--------------------------------

### S3 Event Upload with Access Key Pair

Source: https://langfuse.com/self-hosting/infrastructure/blobstorage

Example environment variables for S3 event upload when authenticating with an Access Key pair. Includes bucket, region, access key ID, and secret access key.

```bash
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=my-bucket-name
LANGFUSE_S3_EVENT_UPLOAD_REGION=my-bucket-region
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```

--------------------------------

### Configure Langfuse for Azure Blob Storage

Source: https://langfuse.com/self-hosting/infrastructure/blobstorage

Environment variables to connect Langfuse to Azure Blob Storage. Requires a container and a static account key. The example uses sample credentials from Azurite. The special flag LANGFUSE_USE_AZURE_BLOB=true enables the Azure Blob Storage interface.

```bash
# Special flag to enable the Azure Blob Storage interface
LANGFUSE_USE_AZURE_BLOB=true

LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse # Container name - If it does not exists, Langfuse will attempt to create it
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=devstoreaccount1 # ABS Account
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw== # ABS Account Key
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=http://localhost:10000/devstoreaccount1 # URL, e.g. `https://${account}.blob.core.windows.net`
```

--------------------------------

### Apply DNS zone and GKE cluster

Source: https://langfuse.com/self-hosting/deployment/gcp

Initializes Terraform and applies only the DNS zone and GKE cluster. This two-stage apply is the supported installation flow because the kubernetes and helm providers depend on the cluster's outputs.

```bash
terraform init
terraform apply --target module.langfuse.google_dns_managed_zone.this --target module.langfuse.google_container_cluster.this

```

--------------------------------

### Minimum production ClickHouse values.yaml overrides

Source: https://langfuse.com/self-hosting/deployment/infrastructure/clickhouse

Recommended values.yaml overrides for a minimum production setup of the bundled ClickHouse in the Langfuse Helm chart. Sets deploy to true, configures auth credentials, 3 replicas, storage size, resource requests/limits, and 3 keeper replicas.

```yaml
clickhouse:
  deploy: true
  auth:
    username: default
    password: changeme # or point auth.existingSecret at a secret you manage
  cluster:
    replicas: 3
    storage:
      size: 100Gi # Start with a large volume to prevent early resizing. Alternatively, consider a blob storage-backed disk.
    resources:
      requests:
        cpu: "2"
        memory: 8Gi
      limits:
        memory: 16Gi
  keeper:
    replicas: 3

```

--------------------------------

### Apply DNS zone and AKS cluster

Source: https://langfuse.com/self-hosting/deployment/azure

Initializes Terraform and applies the DNS zone and AKS cluster targets. This two-stage apply is the supported installation flow because the kubernetes and helm providers depend on the cluster outputs.

```bash
terraform init
terraform apply --target module.langfuse.azurerm_dns_zone.this --target module.langfuse.azurerm_kubernetes_cluster.this

```

--------------------------------

### Get DNS nameservers

Source: https://langfuse.com/self-hosting/deployment/gcp

Retrieves the nameservers for the managed zone named 'langfuse' (replace with your zone name, e.g., 'langfuse-example-com') to set up Nameserver delegation on your DNS provider.

```bash
$ gcloud dns managed-zones describe langfuse --format="get(nameServers)"

```

--------------------------------

### Run SeaweedFS container with S3 gateway

Source: https://langfuse.com/self-hosting/infrastructure/blobstorage

Starts a local SeaweedFS container with the S3 gateway enabled on port 8333, mounting the s3.json identities file. Always pass an identities file via -s3.config; without one, the gateway does not enforce authentication.

```bash
docker run --name seaweedfs \
  -p 8333:8333 \
  -v "$(pwd)/s3.json:/etc/seaweedfs/s3.json:ro" \
  chrislusf/seaweedfs server -s3 -s3.config=/etc/seaweedfs/s3.json -dir=/data
```

--------------------------------

### Self-hosted Redis Cluster Configuration

Source: https://langfuse.com/self-hosting/deployment/infrastructure/cache

Example configuration for a self-hosted Redis cluster. Set REDIS_CLUSTER_ENABLED to true, list all cluster node addresses in REDIS_CLUSTER_NODES, and provide the cluster password via REDIS_AUTH.

```plaintext
REDIS_CLUSTER_ENABLED=true
REDIS_CLUSTER_NODES=10.0.1.10:6379,10.0.1.11:6379,10.0.1.12:6379,10.0.1.13:6379,10.0.1.14:6379,10.0.1.15:6379
REDIS_AUTH=your-cluster-password
```

--------------------------------

### Restart CoreDNS and delete ClickHouse/Keeper pods

Source: https://langfuse.com/self-hosting/deployment/aws

Commands to resolve the race conditions on first install: update kubeconfig for the EKS cluster, restart CoreDNS, and delete the pending ClickHouse and Keeper pods so the StatefulSet recreates them.

```bash
# Connect your kubectl to the EKS cluster
aws eks update-kubeconfig --name langfuse

# Restart the CoreDNS and ClickHouse containers
kubectl --namespace kube-system rollout restart deploy coredns
kubectl --namespace langfuse delete pod langfuse-clickhouse-0-{0,1,2}-0 langfuse-keeper-{0,1,2}-0

```

--------------------------------

### Clone Langfuse Repository

Source: https://langfuse.com/self-hosting/deployment/docker-compose

Clones the Langfuse repository and changes into the project directory. Required before starting the application with Docker Compose.

```bash
git clone https://github.com/langfuse/langfuse.git
cd langfuse
```

--------------------------------

### S3 Event Upload with IAM Role

Source: https://langfuse.com/self-hosting/infrastructure/blobstorage

Example environment variable for S3 event upload when authenticating with an IAM role. Only the bucket name is needed.

```bash
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=my-bucket-name
```

--------------------------------

### ClickHouse native backup and restore to S3

Source: https://langfuse.com/self-hosting/configuration/backups

Uses ClickHouse's native backup functionality to back up and restore the default database to S3. Follow the ClickHouse backup guide for full details.

```sql
-- Create a backup
BACKUP DATABASE default TO S3('s3://backup-bucket/clickhouse-backup-{timestamp}', 'access_key', 'secret_key');
```

```sql
-- Restore from backup
RESTORE DATABASE default FROM S3('s3://backup-bucket/clickhouse-backup-{timestamp}', 'access_key', 'secret_key');
```

--------------------------------

### Azure Blob Storage ClickHouse config and Docker Compose

Source: https://langfuse.com/self-hosting/deployment/infrastructure/clickhouse

Configure ClickHouse to use Azure Blob Storage via an object storage disk and start ClickHouse with an Azurite emulator using Docker Compose. The config.xml uses default Azurite credentials (considered public) and mounts into the ClickHouse container as azuredisk.xml. The Compose file defines ClickHouse and Azurite services with shared volumes, storing ClickHouse data in the Azurite bucket.

```xml
<clickhouse>
    <merge_tree>
        <storage_policy>blob_storage_disk</storage_policy>
    </merge_tree>
    <storage_configuration>
        <disks>
            <blob_storage_disk>
                <type>object_storage</type>
                <object_storage_type>azure_blob_storage</object_storage_type>
                <metadata_type>local</metadata_type>
                <storage_account_url>http://azurite:10000/devstoreaccount1</storage_account_url>
                <container_name>langfuse</container_name>
                <account_name>devstoreaccount1</account_name>
                <account_key>Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==</account_key>
            </blob_storage_disk>
        </disks>
        <policies>
            <blob_storage_disk>
                <volumes>
                    <main>
                        <disk>blob_storage_disk</disk>
                    </main>
                </volumes>
            </blob_storage_disk>
        </policies>
    </storage_configuration>
</clickhouse>
```

```yaml
services:
  clickhouse:
    image: clickhouse/clickhouse-server
    user: "101:101"
    container_name: clickhouse
    hostname: clickhouse
    environment:
      CLICKHOUSE_DB: default
      CLICKHOUSE_USER: clickhouse
      CLICKHOUSE_PASSWORD: clickhouse
    volumes:
      - ./config.xml:/etc/clickhouse-server/config.d/azuredisk.xml:ro
      - langfuse_clickhouse_data:/var/lib/clickhouse
      - langfuse_clickhouse_logs:/var/log/clickhouse-server
    ports:
      - "8123:8123"
      - "9000:9000"
    depends_on:
      - azurite

  azurite:
    image: mcr.microsoft.com/azure-storage/azurite
    container_name: azurite
    command: azurite-blob --blobHost 0.0.0.0
    ports:
      - "10000:10000"
    volumes:
      - langfuse_azurite_data:/data

volumes:
  langfuse_clickhouse_data:
    driver: local
  langfuse_clickhouse_logs:
    driver: local
  langfuse_azurite_data:
    driver: local
```

--------------------------------

### AWS Terraform module for Langfuse Assistant

Source: https://langfuse.com/self-hosting/configuration/langfuse-assistant

Terraform module configuration for AWS deployment. The Langfuse Terraform module for AWS supports the Assistant from `v1.2.0` and configures the model, grants Bedrock invoke on the Langfuse IAM role, and optionally creates the sandbox. The module deploys the Helm chart, so it fills in the values above for you. The sandbox runs in an isolated VPC with no route to the Langfuse VPC or the internet, shared with the code evaluator runners; each workload gets its own deny-all security group. The module does not build the MicroVM image, so run the build script after `terraform apply`.

```hcl
module "langfuse" {
  # ...
  app_version = "4.28.0" # or newer

  enable_ai_features   = true
  ai_features_provider = "bedrock"
  ai_features_model    = "eu.anthropic.claude-opus-5"
  enable_in_app_agent  = true

  # Optional, a cheaper model for supplementary calls such as conversation titles
  ai_features_small_model = "eu.anthropic.claude-haiku-4-5-20251001-v1:0"

  # Optional, isolated file and code execution
  enable_agent_sandbox_microvm = true
}
```

--------------------------------

### Self-hosted Redis with Sentinel Configuration

Source: https://langfuse.com/self-hosting/deployment/infrastructure/cache

Example configuration for a self-hosted Redis deployment with Sentinel. Ensure all Sentinel nodes are accessible from Langfuse containers, REDIS_SENTINEL_MASTER_NAME matches the Sentinel master name, and set maxmemory-policy=noeviction on Redis master and replicas to prevent queue job eviction.

```plaintext
REDIS_SENTINEL_ENABLED=true
REDIS_SENTINEL_NODES=10.0.1.10:26379,10.0.1.11:26379,10.0.1.12:26379
REDIS_SENTINEL_MASTER_NAME=langfuse-master
REDIS_AUTH=your-redis-password
```

--------------------------------

### S3 Blob Storage Disk Configuration and Docker Compose

Source: https://langfuse.com/self-hosting/deployment/infrastructure/clickhouse

Configures ClickHouse to use S3 as an external disk and starts the ClickHouse Docker container with that configuration. Replace the access key, secret, and bucket name in the endpoint, or use <use_environment_credentials>1</use_environment_credentials> to retrieve AWS credentials from environment variables. Metadata remains on local disk, so a persistent volume is required for /var/lib/clickhouse.

```xml
<clickhouse>
    <merge_tree>
        <storage_policy>s3</storage_policy>
    </merge_tree>
    <storage_configuration>
        <disks>
            <s3>
                <type>object_storage</type>
                <object_storage_type>s3</object_storage_type>
                <metadata_type>local</metadata_type>
                <endpoint>https://s3.eu-central-1.amazonaws.com/example-bucket-name/data/</endpoint>
                <access_key_id>ACCESS_KEY</access_key_id>
                <secret_access_key>ACCESS_KEY_SECRET</secret_access_key>
            </s3>
        </disks>
        <policies>
            <s3>
                <volumes>
                    <main>
                        <disk>s3</disk>
                    </main>
                </volumes>
            </s3>
        </policies>
    </storage_configuration>
</clickhouse>
```

```yaml
services:
  clickhouse:
    image: clickhouse/clickhouse-server
    user: "101:101"
    container_name: clickhouse
    hostname: clickhouse
    environment:
      CLICKHOUSE_DB: default
      CLICKHOUSE_USER: clickhouse
      CLICKHOUSE_PASSWORD: clickhouse
    volumes:
      - ./config.xml:/etc/clickhouse-server/config.d/s3disk.xml:ro
      - langfuse_clickhouse_data:/var/lib/clickhouse
      - langfuse_clickhouse_logs:/var/log/clickhouse-server
    ports:
      - "8123:8123"
      - "9000:9000"

volumes:
  langfuse_clickhouse_data:
    driver: local
  langfuse_clickhouse_logs:
    driver: local
```

--------------------------------

### Enable the Assistant with LANGFUSE_IN_APP_AGENT_ENABLED

Source: https://langfuse.com/self-hosting/configuration/langfuse-assistant

Enable the Assistant on web and worker after the model and MCP connection work and any optional sandbox setup. Unset or false hides the Assistant even when AI Features is enabled for the organization. Workers with this variable consume the Assistant run queue; leave it unset on ingestion-only workers.

```bash
LANGFUSE_IN_APP_AGENT_ENABLED=true
```

--------------------------------

### Event Propagation Staleness Probe with failIfEventPropagationStuck

Source: https://langfuse.com/self-hosting/configuration/health-readiness-endpoints

Probe for event-propagation staleness during v3 to v4 dual write mode. Returns 503 when the job's last run started more than LANGFUSE_EVENT_PROPAGATION_STUCK_THRESHOLD_MINUTES (default 15) ago. Reads only Redis and never fails on deployments where the job does not run. For Kubernetes liveness probes, set initialDelaySeconds to at least 60.

```bash
curl "http://localhost:3030/api/health?failIfEventPropagationStuck=true"
```

--------------------------------

### Queue Consumption Liveness Probe with failIfQueueConsumptionStuck

Source: https://langfuse.com/self-hosting/configuration/health-readiness-endpoints

Probe for queue consumption liveness. Returns 503 when the worker has neither picked up nor completed a job across all queues for more than LANGFUSE_QUEUE_CONSUMPTION_STUCK_THRESHOLD_MINUTES (default 60). Tracked in memory per container, so freshly started containers get the full threshold as grace period. Use in a liveness probe to restart wedged containers.

```bash
curl "http://localhost:3030/api/health?failIfQueueConsumptionStuck=true"
```

--------------------------------

### Initialize Terraform and apply DNS zone

Source: https://langfuse.com/self-hosting/deployment/aws

Initializes Terraform and applies only the Route53 zone resource to create the DNS zone before setting up nameserver delegation.

```bash
terraform init
terraform apply --target module.langfuse.aws_route53_zone.zone

```

--------------------------------

### Build Langfuse Web image from source with NEXT_PUBLIC_BASE_PATH

Source: https://langfuse.com/self-hosting/configuration/custom-base-path

Commands to clone the Langfuse repository, checkout the production branch, and build the web container image with the custom base path as a build argument. The production branch is recommended because the main branch includes unreleased changes that might be unstable.

```bash
# clone repo
git clone https://github.com/langfuse/langfuse.git
cd langfuse

# checkout production branch
# main branch includes unreleased changes that might be unstable
git checkout production

# build image with NEXT_PUBLIC_BASE_PATH
docker build -t langfuse/langfuse --build-arg NEXT_PUBLIC_BASE_PATH=/langfuse-base-path -f ./web/Dockerfile .
```

--------------------------------

### Build Langfuse containers from source

Source: https://langfuse.com/self-hosting/deployment/infrastructure/containers

Clone the Langfuse repository, checkout the production branch, and build the web and worker Docker images. The production branch is recommended as the main branch may contain unstable unreleased changes.

```bash
# clone repo
git clone https://github.com/langfuse/langfuse.git
cd langfuse

# checkout production branch
# main branch includes unreleased changes that might be unstable
git checkout production

# build web image
docker build -t langfuse/langfuse -f ./web/Dockerfile .

# build worker image
docker build -t langfuse/langfuse-worker -f ./worker/Dockerfile .
```

--------------------------------

### Run models migration

Source: https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v1-to-v2

Execute the migration to apply new model logic and prices to existing data. This may take a while depending on database size.

```bash
pnpm run models:migrate
```

--------------------------------

### Build the MicroVM image with build-microvm-image.sh

Source: https://langfuse.com/self-hosting/configuration/langfuse-assistant

Run from the Langfuse repository root to build the MicroVM image in your AWS account. Requires Lambda MicroVMs in the Region, an AWS CLI with lambda-microvms support (2.36.1 is known to work), Docker, pnpm, zip, git, and a checkout of the Langfuse repository. The identity running the script needs s3:PutObject on the artifact bucket, lambda:CreateMicrovmImage, ListMicrovmImages, GetMicrovmImage, UpdateMicrovmImage, and iam:PassRole on the build role. On success, the script prints IMAGE_ARN, which you use as LANGFUSE_IN_APP_AGENT_SANDBOX_AWS_LAMBDA_MICROVM_IMAGE_IDENTIFIER.

```bash
export AWS_PROFILE=<profile>
export AWS_REGION=<region>
export S3_BUCKET=<artifact-bucket>
export MICROVM_IMAGE_NAME=langfuse-in-app-agent-sandbox
export LAMBDA_MICROVM_BUILD_ROLE_ARN=arn:aws:iam::<account-id>:role/<build-role>
export BASE_IMAGE_ARN=arn:aws:lambda:<region>:aws:microvm-image:al2023-1
export BASE_IMAGE_VERSION=0

bash packages/in-app-agent-sandbox-runtime/build-microvm-image.sh
```

--------------------------------

### Stop Docker Compose containers

Source: https://langfuse.com/self-hosting/deployment/docker-compose

Stops all containers started by docker-compose. Add the -v flag to also remove the volumes.

```bash
docker compose down
```

--------------------------------

### Configure .env for database connection

Source: https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v1-to-v2

Edit the .env file to connect to your database from your machine. Replace the DATABASE_URL with your actual connection string.

```env
NODE_ENV=production

# Replace with your database connection string
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
```

--------------------------------

### GET /api/public/health

Source: https://langfuse.com/self-hosting/configuration/health-readiness-endpoints

Health check endpoint for the web container. Verifies the API is running and optionally checks database connectivity.

```APIDOC
## [GET] /api/public/health

### Description
Checks if the web service is healthy. By default, it only verifies that the API is running and does not validate database connectivity. Optionally, you can include database connectivity in the check.

### Method
GET

### Endpoint
/api/public/health

### Parameters
#### Query Parameters
- **failIfDatabaseUnavailable** (boolean) - Optional - When set to `true`, the health check also validates database connectivity.

### Request Example
```
curl http://localhost:3000/api/public/health
```

### Response
#### Success Response (200)
- API is functioning normally (and database is reachable if parameter is used)

#### Error Response (503)
- API is not functioning or database is unreachable (when parameter is used)

```

--------------------------------

### Configure MinIO replication to cloud storage

Source: https://langfuse.com/self-hosting/configuration/backups

Sets up MinIO client aliases for local MinIO and an S3 backup target, then adds bucket replication from the local langfuse bucket to the remote backup bucket. Requires MinIO and AWS credentials.

```bash
# Configure MinIO client
mc alias set myminio http://localhost:9000 minio miniosecret
mc alias set s3backup https://s3.amazonaws.com ACCESS_KEY SECRET_KEY

# Set up bucket replication
mc replicate add myminio/langfuse --remote-bucket s3backup/langfuse-backup
```

--------------------------------

### Configure Google Cloud Storage Native Integration

Source: https://langfuse.com/self-hosting/infrastructure/blobstorage

Set these environment variables to connect Langfuse with a Google Cloud Storage bucket using the native integration. The credentials variable is optional and falls back to environment credentials. The universe domain defaults to googleapis.com and applies across all authentication methods.

```bash
LANGFUSE_USE_GOOGLE_CLOUD_STORAGE=true

LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse # Bucket name
LANGFUSE_GOOGLE_CLOUD_STORAGE_CREDENTIALS=<json-credentials OR path-to-credentials.json> # JSON key or path to JSON key file. Optional. Will fallback to environment credentials
LANGFUSE_S3_EVENT_UPLOAD_PREFIX=events/ # Optional prefix to store events within a subpath of the bucket
GOOGLE_CLOUD_UNIVERSE_DOMAIN=googleapis.com # Optional. Google Cloud universe domain. Defaults to `googleapis.com`
```

--------------------------------

### GET /api/health

Source: https://langfuse.com/self-hosting/configuration/health-readiness-endpoints

Health check endpoint for the worker container. Verifies the worker is running and can connect to the database. Optionally checks for event propagation staleness and queue consumption liveness.

```APIDOC
## [GET] /api/health

### Description
Checks if the worker service is healthy. Verifies that the worker is functioning normally and that the database connection is successful. Optionally, you can include checks for event propagation staleness and queue consumption liveness.

### Method
GET

### Endpoint
/api/health

### Parameters
#### Query Parameters
- **failIfEventPropagationStuck** (boolean) - Optional - When set to `true`, the health check fails if the event propagation job has not made progress for more than `LANGFUSE_EVENT_PROPAGATION_STUCK_THRESHOLD_MINUTES` (default 15). The response body includes diagnostics.
- **failIfQueueConsumptionStuck** (boolean) - Optional - When set to `true`, the health check fails if no queue processes jobs for more than `LANGFUSE_QUEUE_CONSUMPTION_STUCK_THRESHOLD_MINUTES` (default 60). The response body includes diagnostics.

### Request Example
```
curl http://localhost:3030/api/health
```

### Response
#### Success Response (200)
- Worker service is functioning normally and database connection is successful

#### Error Response (503)
- Worker service is not functioning or cannot connect to the database
- When `failIfEventPropagationStuck=true`: returns 503 if the event propagation job's last run started more than the threshold ago
- When `failIfQueueConsumptionStuck=true`: returns 503 if no queue processes jobs for more than the threshold

```

--------------------------------

### Configure OCI Object Storage Native Integration with Instance Principal

Source: https://langfuse.com/self-hosting/infrastructure/blobstorage

Set these environment variables to enable the native OCI Object Storage integration using instance principal authentication. This is recommended for production deployments on OCI Compute with IAM dynamic group policies. Do not set access key or secret access key variables when using native OCI auth methods.

```bash
LANGFUSE_USE_OCI_NATIVE_OBJECT_STORAGE=true
LANGFUSE_OCI_AUTH_TYPE=instance_principal

LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse-bucket
LANGFUSE_S3_EVENT_UPLOAD_REGION=us-chicago-1
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=https://objectstorage.us-chicago-1.oraclecloud.com
LANGFUSE_S3_EVENT_UPLOAD_PREFIX=events/
```

--------------------------------

### Verify SSL certificate is active

Source: https://langfuse.com/self-hosting/deployment/gcp

Shows the expected output once the certificate becomes active. The ingress controller should then pick it up and present a valid TLS certificate.

```bash
$ gcloud compute ssl-certificates list
NAME      TYPE     CREATION_TIMESTAMP             EXPIRE_TIME                    REGION  MANAGED_STATUS
langfuse  MANAGED  2025-04-06T03:41:54.791-07:00  2025-07-05T03:41:56.000-07:00          ACTIVE
    <hostname>: ACTIVE

```

--------------------------------

### Build MicroVM image for agent sandbox

Source: https://langfuse.com/self-hosting/deployment/aws

Builds the Lambda MicroVM image for the agent sandbox. Requires a Langfuse checkout at the same version you deploy, Docker, and pnpm. The identity running the script needs s3:PutObject on the artifact bucket, lambda:CreateMicrovmImage / ListMicrovmImages / GetMicrovmImage / UpdateMicrovmImage, and iam:PassRole on the build role; without iam:PassRole, CreateMicrovmImage returns AccessDeniedException.

```bash
export AWS_PROFILE=<profile>
terraform output -json agent_sandbox_build_env \
  | jq -r 'to_entries[] | "export \(.key)=\(.value)"' > .env && source .env

bash packages/in-app-agent-sandbox-runtime/build-microvm-image.sh

```

--------------------------------

### Create langfuse bucket with AWS CLI

Source: https://langfuse.com/self-hosting/infrastructure/blobstorage

Creates a bucket named 'langfuse' using the AWS CLI against the local SeaweedFS S3 gateway. Uses the credentials from the s3.json file.

```bash
AWS_ACCESS_KEY_ID=seaweedfs AWS_SECRET_ACCESS_KEY=seaweedfssecret \
  aws --endpoint-url http://localhost:8333 --region us-east-1 s3 mb s3://langfuse
```

--------------------------------

### Create VolumeSnapshot for ClickHouse replica

Source: https://langfuse.com/self-hosting/configuration/backups

Creates a VolumeSnapshot for a ClickHouse replica in the langfuse namespace. Recommended for Kubernetes deployments; also snapshot the ClickHouse ZooKeeper volumes.

```bash
kubectl apply -f - <<EOF
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: clickhouse-backup-$(date +%Y%m%d-%H%M%S)
  namespace: langfuse
spec:
  source:
    persistentVolumeClaimName: data-langfuse-clickhouse-0
  volumeSnapshotClassName: csi-hostpath-snapclass
EOF
```

--------------------------------

### AWS ElastiCache Redis Cluster Configuration

Source: https://langfuse.com/self-hosting/deployment/infrastructure/cache

Example configuration for AWS ElastiCache Redis Cluster. Set REDIS_CLUSTER_ENABLED to true, provide the cluster endpoint in REDIS_CLUSTER_NODES, and enable TLS with the server name for secure connections.

```plaintext
REDIS_CLUSTER_ENABLED=true
REDIS_CLUSTER_NODES=clustercfg.my-redis-cluster.abc123.cache.amazonaws.com:6379
REDIS_AUTH=your-auth-token
REDIS_TLS_ENABLED=true
REDIS_TLS_SERVERNAME=clustercfg.my-redis-cluster.abc123.cache.amazonaws.com
```

--------------------------------

### Configure Langfuse for MinIO event uploads

Source: https://langfuse.com/self-hosting/infrastructure/blobstorage

Environment variables to connect Langfuse to a local MinIO instance. Requires a bucket named 'langfuse' created in the MinIO console. For MinIO versions before RELEASE.2025-02-03, set LANGFUSE_S3_DELETE_OBJECTS_CHECKSUM_ALGORITHM=MD5 to avoid MissingContentMD5 errors.

```bash
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse
LANGFUSE_S3_EVENT_UPLOAD_REGION=us-east-1
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=minio
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=miniosecret
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=http://minio:9000
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE=true
LANGFUSE_S3_EVENT_UPLOAD_PREFIX=events/
```

--------------------------------

### Environment variables for AWS SES transactional email

Source: https://langfuse.com/self-hosting/configuration/transactional-emails

Example environment variables for configuring transactional emails via AWS SES. Set SMTP_CONNECTION_URL to ses://<region> and EMAIL_FROM_ADDRESS to a verified identity in the same region. These variables are set on the application containers.

```bash
SMTP_CONNECTION_URL=ses://us-east-1
EMAIL_FROM_ADDRESS=no-reply@example.com
```

--------------------------------

### Enable Redis Sentinel Mode with Environment Variables

Source: https://langfuse.com/self-hosting/deployment/infrastructure/cache

Enable Redis Sentinel mode by setting these environment variables. REDIS_SENTINEL_NODES lists Sentinel addresses, REDIS_SENTINEL_MASTER_NAME must match the Sentinel master name, and REDIS_AUTH is required if Redis authentication is enabled. REDIS_SENTINEL_PASSWORD is optional and used only if Sentinel authentication is enabled.

```plaintext
REDIS_SENTINEL_ENABLED=true
REDIS_SENTINEL_NODES=sentinel1:26379,sentinel2:26379,sentinel3:26379
REDIS_SENTINEL_MASTER_NAME=mymaster
REDIS_AUTH=your-redis-password  # if authentication is enabled on Redis
REDIS_SENTINEL_PASSWORD=your-sentinel-password  # if authentication is enabled on Sentinels (optional)
```

--------------------------------

### Monitor PVC expansion

Source: https://langfuse.com/self-hosting/deployment/infrastructure/clickhouse

Monitor the PVC expansion progress and verify that pods recognize the new space.

```bash
# Watch PVC status
kubectl get pvc -w

# Check if pods recognize the new space
kubectl exec -it <clickhouse-pod-name> -- df -h /var/lib/clickhouse
```

--------------------------------

### FailedScheduling event for ClickHouse PVC not bound

Source: https://langfuse.com/self-hosting/deployment/aws

Shows the Kubernetes event that occurs when the Fargate scheduler rejects ClickHouse pods because the PVC is not yet bound to the pre-created EFS volume on first install. The PVCs bind moments later, but the scheduler does not re-evaluate rejected pods.

```text
Warning  FailedScheduling  fargate-scheduler  Pod not supported on Fargate: volumes not supported:
clickhouse-storage-volume not supported because: PVC clickhouse-storage-volume-langfuse-clickhouse-0-0-0 not bound

```

--------------------------------

### Sync SeaweedFS to external S3 storage using mc mirror

Source: https://langfuse.com/self-hosting/configuration/backups

Configures the MinIO client (mc) to alias the SeaweedFS endpoint and an external S3 bucket, then mirrors the langfuse bucket to a timestamped backup folder. Requires the SeaweedFS access key and secret key, plus AWS credentials.

```bash
# Configure source and target
mc alias set seaweedfs http://langfuse-s3-all-in-one.langfuse.svc.cluster.local:8333 $SEAWEEDFS_ACCESS_KEY $SEAWEEDFS_SECRET_KEY
mc alias set s3backup https://s3.amazonaws.com $AWS_ACCESS_KEY $AWS_SECRET_KEY

# Copy the bucket
mc mirror seaweedfs/langfuse s3backup/langfuse-backup/$(date +%Y%m%d)
```

--------------------------------

### Run Helm chart tests

Source: https://langfuse.com/self-hosting/deployment/kubernetes-helm

Runs the Helm chart tests for the langfuse chart with color output.

```bash
helm unittest charts/langfuse --color

```

--------------------------------

### Run Langfuse Web container

Source: https://langfuse.com/self-hosting/deployment/infrastructure/containers

Run the Langfuse Web container with required environment variables. The ENCRYPTION_KEY must be generated via 'openssl rand -hex 32'. The image is pulled from docker.langfuse.com.

```bash
docker run --name langfuse-web \
  -e DATABASE_URL=postgresql://hello \
  -e NEXTAUTH_URL=http://localhost:3000 \
  -e NEXTAUTH_SECRET=mysecret \
  -e SALT=mysalt \
  -e ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000 \ # generate via: openssl rand -hex 32
  -e CLICKHOUSE_URL=http://clickhouse:8123 \
  -e CLICKHOUSE_USER=clickhouse \
  -e CLICKHOUSE_PASSWORD=clickhouse \
  -e CLICKHOUSE_MIGRATION_URL=clickhouse://clickhouse:9000 \
  -e REDIS_HOST=localhost \
  -e REDIS_PORT=6379 \
  -e REDIS_AUTH=redis \
  -e LANGFUSE_S3_EVENT_UPLOAD_BUCKET=my-bucket \
  -e LANGFUSE_S3_EVENT_UPLOAD_REGION=us-east-1 \
  -e LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE \
  -e LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=bPxRfiCYEXAMPLEKEY \
  -p 3000:3000 \
  -a STDOUT \
docker.langfuse.com/langfuse/langfuse:4
```

--------------------------------

### Azure Managed Redis OSS clustering configuration

Source: https://langfuse.com/self-hosting/deployment/infrastructure/cache

Environment variables for Azure Managed Redis with OSS clustering. Set these on both Langfuse Web and Worker containers. Replace the example hostname and inject the access key via secret configuration. Leave REDIS_USERNAME unset and do not set REDIS_CONNECTION_STRING in cluster mode.

```plaintext
REDIS_CLUSTER_ENABLED=true
REDIS_CLUSTER_NODES=my-amr.eastus.redis.azure.net:10000
REDIS_AUTH=your-azure-managed-redis-access-key
REDIS_TLS_ENABLED=true
REDIS_TLS_SERVERNAME=my-amr.eastus.redis.azure.net
REDIS_TLS_REJECT_UNAUTHORIZED=true
REDIS_SENTINEL_ENABLED=false
```

--------------------------------

### Enable lightweight updates for Langfuse user

Source: https://langfuse.com/self-hosting/configuration/scaling

Creates a ClickHouse settings profile to enable lightweight updates for the Langfuse user, required before setting CLICKHOUSE_USE_LIGHTWEIGHT_UPDATE=true.

```sql
CREATE SETTINGS PROFILE langfuse_lightweight_update SETTINGS enable_lightweight_update = 1 TO 'user';
```

--------------------------------

### Pre-provision static IP for Langfuse GCP deployment

Source: https://langfuse.com/self-hosting/deployment/gcp

Steps to pre-provision a static IP address for the Langfuse GCP deployment. Enable the provision_static_ip flag, run a targeted apply to create the IP, retrieve it with terraform output, configure your DNS A-record, then run the full apply. Recommended for production when you need the IP before deploying the full stack.

```hcl
module "langfuse" {
  # ...
  provision_static_ip = true
}

```

```hcl
terraform apply -target=module.langfuse.google_compute_global_address.ingress

```

```hcl
terraform output ingress_ip

```

```hcl
terraform apply

```

--------------------------------

### Worker log showing background migration stuck on a single date

Source: https://langfuse.com/self-hosting/upgrade/background-migrations

Example worker container log lines showing a background migration repeatedly processing batches with the same oldest record timestamp (2025-06-03T08:34:15.231Z). This pattern indicates the migration is stuck on a single date, often due to many events created at the same time or an instance created before 2024-05-03 and rarely updated.

```text
langfuse-worker-1    | 2025-06-03T08:38:21.918Z info      [Background Migration] Acquired lock for background migration 20241024_1730_migrate_traces_from_pg_to_ch
langfuse-worker-1    | 2025-06-03T08:38:21.949Z info      Migrating traces from postgres to clickhouse with {}
langfuse-worker-1    | 2025-06-03T08:38:22.429Z info      Got 1000 records from Postgres in 475ms
langfuse-worker-1    | 2025-06-03T08:38:22.914Z info      Inserted 1000 traces into Clickhouse in 485ms
langfuse-worker-1    | 2025-06-03T08:38:22.919Z info      Processed batch in 965ms. Oldest record in batch: 2025-06-03T08:34:15.231Z
langfuse-worker-1    | 2025-06-03T08:38:23.391Z info      Got 1000 records from Postgres in 472ms
langfuse-worker-1    | 2025-06-03T08:38:23.811Z info      Inserted 1000 traces into Clickhouse in 420ms
langfuse-worker-1    | 2025-06-03T08:38:23.815Z info      Processed batch in 896ms. Oldest record in batch: 2025-06-03T08:34:15.231Z
langfuse-worker-1    | 2025-06-03T08:38:24.256Z info      Got 1000 records from Postgres in 441ms
langfuse-worker-1    | 2025-06-03T08:38:24.638Z info      Inserted 1000 traces into Clickhouse in 382ms
```

--------------------------------

### Set ADMIN_API_KEY environment variable

Source: https://langfuse.com/self-hosting/administration/instance-management-api

Configure the ADMIN_API_KEY environment variable to enable the Instance Management API. This is required for Enterprise Edition self-hosted instances.

```bash
ADMIN_API_KEY=your-admin-api-key
```
Tokens:
Raw