Langfuse

Stack

Langfuse v3 - open-source LLM engineering platform: tracing, evaluations, prompt management, and usage dashboards. This template mirrors the official self-host topology.

Configuration

Type

Compose

Platform

linux

Env vars

CLICKHOUSE_PASSWORD=''ENCRYPTION_KEY=''MINIO_ROOT_PASSWORD=''NEXTAUTH_SECRET=''NEXTAUTH_URL=http://localhost:5000REDIS_AUTH=# openssl rand -base64 24SALT=# openssl rand -base64 32

Source

Repo

Template by deployable-sh·Source

Report issue

Services

web

Configuration

Image

langfuse/langfuse:3

Ports

5000:5000

Env vars

DATABASE_URL=postgresql://langfuse:langfuse-local-only@db:5432/langfuseSALT=${SALT}ENCRYPTION_KEY=${ENCRYPTION_KEY}CLICKHOUSE_MIGRATION_URL=clickhouse://clickhouse:9000CLICKHOUSE_URL=http://clickhouse:8123CLICKHOUSE_USER=langfuseCLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD}CLICKHOUSE_CLUSTER_ENABLED=falseREDIS_HOST=cacheREDIS_PORT=6379REDIS_AUTH=${REDIS_AUTH}LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuseLANGFUSE_S3_EVENT_UPLOAD_REGION=autoLANGFUSE_S3_EVENT_UPLOAD_ENDPOINT=http://blob:9000LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID=langfuseLANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=${MINIO_ROOT_PASSWORD}LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE=trueLANGFUSE_S3_EVENT_UPLOAD_PREFIX=events/LANGFUSE_S3_MEDIA_UPLOAD_BUCKET=langfuseLANGFUSE_S3_MEDIA_UPLOAD_REGION=autoLANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT=http://blob:9000LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID=langfuseLANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY=${MINIO_ROOT_PASSWORD}LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE=trueLANGFUSE_S3_MEDIA_UPLOAD_PREFIX=media/TELEMETRY_ENABLED=falsePORT=5000HOSTNAME=0.0.0.0NEXTAUTH_URL=${NEXTAUTH_URL:-http://localhost:5000}NEXTAUTH_SECRET=${NEXTAUTH_SECRET}

Restart

unless-stopped

Image details

Pulls: 18.0M

User: langfuse

Created: Apr 12, 2024

Updated: 1 hour ago

Status: active

worker

Configuration

Image

langfuse/langfuse-worker:3

Env vars

Restart

unless-stopped

Image details

Pulls: 8.7M

User: langfuse

Created: Apr 12, 2024

Updated: 1 hour ago

Status: active

db

Configuration

Image

postgres:17

Volumes

/var/lib/postgresql/data : dbdata

Env vars

POSTGRES_USER=langfusePOSTGRES_PASSWORD=langfuse-local-onlyPOSTGRES_DB=langfuse

Restart

unless-stopped

Image details

Pulls: 11.6B

User: stackbrew

Created: Jun 05, 2014

Updated: 1 hour ago

Status: active

clickhouse

Configuration

Image

clickhouse/clickhouse-server:26.6.1.1193

Ports

9000:90008123:8123

Volumes

/var/lib/clickhouse : chdata

Env vars

CLICKHOUSE_DB=defaultCLICKHOUSE_USER=langfuseCLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD}

Restart

unless-stopped

Image details

Pulls: 304.5M

User: clickhouse

Created: Jul 09, 2020

Updated: 43 minutes ago

Status: active

cache

Configuration

Image

valkey/valkey:8

Command

sh,-c,exec valkey-server --requirepass "$REDIS_AUTH" --maxmemory-policy noeviction

Ports

6379:6379

Env vars

REDIS_AUTH=${REDIS_AUTH}

Restart

unless-stopped

Image details

Pulls: 302.3M

User: valkey

Created: Apr 02, 2024

Updated: 11 hours ago

Status: active

blob

Configuration

Image

minio/minio:RELEASE.2025-09-07T16-13-09Z

Command

server,/data,--address,:9000

Ports

9000:9000

Volumes

/data : blobdata

Env vars

MINIO_ROOT_USER=langfuseMINIO_ROOT_PASSWORD=${MINIO_ROOT_PASSWORD}

Restart

unless-stopped

Standalone Install

Select an install method, to see config/commands for deploying Langfuse

Installation method

Docker Run

Docker Compose

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

Ensure both Docker and Portainer are installed, and up-to-date
Log into your Portainer web UI
Under Settings → App Templates, paste the below URL
Head to Home → App Templates, and the list of apps will show up
Select Langfuse, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json

Show Me

Original stackfile

The compose file this template deploys, straight from its repo:

name: langfuse

