# Source: https://langfuse.com/self-hosting/v2/docker-compose.md

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

---
title: Docker Compose (self-hosted)
description: Step-by-step guide to run Langfuse on a VM using docker compose.
label: "Version: v3"
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.

<Callout type="info">
  Coming from docker-compose v2? See our upgrade guide for [docker
  compose](/self-hosting/upgrade-guides/upgrade-v2-to-v3#docker-compose).
</Callout>

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



import {
  Lock,
  Shield,
  Network,
  Users,
  Brush,
  Workflow,
  UserCog,
  Route,
  Mail,
  ServerCog,
  Activity,
  Eye,
  Zap,
} from "lucide-react";

import { Cards } from "nextra/components";

<Cards num={3}>
  <Cards.Card
    icon={<Lock size="24" />}
    title="Authentication & SSO"
    href="/self-hosting/security/authentication-and-sso"
    arrow
  />
  <Cards.Card
    icon={<UserCog size="24" />}
    title="Automated Access Provisioning"
    href="/self-hosting/administration/automated-access-provisioning"
    arrow
  />
  <Cards.Card
    icon={<Zap size="24" />}
    title="Caching"
    href="/self-hosting/configuration/caching"
    arrow
  />
  <Cards.Card
    icon={<Route size="24" />}
    title="Custom Base Path"
    href="/self-hosting/configuration/custom-base-path"
    arrow
  />
  <Cards.Card
    icon={<Shield size="24" />}
    title="Encryption"
    href="/self-hosting/configuration/encryption"
    arrow
  />
  <Cards.Card
    icon={<Workflow size="24" />}
    title="Headless Initialization"
    href="/self-hosting/administration/headless-initialization"
    arrow
  />
  <Cards.Card
    icon={<Network size="24" />}
    title="Networking"
    href="/self-hosting/security/networking"
    arrow
  />
  <Cards.Card
    icon={<Users size="24" />}
    title="Organization Creators (EE)"
    href="/self-hosting/administration/organization-creators"
    arrow
  />
  <Cards.Card
    icon={<ServerCog size="24" />}
    title="Instance Management API (EE)"
    href="/self-hosting/administration/instance-management-api"
    arrow
  />
  <Cards.Card
    icon={<Activity size="24" />}
    title="Health and Readiness Check"
    href="/self-hosting/configuration/health-readiness-endpoints"
    arrow
  />
  <Cards.Card
    icon={<Eye size="24" />}
    title="Observability via OpenTelemetry"
    href="/self-hosting/configuration/observability"
    arrow
  />
  <Cards.Card
    icon={<Mail size="24" />}
    title="Transactional Emails"
    href="/self-hosting/configuration/transactional-emails"
    arrow
  />
  <Cards.Card
    icon={<Brush size="24" />}
    title="UI Customization (EE)"
    href="/self-hosting/administration/ui-customization"
    arrow
  />
</Cards>



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