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:2

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
   pnpm 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.

   pnpm 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)

To host Langfuse on Google Cloud Run, you need to follow these steps using Google Cloud Build because Google Cloud Run doesn't support GitHub Container Registry:

1. First, mirror the latest release of Langfuse to your private GitHub repository. You can do this by using this link (opens in a new tab). Note: Make sure to mirror the production branch, the Langfuse main branch includes unreleased features and might not be stable.

2. Whenever there's a new tagged release, merge the latest commit on the Langfuse production branch into the production branch of your private GitHub repository.

3. Push the production branch to your private repository, which now contains the new tagged release. This action will automatically deploy Langfuse on Google Cloud Run.

Note: You can use the Slack RSS app to monitor the Langfuse release feed here (opens in a new tab).

Setup Project on Google Cloud Run

1. Open Google Cloud Run.

2. Click on Create Service.

3. Choose GitHub integration to deploy from a repository continuously. Then click on Set up with Cloud Build.

4. Authorize Google Cloud access to your GitHub and select the repository.

5. In the Build Configuration, change the branch to production (i.e. ^production$).

6. Select Build Type as Dockerfile and specify the source location as /web/Dockerfile.

7. Click on Save.

8. Now, Configure the service name and region according to your requirements.

9. Select authentication as 'Allow unauthenticated invocations', as Langfuse will have its own built-in Authentication that you can use.

10. Choose 'CPU Allocation and Pricing' as "CPU is only allocated during request processing" to scale down the instance to 0 when there are no requests.

11. Configure ingress control according to your needs. For most cases, 'All' should suffice.

12. Under "Container(s), Volumes, Networking & Security", specify container port as 3000. Then click the "Secrets & Variables" tab. Add the required environment variables: SALT, NEXTAUTH_URL, NEXTAUTH_SECRET, and DATABASE_URL, etc.

13. The NEXTAUTH_URL will be the URL of the deployed service, which you can update later when the service finishes building and gets deployed.

14. Now, set up the database. Note: Your Cloud Run service won't be assigned a static IP, so you can't whitelist the ingress IP in Cloud SQL or any other hosted databases. Instead, utilize the Google Cloud Proxy. Scroll down to "Cloud SQL connections" and enable access to the SQL instance hosting the database for Langfuse. After that, go to the "Secrets & Variables" section of the Container setup and add DATABASE_URL as an environment variable.

    Here's what the value should look like:

    postgresql://<user-name>:<password>@localhost/<db-name>/?host=/cloudsql/<google-cloud-project-id>:<region-id>:<sql-instance-id>&sslmode=none&pgbouncer=true

    Also, set DIRECT_URL for database migrations, without &pgbouncer=true, the value should look like this:

    postgresql://<user-name>:<password>@localhost/<db-name>/?host=/cloudsql/<google-cloud-project-id>:<region-id>:<sql-instance-id>&sslmode=none

15. Finally, you can finish deploying the application.

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.

You can deploy Langfuse to Azure via the Azure Developer CLI using this template: Azure-Samples/langfuse-on-azure (opens in a new tab).

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.