### Clone Langfuse Repository and Set Up Environment

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 for local configuration. This is the initial setup for running migration scripts.

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

cd langfuse

git checkout v2

pnpm i

cp .env.dev.example .env
```

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

### Start Langfuse with Docker Compose (Bash)

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

Start the Langfuse application using Docker Compose after cloning the repository and updating necessary configurations. Ensure Docker and Docker Compose are installed.

```bash
docker compose up
```

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

### Verify Docker Installation (Bash)

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

Verify that Docker is installed correctly by running the 'hello-world' container. This confirms the Docker daemon is running and accessible.

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

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

### Install Velero and Create Backup Schedule

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

Install Velero for comprehensive Kubernetes backups and create a daily backup schedule for the 'langfuse' namespace. Backups are retained for 720 hours.

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

# Create a backup schedule
velero schedule create langfuse-daily \
  --schedule="0 2 * * *" \
  --include-namespaces langfuse \
  --ttl 720h0m0s
```

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

### Install Docker and Dependencies (Bash)

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

Install Docker Engine, CLI, containerd.io, and Docker Compose plugin on an Ubuntu system. This is required for running Docker Compose.

```bash
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
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
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

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

### Start Local MinIO Container

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

Docker command to start a local MinIO instance for S3 compatibility. Access the console at http://localhost:9001.

```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 Langfuse Helm Chart

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

Installs the Langfuse Helm chart into the specified Kubernetes namespace. This command deploys Langfuse and its dependencies.

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

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

### Example ClickHouse Production Configuration for Langfuse

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

Use these values.yaml overwrites for a minimum production setup of the ClickHouse Helm chart. Ensure shards are set to 1 as Langfuse does not support multi-shard clusters. A minimum of 3 replicas is recommended for production.

```yaml
clickhouse:
  deploy: true
  shards: 1 # Fixed: Langfuse does not support multi-shard clusters
  replicaCount: 3
  resourcesPreset: large # or more
  persistence:
    size: 100Gi # Start with a large volume to prevent early resizing. Alternatively, consider a blob storage backed disked.
  auth:
    username: default
    password: changeme
```

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

### Docker Redis Standalone Example

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

Run Redis in a single Docker container for non-production environments. Configure authentication and memory policy.

```bash
docker run --name redis \
  -p 6379:6379 \
  redis --requirepass myredissecret --maxmemory-policy noeviction
```

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

### IdP-Initiated SSO Authentication Flow Example

Source: https://langfuse.com/self-hosting/authentication-and-sso

Use this URL format in your identity provider to enable IdP-initiated SSO. Replace placeholders with your Langfuse URL and provider name. Ensure your IdP is configured to use the 'Redirect to app to initiate login (OIDC Compliant)' option. This feature requires Langfuse version >=v3.126.0.

```bash
https://<YOUR_LANGFUSE_URL>/auth/sso-initiate?provider=<PROVIDER>
```

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

### Monitor Background Migration Logs

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

Example log output from the worker container showing the progress of a trace migration between Postgres and Clickhouse.

```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
```

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

### Start Langfuse v3 Deployment

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

Command to start the Langfuse v3 Docker Compose deployment using a modified compose file. Replace 'docker-compose.v3.yml' with your actual file name.

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

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

### Run ClickHouse Docker Container

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

Use this command to start a single ClickHouse Docker container for development. It is not recommended for production due to the lack of redundancy. Ensure necessary ports are exposed.

```bash
docker run --name clickhouse-server \
  -e CLICKHOUSE_DB=default \
  -e CLICKHOUSE_USER=clickhouse \
  -e CLICKHOUSE_PASSWORD=clickhouse \
  -d --ulimit nofile=262144:262144 \
  -p 8123:8123 \
  -p 9000:9000 \
  -p 9009:9009 \
  clickhouse/clickhouse-server
```

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

### Configure ADMIN_API_KEY

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

Set the ADMIN_API_KEY environment variable to authenticate with the Instance Management API. This key is specific to your self-hosted installation.

```bash
ADMIN_API_KEY=your-admin-api-key
```

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

### Docker Compose Volume Configuration

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

Example of volume configuration in a docker-compose.yml file. Ensure your database volume name is correctly identified for the upgrade process.

```yaml
volumes:
  database_data:
    driver: local
```

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

### MinIO Cloud Storage Replication Configuration

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

Configures MinIO client to replicate data to an S3-compatible cloud storage bucket. Requires MinIO client (`mc`) to be installed and configured.

```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

```

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

### GET /api/public/ready

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

Checks if the Langfuse web service is ready to receive traffic. This is particularly useful during graceful shutdowns.

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

### Description
Checks if the web application is ready to receive traffic. This endpoint is essential for managing graceful shutdowns and ensuring traffic is not sent to an unhealthy instance.

### Method
GET

### Endpoint
`/api/public/ready`

