# Langfuse Backup

> Docker volume backup and restore for self-hosted Langfuse. Use when: backing up a self-hosted Langfuse instance, restoring Langfuse after a crash or migration, setting up daily cron backups for Langfuse postgres/clickhouse/minio/redis volumes. Backs up postgres (traces, scores), minio (blobs), with optional clickhouse and redis. Includes restore script with validation and 14-day retention pruning.

- Skill: `dvcrn/langfuse-backup` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add dvcrn/langfuse-backup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/langfuse-backup/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/langfuse-backup

---


# langfuse-backup

Backup and restore Docker volumes for a self-hosted Langfuse instance.

## Scripts

- `scripts/backup_langfuse.sh` — back up postgres + minio volumes (primary data)
- `scripts/restore_langfuse.sh` — restore from a specific backup date

## Quick start

```bash
# Configure (env vars or edit the script defaults)
export LANGFUSE_BACKUP_DIR="$HOME/.langfuse-backups"
export LANGFUSE_COMPOSE_DIR="/path/to/langfuse"   # directory with docker-compose.yml
export LANGFUSE_DB_CONTAINER="langfuse-db-1"       # postgres container name
export LANGFUSE_MINIO_CONTAINER="langfuse-minio-1" # minio container name
export LANGFUSE_DB_NAME="langfuse"                  # postgres database name
export LANGFUSE_DB_USER="langfuse"                  # postgres user

# Run a backup
bash scripts/backup_langfuse.sh

# List available backups
ls "$LANGFUSE_BACKUP_DIR"

# Restore from a date
bash scripts/restore_langfuse.sh 2026-02-27
```

## Env vars

| Var                       | Default                              | Description                         |
|---------------------------|--------------------------------------|-------------------------------------|
| `LANGFUSE_BACKUP_DIR`     | `~/.langfuse-backups`                | Root backup directory               |
| `LANGFUSE_COMPOSE_DIR`    | `~/langfuse`                         | Docker Compose project directory    |
| `LANGFUSE_DB_CONTAINER`   | `langfuse-db-1`                      | Postgres container name             |
| `LANGFUSE_MINIO_CONTAINER`| `langfuse-minio-1`                   | MinIO container name                |
| `LANGFUSE_DB_NAME`        | `langfuse`                           | Postgres database name              |
| `LANGFUSE_DB_USER`        | `langfuse`                           | Postgres user                       |
| `LANGFUSE_RETENTION_DAYS` | `14`                                 | How many days of backups to keep    |

## What gets backed up

| Volume    | Backed up? | Notes                                       |
|-----------|------------|---------------------------------------------|
| Postgres  | ✅ Yes     | `pg_dump` → `.sql.gz` — traces, scores, evals |
| MinIO     | ✅ Yes     | `tar.gz` — uploaded blobs                  |
| ClickHouse| ⚠️ Optional| Large; many users skip (replayed from traces)|
| Redis     | ⚠️ Skip    | Cache only — safe to skip                  |

## Cron setup (macOS LaunchAgent)

```xml
<!-- ~/Library/LaunchAgents/com.yourname.langfuse-backup.plist -->
<key>StartCalendarInterval</key>
<dict>
  <key>Hour</key><integer>2</integer>
  <key>Minute</key><integer>0</integer>
</dict>
<key>ProgramArguments</key>
<array>
  <string>/bin/bash</string>
  <string>/path/to/scripts/backup_langfuse.sh</string>
</array>
<key>StandardOutPath</key>
<string>/tmp/langfuse-backup.log</string>
```

## Restore procedure

```bash
# 1. Stop Langfuse
cd $LANGFUSE_COMPOSE_DIR && docker compose down

# 2. Restore from backup
bash scripts/restore_langfuse.sh 2026-02-27

# 3. Start Langfuse
cd $LANGFUSE_COMPOSE_DIR && docker compose up -d
```