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. At least version 12 is required.

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

docker run --name langfuse \
-e DATABASE_URL=postgresql://hello \
-e NEXTAUTH_URL=http://localhost:3000 \
-e NEXTAUTH_SECRET=mysecret \
-e SALT=mysalt \
-p 3000:3000 \
-a STDOUT \
langfuse/langfuse

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:

Authentication

SSO

To enable OAuth/SSO provider sign-in for Langfuse, add the following environment variables:

Use *_ALLOW_ACCOUNT_LINKING to allow merging accounts with the same email address. This is useful when users sign in with different providers or email/password but have the same email address. You need to be careful with this setting as it can lead to security issues if the emails are not verified.

Need another provider? Langfuse uses Auth.js, which integrates with many providers (opens in a new tab). Add a feature request on GitHub if you want us to add support for a specific provider.

Additional configuration

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.
• Make sure you are at least on Postgres 12.

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 & Cloud SQL)

The simplest way to deploy Langfuse on Google Cloud Platform is to use Cloud Run for the containerized application and Cloud SQL for the database.

Option 1: UI Deployment

Create Cloud SQL Instance:

1. Open Google Cloud SQL.
2. Click on Create Instance.
3. Choose PostgreSQL and configure the instance according to your requirements.
4. You'll need the following details:
   • default > user: postgres
   • default > database schema: public
   • setup > password: <password>
   • connection > connection name: <google-cloud-project-id>:<region-id>:<sql-instance-id>

Deploy on Cloud Run:

1. Open Google Cloud Run.

2. Click on Create Service.

3. Enter the following container image URL: docker.io/langfuse/langfuse:2. We use tag 2 to pin the major version.

4. Configure the service name and region according to your requirements.

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

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

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

8. "Container(s), Volumes, Networking & Security":

   • Specify container port as 3000.
   • On "Variables & Secrets" tab, add the required environment variables (see table above): SALT, NEXTAUTH_URL, NEXTAUTH_SECRET, and DATABASE_URL, etc.
     • To configure Cloud SQL, add the following:
       • DATABASE_URL as the connection string to the Cloud SQL instance. postgresql://<user-name>:<password>@localhost/<db-name>/?host=/cloudsql/<google-cloud-project-id>:<region-id>:<sql-instance-id>&sslmode=none&pgbouncer=true
       • 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
     • Set NEXTAUTH_URL to http://localhost:3000. This is a placeholder, we'll update it later.

9. Scroll all the way down to enable the Cloud SQL connections. Select the created Cloud SQL instance in the dropdown. Context: 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, we use the Google Cloud SQL Proxy.

10. Finally, you can finish deploying the application.

11. While the application is deployed for the first time, you can see how the database migrations are applied in the logs.

12. Once the application is up and running, you can find the Cloud Run service URL on top of the page. Now, choose "Edit and deploy new revision" to update the NEXTAUTH_URL environment variable to the Cloud Run service URL ending in .run.app.

13. Optionally, configure a custom domain for the Cloud Run service.

Option 2: Cloud Build

Google Cloud Build is GCP's continuous integration and continuous deployment (CI/CD) service that automates the building, testing, and deployment of your applications. To deploy Langfuse, you can specify your workflow in a cloudbuild.yaml file. Additionally, GCP's Secret Manager can be used to securely handle sensitive information like DATABASE_URL and NEXTAUTH_SECRET. Below is an example of how to set up a Cloud Build configuration:

# Deployment configuration for Langfuse on Google Cloud Run
substitutions:
  _SERVICE_NAME: langfuse
  _REGION: europe-west1 # Change to your desired region
  _PROJECT_ID: your-project-id # Change to your Google Cloud project ID
 
tags: ["${_PROJECT_ID}", "${_SERVICE_NAME}"]
 
steps:
  # Step to deploy the Docker image to Google Cloud Run
  - name: "gcr.io/cloud-builders/gcloud"
    id: deploy-cloud-run
    entrypoint: bash
    args:
      - "-c"
      - |
        gcloud beta run deploy ${_SERVICE_NAME} --image docker.io/langfuse/langfuse:2 \
           --region ${_REGION} \
           --project ${_PROJECT_ID} \
           --platform managed \
           --allow-unauthenticated \
           --memory 2Gi \
           --cpu 1 \
           --min-instances 0 \
           --max-instances 3 \
           --set-env-vars HOSTNAME=0.0.0.0 \
           --update-secrets AUTH_GOOGLE_CLIENT_ID=AUTH_GOOGLE_CLIENT_ID:latest, \
                            AUTH_GOOGLE_CLIENT_SECRET=AUTH_GOOGLE_CLIENT_SECRET:latest, \
                            SALT=SALT:latest, \
                            NEXTAUTH_URL=LANGFUSE_URL:latest, \
                            NEXTAUTH_SECRET=NEXTAUTH_SECRET:latest, \
                            DATABASE_URL=DATABASE_URL:latest, \
                            DIRECT_URL=DIRECT_URL:latest