x-langfuse-env: &langfuse-env
  DATABASE_URL: postgresql://langfuse:langfuse-local-only@db:5432/langfuse
  SALT: ${SALT}
  ENCRYPTION_KEY: ${ENCRYPTION_KEY}
  CLICKHOUSE_MIGRATION_URL: clickhouse://clickhouse:9000
  CLICKHOUSE_URL: http://clickhouse:8123
  CLICKHOUSE_USER: langfuse
  CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
  CLICKHOUSE_CLUSTER_ENABLED: "false"
  REDIS_HOST: cache
  REDIS_PORT: "6379"
  REDIS_AUTH: ${REDIS_AUTH}
  LANGFUSE_S3_EVENT_UPLOAD_BUCKET: langfuse
  LANGFUSE_S3_EVENT_UPLOAD_REGION: auto
  LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: http://blob:9000
  LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: langfuse
  LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD}
  LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: "true"
  LANGFUSE_S3_EVENT_UPLOAD_PREFIX: events/
  LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: langfuse
  LANGFUSE_S3_MEDIA_UPLOAD_REGION: auto
  LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: http://blob:9000
  LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: langfuse
  LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD}
  LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: "true"
  LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: media/
  TELEMETRY_ENABLED: "false"

services:
  web:
    image: langfuse/langfuse:3
    restart: unless-stopped
    environment:
      <<: *langfuse-env
      PORT: "5000"
      HOSTNAME: "0.0.0.0"
      NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:5000}
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET}
    ports:
      - "5000:5000"
    depends_on:
      - db
      - clickhouse
      - cache
      - blob

  worker:
    image: langfuse/langfuse-worker:3
    restart: unless-stopped
    environment: *langfuse-env
    depends_on:
      - db
      - clickhouse
      - cache
      - blob

  db:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_USER: langfuse
      POSTGRES_PASSWORD: langfuse-local-only
      POSTGRES_DB: langfuse
    volumes:
      - dbdata:/var/lib/postgresql/data

  clickhouse:
    image: clickhouse/clickhouse-server:26.6.1.1193
    restart: unless-stopped
    environment:
      CLICKHOUSE_DB: default
      CLICKHOUSE_USER: langfuse
      CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD}
    ports:
      - "9000:9000"
      - "8123:8123"
    volumes:
      - chdata:/var/lib/clickhouse

  cache:
    image: valkey/valkey:8
    command: ["sh", "-c", "exec valkey-server --requirepass \"$REDIS_AUTH\" --maxmemory-policy noeviction"]
    restart: unless-stopped
    environment:
      REDIS_AUTH: ${REDIS_AUTH}
    ports:
      - "6379:6379"

  blob:
    image: minio/minio:RELEASE.2025-09-07T16-13-09Z
    command: ["server", "/data", "--address", ":9000"]
    restart: unless-stopped
    environment:
      MINIO_ROOT_USER: langfuse
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    ports:
      - "9000:9000"
    volumes:
      - blobdata:/data

volumes:
  dbdata:
  chdata:
  blobdata:

Or deploy it directly from the source:

git clone https://github.com/deployable-sh/stacks
cd stacks
docker compose -f langfuse/compose.yaml up -d

More install options in our documentation.

Container Documentation

web Documentation

Langfuse Application Container | Open Source LLM Engineering Platform: Traces, Evals, Prompts & more

db Documentation

The PostgreSQL object-relational database system provides reliability and data integrity.

clickhouse Documentation

ClickHouse is an open-source column-oriented database management system.

cache Documentation

Valkey is a high-performance data structure server that primarily serves key/value workloads.

Serve Langfuse on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxy Domain App port Upstream

Proxying langfuse.example.com to http://clickhouse:9000

Add this to your Caddyfile

