Langfuse v3 with AWS CDK

This project helps you build and deploy Langfuse v3 using AWS CDK.

Please also refer to the blog posts I've created about this project.

Language	Title
Japanese	AWS CDKを使ってLangfuseをセルフホストする
Japanese	Self hosting Langfuse に Cognito認証を追加する
English	Self-Hosting Langfuse v3 on AWS Using CDK
English	Adding Cognito Authentication to Self-Hosted Langfuse with AWS CDK

Architecture

• Deploys Langfuse Web/Worker Services and ClickHouse using ECS on Fargate
  • Enables service-to-service communication through ECS Service Connect
  • Utilizes EFS for ClickHouse storage
• Implements Aurora Serverless V2 for the relational database
• Uses ElastiCache Valkey for caching and queue management
• Employs S3 for blob storage
• Supports optional Cognito integration for authentication (Ref: Authentication and SSO)
• Offers CloudFront integration as an option
  • When CloudFront is enabled, the system utilizes a VPC Origin with an internal Application Load Balancer (ALB) for the web service. Additionally, WAFv2 is implemented to control access based on IP addresses.
  • When CloudFront is disabled, the system uses an internet-facing Application Load Balancer (ALB).

Architecture with CloudFront

Architecture intenet-facing ALB (without CloudFront)

Note

The following resources must be created in us-east-1 (N. Virginia) region due to service requirements:

• ACM certificate and WAF Web ACL for CloudFront.
• ACM certificate for Cognito custom domain (this is required because Cognito internally creates a CloudFront Distribution. For more information, see Using your own domain for managed login.)

Therefore, these resources are managed in a separate stack deployed in us-east-1.

Set Up Your Environment

Ensure you have Node.js, npm, and the AWS CDK CLI installed.

Usage

1. Set Configuration Properties

Please modify the following configuration files:

• /bin/app-config.ts: Environment parameters (including AWS Account ID, Region, and Domain).
• /lib/stack-config.ts: Parameters for AWS Resources and Langfuse Services.

2. Deploy

Run the following commands to deploy your stack:

npm ci
npx cdk deploy --context env=dev
npx cdk deploy --context env=prod --all # when CloudFront or Cognito Authentication is enabled

Important

If enableCognitoAuth is set to true, two stacks will be created：

• UsEast1Stack: ACM Certificate for Cognito on us-east-1.
• LangfuseWithAwsCdkStack: Resources for Langfuse services on your region.

In this case, you must use the --all flag to deploy all stacks.

Deployment takes approximately 20 minutes. Upon completion, you'll receive the Langfuse App URL in the output:

Outputs:
# omit

LangfuseWithAwsCdkStack-prod.LangfuseURL = https://langfuse.example.com

# omit
✨  Total time: 1040.53s

You can now start using your Langfuse application!

3. Clean Up

If you no longer need the resources, destroy the stack with:

npx cdk destroy --context env=dev
npx cdk destroy --context env=prod --all # when CloudFront or Cognito Authentication is enabled

Example: Testing the Langfuse Application via REST API

After building your application, you can perform operational checks using REST API calls. This section provides a step-by-step guide to testing your app.

Reference

For detailed API documentation, please refer to the API Reference.

Setting Up Environment Variables

Before making API calls, you need to set your hostname and API keys. Replace the placeholders with your actual Langfuse URL, Public Key, and Secret Key.

export LANGFUSE_SECRET_KEY="YOUR_SECRET_KEY"
export LANGFUSE_PUBLIC_KEY="YOUR_PUBLIC_KEY"
export LANGFUSE_HOST="YOUR_LANGFUSE_URL"

Performing a Health Check

You can perform a health check using the following curl command:

curl "$LANGFUSE_HOST/api/public/health" \
  --header "Authorization: $LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY"

Expected Result

A successful health check will return a response similar to this:

{
  "status": "OK",
  "version": "3.24.0"
}

Ingestion Test

To test the ingestion, use the following curl command. This example demonstrates how to send a trace creation request.

curl -X POST "$LANGFUSE_HOST/api/public/ingestion" \
  -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch": [
      {
        "type": "trace-create",
        "id": "'$(uuidgen)'",
        "timestamp": "'$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")'",
        "metadata": null,
        "body": {
          "id": "'$(uuidgen)'",
          "name": "test",
          "timestamp": "'$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")'",
          "public": false
        }
      }
    ],
    "metadata": null
  }'

Expected Result

A successful ingestion will return a response like this:

{
  "successes": [
    {
      "id": "523EFC5E-8BAC-485D-9CC3-C049B5F64FA4",
      "status": 201
    }
  ],
  "errors": []
}

It is acceptable as long as the result can be viewed from the frontend as well, as shown below.