You can submit this build using gcloud build submit (opens in a new tab) in your local console by issuing the below in the same folder as the cloudbuild.yaml file.

To submit this build, use the following command in your local console, in the directory containing the cloudbuild.yaml file:

gcloud builds submit .

For automatic rebuilds upon new commits, set up a Cloud Build Trigger (opens in a new tab) linked to your repository holding the cloudbuild.yaml file. This will redeploy Langfuse whenever changes are pushed to the repository.

Note on AlloyDB

AlloyDB (opens in a new tab) is a fully-managed postgres compatible database offered by Google Cloud Platform that is tuned for better performance for tasks such as analytical queries and in-database embeddings. It is recommend you use it within a Shared VPC (opens in a new tab) with your Cloud Run runtime, which will expose AlloyDB's private ip address to your application. If you are using it the DB connection string changes slightly:

# ALLOYDB_CONNECTION_STRING
postgresql://<USER>:<PASSWORD>@<ALLOY_DB_PRIVATE_IP>:5432/<ALLOY_DB_DATABASE>/?sslmode=none&pgbouncer=true

# ALLOYDB_DIRECT_URL
postgresql://<USER>:<PASSWORD>@<ALLOY_DB_PRIVATE_IP>:5432/<ALLOY_DB_DATABASE>/?sslmode=none

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

Heroku

To deploy this image on heroku you have to run through the steps in the following deployment guide:

1. Pull the docker image. This can be achieved by running the following command in your terminal:

   docker pull langfuse/langfuse:2

2. Get the ID of the pulled image

   Linux / MacOS:

   Running the following command should result in directly printing the image ID

   docker images | grep langfuse/langfuse | awk '[print $3]'

   Following this tutorial, you will always have to insert this image ID when [IMAGE_ID] is written.

   Windows:

   On windows you can print the full information of the pulled image using:

   docker images | findstr /S "langfuse/langfuse"

   This will result in something like:

   langfuse/langfuse                                           2          cec90c920468   28 hours ago    595MB

   Here you have to manually retrieve the image ID which in this case is cec90c920468. It should be located between the tag 2 and the created 28 hours ago in this example.

3. Prepare your terminal and docker image

   First of all, you will have to be logged in to heroku using

   heroku login

   If this is not working, please visit the heroku CLI setup (opens in a new tab).

   If you succeeded in logging in to heroku via the CLI, you can continue by following the next steps:

   Tag the docker image (Insert your image ID into the command). You will also have to insert the name of your heroku app/dyno into [HEROKU_APP_NAME]:

   docker tag [IMAGE_ID] registry.heroku.com/[HEROKU_APP_NAME]/web

4. Setup a database for your heroku app

   In the dashboard of your heroku app, add the Heroku Postgres-AddOn. This will add a PostgreSQL database to your application.

5. Set the environment variables

   For the minimum deployment in heroku, you will have to set the following environment variables (see table above). The DATABASE_URL is your database connection string starting with postgres:// in the configuration of your added PostgreSQL database.

   DATABASE_URL=
   NEXTAUTH_SECRET=
   NEXTAUTH_URL=
   SALT=

   Have a look at the other optional environment variables in the table above and set them if needed to configure your deployment.

6. Push to heroku container registry

   In this step you will push the docker image to the heroku container registry: (Insert the name of your heroku app/dyno)

   docker push registry.heroku.com/[HEROKU_APP_NAME]/web

7. Deploy the docker image from the heroku registry

   In the last step you will have to execute the following command to finally deploy the image. Again insert the name of your heroku app:

   heroku container:release web --app=[HEROKU_APP_NAME]

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 the number of connections.

Support

If you experience any issues, please join us on Discord or contact the maintainers at [email protected].

For support with production deployments, the Langfuse team provides dedicated enterprise support. To learn more, reach out to [email protected] 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.