Self-Hosting Guide

(opens in a new tab)

Langfuse Server, which includes the API and Web UI, is open-source and can be self-hosted using Docker.

For a detailed component and architecture diagram, refer to CONTRIBUTING.md (opens in a new tab).

Prerequisites: Postgres Database

Langfuse requires a persistent Postgres database to store its state. You can use a managed service on AWS, Azure, or GCP, or host it yourself. Once the database is ready, keep the connection string handy.

Deploying the Application

Deploy the application container to your infrastructure. You can use managed services like AWS ECS, Azure Container Instances, or GCP Cloud Run, or host it yourself.

During the container startup, all database migrations will be applied automatically.

docker pull ghcr.io/langfuse/langfuse:latest

docker run --name langfuse \
-e DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<dbname> \
-e NEXTAUTH_URL=http://localhost:3000 \
-e NEXTAUTH_SECRET=mysecret \
-e SALT=mysalt \
-p 3000:3000 \
-a STDOUT \
ghcr.io/langfuse/langfuse:latest

Configuring Environment Variables

Langfuse can be configured using environment variables (.env.prod.example (opens in a new tab)). Some are mandatory as defined in the table below:

To enable OAuth/SSO provider sign-in for Langfuse, refer to the NextAuth.js docs (opens in a new tab).

Health Check Endpoint

Langfuse includes a health check endpoint at /api/public/health. This endpoint checks both API functionality and database connectivity.

Access the health check endpoint:

curl http://localhost:3000/api/public/health

The potential responses from the health check endpoint are:

• 200 OK: Both the API is functioning normally and a successful connection to the database was made.
• 503 Service Unavailable: Either the API is not functioning or it couldn't establish a connection to the database.

Applications and monitoring services can call this endpoint periodically for health updates.

Troubleshooting

If you encounter issues, ensure the following:

• NEXTAUTH_URL exactly matches the URL you're accessing Langfuse with. Pay attention to the protocol (http vs https) and the port (e.g., 3000 if you do not expose Langfuse on port 80).
• Set HOSTNAME to 0.0.0.0 if you cannot access Langfuse.
• SSO: Ensure that the OAuth provider is configured correctly. The return path needs to match the NEXTAUTH_URL, and the OAuth client needs to be configured with the correct callback URL.
• Encode special characters in DATABASE_URL, see this StackOverflow answer (opens in a new tab) for details.
• If you use the SDKs to connect with Langfuse, use auth_check() to verify that the connection works.

Updating the Application

Langfuse is released through tagged semver releases. Check GitHub releases (opens in a new tab) for information about the changes in each version.

How to update

To update the application:

1. Stop the container.
2. Pull the latest container.
3. Restart the application.

During container startup, any necessary database migrations will be applied automatically if the database schema has changed.

We recommend enabling automated updates to benefit from the latest features, bug fixes, and security patches.

Apply newly supported models to existing data in Langfuse

Langfuse includes a list of supported models for usage and cost tracking. If a Langfuse update includes support for new models, these will only be applied to newly ingested traces/generations.

Optionally, you can apply the new model definitions to existing data using the following steps. During the migration, the database remains available (non-blocking).

1. Clone the repository and create an .env file:

   # Clone the Langfuse repository
   git clone https://github.com/langfuse/langfuse.git
    
   # Navigate to the Langfuse directory
   cd langfuse
    
   # Install all dependencies
   npm i
    
   # Create an .env file
   cp .env.dev.example .env

2. Edit the .env to connect to your database from your machine:

   .env

   NODE_ENV=production
    
   # Replace with your database connection string
   DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres

3. Execute the migration. Depending on the size of your database, this might take a while.

   npm run models:migrate

4. Clean up: remove the .env file to avoid connecting to the production database from your local machine.

Platform-specific information

Railway

(opens in a new tab)

Google Cloud Platform (Cloud Run)

Cloud Run is an excellent method for deploying Langfuse easily and at scale. Cloud Run does not support deploying containers directly from the GitHub Container Registry (ghcr.io) used by Langfuse. To avoid the need to pull the container and push it to the Google registry, you can refer to this guide (opens in a new tab) or use Cloud Build. Note: you can use Google for SSO.

AWS (via Stitch)

(opens in a new tab)

With Stitch, you can deploy Langfuse to your own AWS account. The link above will take you to the Stitch installer where you can: select your cloud platform, select the infra you would like to use and enter your environment variables. You can find docs at https://stitch.tech/ (opens in a new tab).

AWS (Fargate)

Deploy Langfuse to AWS using the AWS Fargate service for serverless container deployment. You can find the deployment guide and Cloud Development Kit (CDK) scripts here: AI4Organization/langfuse-ecr-ecs-deployment-cdk (opens in a new tab).

Azure

Deploy Langfuse to Azure using the Azure Container Instances service for a flexible and low-maintenance container deployment. Note: you can use Azure AD for SSO.

Kubernetes

Not really a platform, but Kubernetes is a popular way to deploy Langfuse. You can find community-maintained templates at langfuse/langfuse-k8s (opens in a new tab).

FAQ

• Are there prebuilt ARM images available? No, currently we do not publish official ARM images. However, you can build your own ARM images using the Dockerfile in the Langfuse repository.
• Can I deploy multiple instances of Langfuse behind a load balancer? Yes, you can deploy multiple instances of Langfuse behind a load balancer. Make sure that your database is configured to handle sufficient multiple connections.

Support

If you experience any issues, please join us on Discord or contact the maintainers at support@langfuse.com.

For support with production deployments, the Langfuse team provides dedicated enterprise support. To learn more, reach out to enterprise@langfuse.com or schedule a demo.

Alternatively, you may consider using Langfuse Cloud, which is a fully managed version of Langfuse. You can find information about its security and privacy here.