Self-host (docker)

Self-Hosting Guide

Docker Image (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 (opens in a new tab).

Looking for a managed solution? Consider Langfuse Cloud (opens in a new tab) maintained by the Langfuse team.

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 \

We follow semantic versioning for Langfuse releases, i.e. breaking changes are only introduced in a new major version.

  • We recommend automated updates within a major version to benefit from the latest features, bug fixes, and security patches.
  • Subscribe to our mailing list to get notified about new releases and new major versions.

Configuring Environment Variables

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

VariableRequired / DefaultDescription
DATABASE_URLRequiredConnection string of your Postgres database. Instead of DATABASE_URL, you can also use DATABASE_HOST, DATABASE_USERNAME, DATABASE_PASSWORD and DATABASE_NAME.
DIRECT_URLDATABASE_URLConnection string of your Postgres database used for database migrations. Use this if you want to use a different user for migrations or use connection pooling on DATABASE_URL. For large deployments, configure the database user with long timeouts as migrations might need a while to complete.
SHADOW_DATABASE_URLIf your database user lacks the CREATE DATABASE permission, you must create a shadow database and configure the "SHADOW_DATABASE_URL". This is often the case if you use a Cloud database. Refer to the Prisma docs (opens in a new tab) for detailed instructions.
NEXTAUTH_URLRequiredURL of your deployment, e.g. or http://localhost:3000. Required for successful authentication via OAUTH.
NEXTAUTH_SECRETRequiredUsed to validate login session cookies, generate secret with at least 256 entropy using openssl rand -base64 32.
SALTRequiredUsed to salt hashed API keys, generate secret with at least 256 entropy using openssl rand -base64 32.
LANGFUSE_CSP_ENFORCE_HTTPSfalseSet to true to set CSP headers to only allow HTTPS connections.
PORT3000Port the server listens on.
HOSTNAMElocalhostIn some environments it needs to be set to to be accessible from outside the container (e.g. Google Cloud Run).
LANGFUSE_DEFAULT_PROJECT_IDConfigure optional default project for new users. When users create an account they will be automatically added to this project.
LANGFUSE_DEFAULT_PROJECT_ROLEVIEWERRole of the user in the default project (if set). Possible values are ADMIN, MEMBER, VIEWER. See project roles for details.
SMTP_CONNECTION_URLConfigure optional SMTP server connection for transactional email.
EMAIL_FROM_ADDRESSConfigure from address for transactional email. Required if SMTP_CONNECTION_URL is set.
Optional S3 configuration to enable large exports from the UI.
DB_EXPORT_PAGE_SIZE1000Optional page size for streaming exports to S3 to avoid memory issues. The page size can be adjusted if needed to optimize performance.
ENABLE_EVENT_LOGtrueSet to false to disable logging raw events to the events table in the database. This table is useful for debugging your instance but not required to run the application.



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

ProviderVariablesOAuth Redirect URL
Google (opens in a new tab)AUTH_GOOGLE_CLIENT_ID
GitHub (opens in a new tab)AUTH_GITHUB_CLIENT_ID
AzureAD (opens in a new tab)AUTH_AZURE_AD_CLIENT_ID
Okta (opens in a new tab)AUTH_OKTA_CLIENT_ID
Auth0 (opens in a new tab)AUTH_AUTH0_CLIENT_ID

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

AUTH_DOMAINS_WITH_SSO_ENFORCEMENTcomma-separated list of domains that are only allowed to sign in using SSO. Email/password sign in is disabled for these domains. E.g.,
AUTH_DISABLE_USERNAME_PASSWORDSet to true to disable email/password sign for all users. Only OAuth/SSO providers can be used to sign in.
AUTH_DISABLE_SIGNUPSet to true to disable sign up for new users. Only existing users can sign in.

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.


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

Langfuse releases

Watch the repository on GitHub to get notified about new releases

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
    # Navigate to the Langfuse directory
    cd langfuse
    # Install all dependencies
    pnpm i
    # Create an .env file
    cp .env
  2. Edit the .env to connect to your database from your machine:

    # Replace with your database connection string
  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

This section is work in progress and relies on community contributions. The Langfuse team/maintainers do not have the capacity to maintain or test this section. If you have successfully deployed Langfuse on a specific platform, consider contributing a guide either via a GitHub PR/Issue (opens in a new tab) or by reaching out to the maintainers. Please also let us know if one of these guides does not work anymore or if you have a better solution.


Deploy on 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: 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

  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
  _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}"]
  # Step to deploy the Docker image to Google Cloud Run
  - name: ""
    id: deploy-cloud-run
    entrypoint: bash
      - "-c"
      - |
        gcloud beta run deploy ${_SERVICE_NAME} --image \
           --region ${_REGION} \
           --project ${_PROJECT_ID} \
           --platform managed \
           --allow-unauthenticated \
           --memory 2Gi \
           --cpu 1 \
           --min-instances 0 \
           --max-instances 3 \
           --set-env-vars HOSTNAME= \
           --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, \

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:


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


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


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


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.


    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][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.


    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[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]


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


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.

Was this page useful?

Questions? We're here to help

Subscribe to updates