langfuse.example.com {
	reverse_proxy http://clickhouse:9000
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

In Portainer, go to Containers, click the container, then Logs. Or run docker logs <container>
Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:5000 failed: port is already allocated", something else on your server is using that port.

Find what's using it: sudo ss -tlnp | grep :5000
Stop the other service, or pick a different host port. In 5000:5000 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

Use your server's real IP: http://your-server-ip:5000. The 0.0.0.0 link Portainer shows isn't a real address.
Give it a minute after first deploy, langfuse can take a while to initialise.
Make sure your firewall allows the port, e.g. sudo ufw allow 5000

Image won't pull

Test the pull directly on the host: docker pull langfuse/langfuse:3

"manifest unknown" means the tag no longer exists.
"toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
"no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

Check the logs right after a restart, the last few lines before it died are the useful ones.
Get the exit code with docker inspect <container> --format '{{.State.ExitCode}}'
Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Stack won't deploy

Compose stacks fail fast on small mistakes, and Portainer shows the reason just above the editor.

YAML only accepts spaces for indentation, a single tab breaks the whole file.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

Bug within the app: Open an issue within langfuse's repo
Template not working: Open an issue on deployable-sh/stacks
This website not working: Open an issue on lissy93/portainer-templates

A Compose stack

Langfuse is a Compose stack, a set of containers (6 of them) defined in one file and brought up together by Portainer, then started and stopped as a single app.

The services

This stack is built from 6 containers that run side by side. Here's each one, with the image it runs and anything it waits for first:

web runs langfuse/langfuse:3, starts after db, clickhouse, cache, blob
worker runs langfuse/langfuse-worker:3, starts after db, clickhouse, cache, blob
db runs postgres:17
clickhouse runs clickhouse/clickhouse-server:26.6.1.1193
cache runs valkey/valkey:8
blob runs minio/minio:RELEASE.2025-09-07T16-13-09Z

Ports

A port is the door the app answers on. A mapping like 5000:5000 means it's reachable on port 5000 of your server, where the left number is yours to change and the right one belongs to the app. Once it's running, open http://your-server-ip:9000 in a browser. It opens:

5000:5000
9000:9000, likely the web interface
8123:8123, likely the web interface
6379:6379
9000:9000, likely the web interface

Volumes

A volume is where Langfuse keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:

/var/lib/postgresql/data kept in the dbdata volume Docker manages
/var/lib/clickhouse kept in the chdata volume Docker manages
/data kept in the blobdata volume Docker manages

Environment variables

Environment variables are the settings you hand over when you deploy, things like a password or a timezone. Langfuse takes 36 of them, all with defaults you can leave alone or tweak:

DATABASE_URL, defaults to postgresql://langfuse:langfuse-local-only@db:5432/langfuse
SALT, pulled from your own environment
ENCRYPTION_KEY, pulled from your own environment
CLICKHOUSE_MIGRATION_URL, defaults to clickhouse://clickhouse:9000
CLICKHOUSE_URL, defaults to http://clickhouse:8123
CLICKHOUSE_USER, defaults to langfuse
CLICKHOUSE_PASSWORD, pulled from your own environment
CLICKHOUSE_CLUSTER_ENABLED, defaults to false
REDIS_HOST, defaults to cache
REDIS_PORT, defaults to 6379
REDIS_AUTH, pulled from your own environment
LANGFUSE_S3_EVENT_UPLOAD_BUCKET, defaults to langfuse
LANGFUSE_S3_EVENT_UPLOAD_REGION, defaults to auto
LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT, defaults to http://blob:9000
LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID, defaults to langfuse
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, pulled from your own environment
LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE, defaults to true
LANGFUSE_S3_EVENT_UPLOAD_PREFIX, defaults to events/
LANGFUSE_S3_MEDIA_UPLOAD_BUCKET, defaults to langfuse
LANGFUSE_S3_MEDIA_UPLOAD_REGION, defaults to auto
LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT, defaults to http://blob:9000
LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID, defaults to langfuse
LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY, pulled from your own environment
LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE, defaults to true
LANGFUSE_S3_MEDIA_UPLOAD_PREFIX, defaults to media/
TELEMETRY_ENABLED, defaults to false
PORT, defaults to 5000
HOSTNAME, defaults to 0.0.0.0
NEXTAUTH_URL, defaults to http://localhost:5000
NEXTAUTH_SECRET, pulled from your own environment
POSTGRES_USER, defaults to langfuse
POSTGRES_PASSWORD, defaults to langfuse-local-only
POSTGRES_DB, defaults to langfuse
CLICKHOUSE_DB, defaults to default
MINIO_ROOT_USER, defaults to langfuse
MINIO_ROOT_PASSWORD, pulled from your own environment

Restart policy

The restart policy here is unless-stopped, so Docker restarts Langfuse after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).

Networking

Portainer puts these services on one shared private network, so they can find each other by name (like web) while only the ports above are open to you.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set Langfuse up. Add the template list to Portainer once, then deploying Langfuse is a click rather than a wall of config.

Langfuse

Configuration

Services

web

Configuration

Image details

worker

Configuration

Image details

db

Configuration

Image details

clickhouse

Configuration

Image details

cache

Configuration

Image details

blob

Configuration

Standalone Install

Install on Portainer

Template Import URL

Container Documentation

web Documentation

db Documentation

clickhouse Documentation

cache Documentation

Proxy configurator

Troubleshooting

Check the logs first

Port already in use

Running but the page won't load

Image won't pull

"exec format error"

Container keeps restarting

Stack won't deploy

Raise an issue

Config glossary

A Compose stack

The services

Ports

Volumes

Environment variables

Restart policy

Networking

Platform

Portainer app templates

Similar apps