### Response
#### Success Response (200)
- **message** (string) - Indicates the application is ready to serve traffic.
#### Error Response (500)
- **message** (string) - Indicates the application has received a shutdown signal (SIGTERM or SIGINT) and should not receive new traffic.

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

### Response Example
```json
{
  "message": "Ready"
}
```
```

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

### Set Database Connection String

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

Replace the placeholder with your actual PostgreSQL database connection string. Ensure the credentials and database name are correct.

```bash
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
```

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

### Enable OCI Object Storage (Native)

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

Set `LANGFUSE_USE_OCI_NATIVE_OBJECT_STORAGE=true` to enable the native OCI Object Storage integration. Choose an authentication method via `LANGFUSE_OCI_AUTH_TYPE`.

```bash
LANGFUSE_USE_OCI_NATIVE_OBJECT_STORAGE=true
LANGFUSE_OCI_AUTH_TYPE=workload_identity # or instance_principal, resource_principal, oci_profile, session_token
```

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

### Check Web Container Readiness

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

Determine if the web application is ready to receive traffic, useful for managing graceful shutdowns.

```bash
curl http://localhost:3000/api/public/ready
```

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

### GET /api/health

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

Checks if the Langfuse worker service is healthy and can connect to the database.

```APIDOC
## GET /api/health

### Description
Checks if the worker service is functioning normally and has a successful database connection.

### Method
GET

### Endpoint
`/api/health`

### Response
#### Success Response (200)
- **message** (string) - Indicates the worker service is functioning normally and the database connection is successful.
#### Error Response (503)
- **message** (string) - Indicates the worker service is not functioning or cannot connect to the database.

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

### Response Example
```json
{
  "message": "OK"
}
```
```

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

### Build Langfuse Web Docker Image

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

Build the Langfuse web Docker image from source using the provided Dockerfile. Ensure you have cloned the repository and checked out the production branch.

```bash
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 .
```

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

### Configure Database Connection in .env

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

Edit the .env file to specify your production database connection string. Ensure NODE_ENV is set to 'production' for the migration script.

```bash
NODE_ENV=production

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
```

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

### Langfuse ClickHouse Connection Configuration

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

Configure these environment variables to connect Langfuse to your ClickHouse instance. Ensure the URLs and credentials match your ClickHouse setup.

```yaml
CLICKHOUSE_URL=http://localhost:8123
CLICKHOUSE_MIGRATION_URL=clickhouse://localhost:9000
CLICKHOUSE_USER=clickhouse
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_CLUSTER_ENABLED=false
```

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

### GET /api/public/health

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

Checks if the Langfuse web service is healthy. By default, it only verifies if the API is running. The `failIfDatabaseUnavailable` query parameter can be added to also check database connectivity.

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

### Description
Checks if the web service is healthy. By default, it only checks if the API is running and does not validate database connectivity. To include database connectivity, use the `failIfDatabaseUnavailable=true` query parameter.

### Method
GET

### Endpoint
`/api/public/health`

#### Query Parameters
- **failIfDatabaseUnavailable** (boolean) - Optional - If set to `true`, the health check will fail if the database is unavailable.

### Response
#### Success Response (200)
- **message** (string) - Indicates the API is functioning normally.
#### Error Response (503)
- **message** (string) - Indicates the API is not functioning or the database is unreachable (when `failIfDatabaseUnavailable` is used).

### Request Example
```bash
curl http://localhost:3000/api/public/health
curl http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true
```

### Response Example
```json
{
  "message": "OK"
}
```
```

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

### ClickHouse Native Backup and Restore

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

Use ClickHouse's built-in SQL commands to create backups to S3 and restore from S3. Replace placeholders with your actual S3 credentials and bucket path.

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

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

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

### Create MinIO Volume Snapshot

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

Use this Kubernetes manifest to create a VolumeSnapshot for the MinIO persistent volume. Ensure the `csi-hostpath-snapclass` is available in your cluster.

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

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

### Kubernetes Volume Snapshot for PostgreSQL

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

Creates a VolumeSnapshot of the PostgreSQL PersistentVolumeClaim in Kubernetes. Ensure the `csi-hostpath-snapclass` is configured.

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

```

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

### Expand ClickHouse PVC Size (Patch Method)

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

Patch all ClickHouse PVCs to increase their storage size. This requires the storage class to have `allowVolumeExpansion: true`. The new size is set to 200Gi in this example.

```bash
# Or patch all ClickHouse PVCs at once
kubectl patch pvc data-<chart-name>-clickhouse-0 -p '{"spec":{"resources":{"requests":{"storage":"200Gi"}}}}'
kubectl patch pvc data-<chart-name>-clickhouse-1 -p '{"spec":{"resources":{"requests":{"storage":"200Gi"}}}}'
kubectl patch pvc data-<chart-name>-clickhouse-2 -p '{"spec":{"resources":{"requests":{"storage":"200Gi"}}}}'
```

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

### Langfuse Redis Standalone Helm Configuration

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

Use these Helm chart overwrites for a minimal production setup with a standalone Redis instance. Ensure Redis is configured with `noeviction` policy for queue jobs.

```yaml
valkey:
  deploy: true
  architecture: standalone
  primary:
    extraFlags:
      - "--maxmemory-policy noeviction" # Necessary to handle queue jobs correctly
  auth:
    password: changeme
