### 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 development. This is the initial setup for running the migration script.

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

cd langfuse

git checkout v2

pnpm i

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

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

### Verify Docker Installation (Bash)

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

Runs the 'hello-world' Docker image to verify that Docker is installed and running correctly.

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

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

### Install Docker and Docker Compose on Ubuntu (Bash)

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

Installs Docker and Docker Compose on an Ubuntu system by adding Docker's official GPG key and repository, then installing the necessary 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
```

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

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

### Helm Chart Valkey Configuration for Production

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

Example `values.yaml` overwrites for a minimum production setup using the Valkey Helm chart. Ensures queue jobs are handled correctly by setting `maxmemory-policy`.

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

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

### Start Local MinIO Container

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

Use this Docker command to start a local MinIO instance for development. Ensure to create a bucket named 'langfuse' in the MinIO console.

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

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

Installs the Langfuse Helm chart into the specified namespace. Ensure the namespace exists before running this command.

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

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

### Start Langfuse Application (Bash)

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

Starts the Langfuse application using Docker Compose after updating secrets in the docker-compose.yml file. Monitor logs for the 'Ready' message.

```bash
docker compose up
```

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

### Self-hosted Redis with Sentinel Example

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

Example environment variables for a self-hosted Redis instance using Sentinel. Verify Sentinel node accessibility and master name configuration.

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

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

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

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

### Docker Redis Container Setup

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

Command to run a Redis container using Docker. Includes password protection and `maxmemory-policy` setting. Not recommended for production due to lack of redundancy.

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

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

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

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

### Run ClickHouse Docker Container

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

Starts a ClickHouse server Docker container for development. Not recommended for production due to lack of redundancy. Ensure ports 8123, 9000, and 9009 are available.

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

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

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

```

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

### 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"
}
```
```

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

### 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"
}
```
```

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

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

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

### Self-hosted Redis Cluster Configuration

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

Example configuration for a self-hosted Redis cluster. Adjust IP addresses and ports as per your deployment.

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

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

### 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. This allows the migration script to connect to your database from your local machine.

```bash
NODE_ENV=production

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

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

### 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');
```

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

### Example AWS SES Configuration

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

Configure Langfuse to use AWS SES for sending transactional emails by setting the SMTP_CONNECTION_URL and EMAIL_FROM_ADDRESS environment variables.

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

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

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

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

### AWS ElastiCache Redis Cluster Configuration

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

Configuration example for connecting Langfuse to an AWS ElastiCache Redis cluster. Ensure TLS is enabled for secure connections.

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

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

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

```

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

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

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

### 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"
}
```
```

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

### Docker Compose for ClickHouse with S3 Disk

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

Docker Compose configuration to run ClickHouse with the S3 disk setup. Ensure the config.xml is correctly mounted as a read-only volume.

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

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

### ClickHouse Helm Chart Overrides for Production

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

Use these values.yaml overrides for a minimum production setup of ClickHouse with Langfuse. Ensure persistence.size is adequate and replicaCount is at least 3.

```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 disk.
  auth:
    username: default
    password: changeme
```

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

### Port-Forward to Langfuse UI

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

Establishes a local port-forward to the Langfuse UI service, allowing access via `http://localhost:<local-port>`. Replace `<local-port>` with your desired local port.

```bash
kubectl port-forward svc/langfuse-web -n langfuse <local-port>:<nodeport>
```

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

### Add and Update Helm Chart Repository

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

Adds the Langfuse Helm chart repository and updates the local repository cache. This is a prerequisite for installing or upgrading Langfuse using Helm.

```bash
helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm repo update
```

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

### Monitor PVC Expansion Progress

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

Monitor the PVC status during expansion and verify that pods recognize the new disk 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
```

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

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

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

### Configure Native Google Cloud Storage Integration

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

Set these environment variables to connect Langfuse with your Google Cloud Storage bucket using the native integration. Credentials can be provided as a JSON key, a path to a JSON key file, or via environment credentials.

```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
GOOGLE_CLOUD_UNIVERSE_DOMAIN=googleapis.com # Optional. Google Cloud universe domain. Defaults to `googleapis.com`
```