---
title: "Docker Compose Deployment (Self-Hosted)"
description: "Step-by-step guide to deploy and run Langfuse locally or on a VM using Docker Compose. The simplest way to self-host Langfuse with Docker."
label: "Version: v4"
sidebarTitle: "Local/VM (Docker Compose)"
---

# Docker Compose

This guide will walk you through deploying Langfuse locally or on a VM using Docker Compose.
We will use the [`docker-compose.yml`](https://github.com/langfuse/langfuse/blob/main/docker-compose.yml) file.
This is the simplest way to run Langfuse to give it a try.

If you use a cloud provider like AWS, GCP, or Azure, you will need permissions to deploy virtual machines.

For high-availability and high-throughput, we recommend using Kubernetes ([deployment guide](/self-hosting/deployment/kubernetes-helm)).
The docker compose setup lacks high-availability, scaling capabilities, and backup functionality.

  Coming from docker-compose v2? See our upgrade guide for [docker
  compose](/self-hosting/upgrade-guides/upgrade-v2-to-v3#docker-compose).

## Walkthrough

Watch this 2:15 minute walkthrough for a step-by-step guide on running Langfuse locally with Docker Compose.

<iframe
  width="100%"
  className="aspect-[15.94/9] rounded-lg border mt-6 w-full"
  src="https://www.youtube-nocookie.com/embed/we52x5-a_Ac?si=2rqAs0LNwqeq767W"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  referrerpolicy="strict-origin-when-cross-origin"
  allowFullScreen
></iframe>

## Get Started

<Tabs items={["Local", "VM"]}>

<Tab>

<Steps>

### Requirements

- git
- docker & docker compose -> use [Docker Desktop](https://www.docker.com/products/docker-desktop/) on Mac or Windows

### Clone Langfuse Repository

Get a copy of the latest Langfuse repository:

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

### Start the application

Update the secrets in the docker-compose.yml and then run the langfuse docker compose using:

```bash
docker compose up
```

Watch the containers being started and the logs flowing in.
After about 2-3 minutes, the langfuse-web-1 container should log "Ready".
At this point you can proceed to the next step.

### Done

And you are ready to go! Open `http://localhost:3000` in your browser to access the Langfuse UI.

</Steps>

</Tab>

<Tab>

<Steps>

### Start a new instance and SSH into it

Enter your cloud provider interface and navigate to the VM instance section.
This is EC2 on AWS, Compute Engine on GCP, and Virtual Machines on Azure.
Create a new instance.

We recommend that you use at least 4 cores and 16 GiB of memory, e.g. a t3.xlarge on AWS.
Assign a public IP address in case you want to send traces from external sources.
As observability data tends to be large in volume, choose a sufficient amount of storage, e.g. 100GiB.

The rest of this guide will assume that you have an Ubuntu OS running on your VM and are connected via SSH.

### Install Docker and Docker Compose

Install docker (see [official guide](https://docs.docker.com/engine/install/ubuntu/) as well). Setup Docker's apt repository:

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

Install Docker packages:

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

Verify installation:

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

### Clone Langfuse Repository

Get a copy of the latest Langfuse repository:

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

cd langfuse
```

### Update Secrets

We strongly recommend that you update the secrets in the docker-compose file.
All sensitive lines are marked with `# CHANGEME`.
Make sure to select long, random passwords for all secrets.

### Update network parameters (optional)

Only the langfuse-web container and minio must be accessible from outside the instance.
Therefore, we recommend to add a security group or firewall to your instance that restricts incoming traffic to port :3000 and :9090.

### Start the application

```bash
docker compose up
```

Watch the containers being started and the logs flowing in.
After about 2-3 minutes, the langfuse-web-1 container should log "Ready".
At this point you can proceed to the next step.

### Done

And you are ready to go! Open `http://<instance-ip>:3000` in your browser to access the Langfuse UI.

Depending on your configuration, you might need to open an SSH tunnel to your VM to access the IP. Please refer to your cloud provider's documentation for how to do this.

</Steps>

</Tab>

</Tabs>

## Features

Langfuse supports many configuration options and self-hosted features.
For more details, please refer to the [configuration guide](/self-hosting/configuration).

- [Authentication & SSO](/self-hosting/security/authentication-and-sso)
- [Automated Access Provisioning](/self-hosting/administration/automated-access-provisioning)
- [Caching](/self-hosting/configuration/caching)
- [Code evaluators](/self-hosting/configuration/code-evaluators)
- [Custom Base Path](/self-hosting/configuration/custom-base-path)
- [Encryption](/self-hosting/configuration/encryption)
- [Headless Initialization](/self-hosting/administration/headless-initialization)
- [Data Masking](/self-hosting/security/data-masking)
- [Networking](/self-hosting/security/networking)
- [Organization Creators (EE)](/self-hosting/administration/organization-creators)
- [Instance Management API (EE)](/self-hosting/administration/instance-management-api)
- [Health and Readiness Check](/self-hosting/configuration/health-readiness-endpoints)
- [Observability via OpenTelemetry](/self-hosting/configuration/observability)
- [Transactional Emails](/self-hosting/configuration/transactional-emails)
- [UI Customization (EE)](/self-hosting/administration/ui-customization)

## Scaling

Docker compose does not support horizontal scaling without an additional Load Balancer component.
We recommend to use one of the other deployment options if your load exceeds single-instance scale or requires high availability.
To add more throughput on a docker compose setup, you can usually use a larger virtual machine, i.e. scale vertically.

## Shutdown

You can stop the containers by hitting `Ctrl+C` in the terminal.
If you started docker-compose in the background (`-d` flag), you can stop all instance using:

```bash
docker compose down
```

Adding the `-v` flag will also remove the volumes.

Ensure to stop the VM instance in your cloud provider interface to avoid unnecessary costs.

## Troubleshooting

- Multimodal tracing is not working: This docker compose setup by default uses MinIO for blob storage which is not accessible from outside the Docker network for direct uploads. Please refer to the [blob storage guide](/self-hosting/deployment/infrastructure/blobstorage#minio-media-uploads) for more details on how to configure MinIO for media uploads.
- Make sure that the VM has enough disk space for accumulating traces.

## How to Upgrade

To upgrade Langfuse, you can stop the containers and run `docker compose up --pull always`.

For more details on upgrading, please refer to the [upgrade guide](/self-hosting/upgrade).

---

If you experience any issues when self-hosting Langfuse, please:

1. Check out [Troubleshooting & FAQ](/self-hosting/troubleshooting-and-faq) page.
2. Use [Ask AI](/ask-ai) to get instant answers to your questions.
3. Ask the maintainers on [GitHub Discussions](/gh-support).
4. Create a bug report or feature request on [GitHub](/issues).

  Enterprise-grade support is available when self-hosting Langfuse. Learn more on
  our [pricing page](/pricing-self-host).

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/self-hosting/deployment/docker-compose.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.