```

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

### Activate Enterprise License Key

Source: https://langfuse.com/self-hosting/license-key

Add this environment variable to both Langfuse containers to activate enterprise features.

```bash
LANGFUSE_EE_LICENSE_KEY=<your-license-key>
```

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

### Configure Google Cloud Storage (Native)

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

Set these environment variables to connect Langfuse with your Google Cloud Storage bucket. The `LANGFUSE_USE_GOOGLE_CLOUD_STORAGE` flag must be set to `true`. Credentials can be provided as a JSON string or a path to a JSON key file.

```yaml
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
```

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

### Build Langfuse Web Docker Image with Custom Base Path

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

Build the Langfuse web container image from source using Docker, specifying the NEXT_PUBLIC_BASE_PATH build argument. This is required when deploying Langfuse on a custom base path.

```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 .
```

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

### ClickHouse Replicated Table Configuration (Optional)

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

These XML snippets are optional and only needed if you use replicated tables in ClickHouse. The Helm chart should cover macros and default_replica_* configurations.

```xml
<!--
    Substitutions for parameters of replicated tables.
     Optional. If you don't use replicated tables, you could omit that.
     See https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/replication/#creating-replicated-tables
-->
<!--
    <macros>
        <shard>01</shard>
        <replica>example01-01-1</replica>
    </macros>
-->
<!--
    <default_replica_path>/clickhouse/tables/{database}/{table}</default_replica_path>
    <default_replica_name>{replica}</default_replica_name>
-->
```

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

### Configure .env for Database Connection

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

Edit the .env file to specify the NODE_ENV as production and configure your database connection details for local access during migration.

```dotenv
NODE_ENV=production

```

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

### Clone Langfuse Repository (Bash)

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

Clone the Langfuse repository to your local machine. This is a prerequisite for setting up the Docker Compose environment.

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

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

### Configure ClickHouse Cloud Connection for Langfuse

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

Set these environment variables to connect Langfuse to your ClickHouse Cloud instance. Ensure `CLICKHOUSE_MIGRATION_SSL` is set to `true` and that Langfuse Web can access your ClickHouse environment, reviewing IP whitelisting and Private Link access if necessary.

```yaml
CLICKHOUSE_URL=https://<identifier>.<region>.aws.clickhouse.cloud:8443
CLICKHOUSE_MIGRATION_URL=clickhouse://<identifier>.<region>.aws.clickhouse.cloud:9440
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=changeme
CLICKHOUSE_MIGRATION_SSL=true
```

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

### Configure Google Cloud Storage (Compatibility Mode)

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

Set these environment variables to connect Langfuse with your Google Cloud Storage bucket using S3 compatibility. Ensure you have generated an HMAC key with necessary permissions. Note that GCS may have issues with DeleteObject requests.

```yaml
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=my-bucket-name
LANGFUSE_S3_EVENT_UPLOAD_REGION=auto
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=<HMAC Access Key>
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=<HMAC Secret Key>
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=https://storage.googleapis.com
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE=true
LANGFUSE_S3_EVENT_UPLOAD_PREFIX=events/
```

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

### Configure Standalone Redis Connection

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

Use this format for connecting to a standalone Redis instance. Ensure your Langfuse container can reach the Redis endpoint.

```bash
REDIS_CONNECTION_STRING=redis://username:password@your-redis-endpoint:6379
```

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

### Docker Compose Deployment

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

Steps for deploying Langfuse v3 using Docker Compose, including considerations for migrating from v2.

```APIDOC
## Docker Compose Migration Steps

### 1. Note the volume name for the Postgres instance
Identify the Docker volume used by the v2 Postgres instance to ensure data persistence.

### 2. Create a copy of the docker-compose.yml from v3
Obtain the `docker-compose.yml` file for Langfuse v3 and make a copy for customization.

### 3. Stop the Langfuse v2 deployment (Beginning of downtime)
Gracefully shut down the existing Langfuse v2 containers to minimize data inconsistencies.

### 4. Start the Langfuse v3 deployment (End of downtime)
Launch the new Langfuse v3 containers using the prepared `docker-compose.yml` file.
```

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

### Check Web Container Health

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

Verify if the web service is running. Optionally include database connectivity checks by appending the query parameter.

```bash
curl http://localhost:3000/api/public/health
```

```bash
curl http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true
```