Skip to content

Commit 62b4e13

Browse files
jacobecoxjacobecox
committed
updated readme
1 parent 5a455a4 commit 62b4e13

2 files changed

Lines changed: 187 additions & 1 deletion

File tree

‎langfuse/versions/1.0.0/Chart.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ appVersion: "3"
77

88
annotations:
99
created: "2026-05-29"
10-
lastModified: "2026-05-29"
10+
lastModified: "2026-06-02"
1111
category: "app"
1212
createsGvc: false
1313

‎langfuse/versions/1.0.0/README.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Langfuse
2+
3+
Langfuse is an open-source LLM observability and evaluation platform. This template deploys the full Langfuse stack on Control Plane, including:
4+
5+
- **Langfuse Web** — Next.js application serving the UI and public API (auto-scales 2–5 replicas)
6+
- **Langfuse Worker** — Background processor for trace ingestion, evaluations, and integrations
7+
- **PostgreSQL** — Stores users, projects, API keys, prompts, datasets, and eval configs
8+
- **Redis** — BullMQ ingestion queue and API key/prompt cache
9+
- **ClickHouse** — Columnar store for all traces, observations, and scores; powers dashboards
10+
- **Object Storage** — AWS S3 or GCS, shared between ClickHouse (data files) and Langfuse (raw event buffer and media uploads)
11+
12+
## Prerequisites
13+
14+
Object storage must be set up before deploying. Both ClickHouse and Langfuse use the same bucket with separate key prefixes (`clickhouse/`, `events/`, `media/`).
15+
16+
### AWS S3
17+
18+
For Langfuse and ClickHouse to access an S3 bucket, complete the following in your AWS account first:
19+
20+
1. Create your bucket. Set `objectStore.aws.bucket` to its name and `objectStore.aws.region` to its region.
21+
22+
2. If you do not have a Cloud Account set up, refer to the docs to [Create a Cloud Account](https://docs.controlplane.com/guides/create-cloud-account). Set `objectStore.aws.cloudAccountName` to its name.
23+
24+
3. Create a new IAM policy with the following JSON (replace `YOUR_BUCKET_NAME`) and set `objectStore.aws.policyName` to match:
25+
26+
```json
27+
{
28+
"Version": "2012-10-17",
29+
"Statement": [
30+
{
31+
"Effect": "Allow",
32+
"Action": [
33+
"s3:GetObject",
34+
"s3:PutObject",
35+
"s3:DeleteObject",
36+
"s3:ListBucket",
37+
"s3:GetObjectVersion",
38+
"s3:DeleteObjectVersion"
39+
],
40+
"Resource": [
41+
"arn:aws:s3:::YOUR_BUCKET_NAME",
42+
"arn:aws:s3:::YOUR_BUCKET_NAME/*"
43+
]
44+
}
45+
]
46+
}
47+
```
48+
49+
### GCS
50+
51+
For Langfuse and ClickHouse to access a GCS bucket, complete the following in your GCP account first:
52+
53+
**Note**: This template uses S3-compatible HMAC authentication for GCS. A Cloud Account is not required.
54+
55+
1. Create your bucket. Set `objectStore.gcp.bucket` to its name.
56+
57+
2. Navigate to **Settings > Interoperability** and click `Create a key for a service account`.
58+
59+
3. Click `Create new account` and name your service account.
60+
61+
4. Under **Permissions**, assign the role `Storage Object Admin` and click `Done`.
62+
63+
5. You will be provided a new HMAC key. Set `objectStore.gcp.accessKeyId` and `objectStore.gcp.secretAccessKey` with the values provided.
64+
65+
To configure using the CLI:
66+
67+
```bash
68+
gcloud config set project YOUR_PROJECT_ID
69+
70+
gcloud storage buckets create gs://YOUR_BUCKET_NAME
71+
72+
gcloud iam service-accounts create langfuse-storage
73+
74+
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
75+
--member="serviceAccount:langfuse-storage@$(gcloud config get-value project).iam.gserviceaccount.com" \
76+
--role="roles/storage.objectAdmin"
77+
78+
gsutil hmac create langfuse-storage@$(gcloud config get-value project).iam.gserviceaccount.com
79+
```
80+
81+
## Configuration
82+
83+
### Generating Required Secrets
84+
85+
The following auth values must be set in `values.yaml` before deploying. Each requires a specific format:
86+
87+
```bash
88+
# nextAuthSecret and salt — any base64 string
89+
openssl rand -base64 32
90+
91+
# encryptionKey — must be exactly 64 hex characters (32 bytes)
92+
openssl rand -hex 32
93+
```
94+
95+
Run each command separately and copy the output into the corresponding field:
96+
97+
```yaml
98+
langfuse:
99+
auth:
100+
nextAuthSecret: <output of openssl rand -base64 32>
101+
encryptionKey: <output of openssl rand -hex 32> # must be exactly 64 characters
102+
salt: <output of openssl rand -base64 32>
103+
```
104+
105+
> **Important**: `encryptionKey` encrypts LLM API keys and other sensitive project data stored in PostgreSQL. Use `openssl rand -hex 32` specifically — a base64 value will fail validation on startup.
106+
107+
### Passwords
108+
109+
Set strong passwords for each component before deploying:
110+
111+
```yaml
112+
postgres:
113+
config:
114+
password: CHANGE_ME
115+
116+
redis:
117+
auth:
118+
password: CHANGE_ME
119+
120+
clickhouse:
121+
config:
122+
password: CHANGE_ME
123+
```
124+
125+
### Firewall
126+
127+
By default, the Langfuse web UI and API are publicly accessible. To restrict access to specific IP ranges, update `langfuse.firewall.inboundAllowCIDR`:
128+
129+
```yaml
130+
langfuse:
131+
firewall:
132+
inboundAllowCIDR:
133+
- 203.0.113.0/24 # example: restrict to your office IP
134+
```
135+
136+
## Accessing Langfuse
137+
138+
Once deployed, the Langfuse web UI is accessible via the Control Plane external endpoint for the `RELEASE_NAME-langfuse-web` workload. Navigate to the endpoint in your browser to create an account and log in.
139+
140+
### Sending Traces via API
141+
142+
After creating a project and generating API keys (**Settings → API Keys**), send traces using the Langfuse public API:
143+
144+
```bash
145+
curl -X POST https://YOUR_LANGFUSE_ENDPOINT/api/public/traces \
146+
-H "Content-Type: application/json" \
147+
-u "YOUR_PUBLIC_KEY:YOUR_SECRET_KEY" \
148+
-d '{
149+
"name": "my-first-trace",
150+
"input": "Hello",
151+
"output": "Hello back"
152+
}'
153+
```
154+
155+
Or use the [Langfuse SDK](https://langfuse.com/docs/sdk) for Python, TypeScript, and other languages.
156+
157+
## LLM Connections (Playground and Evaluations)
158+
159+
The Langfuse playground and LLM-as-Judge evaluations require LLM API keys to be configured through the UI, stored encrypted in PostgreSQL using your `encryptionKey`.
160+
161+
To configure:
162+
1. In the Langfuse UI, go to **Settings → LLM API Keys** (for the playground) or **Evaluation → Set up default model** (for automated evals)
163+
2. Click **Add LLM Connection**, choose your provider (OpenAI, Anthropic, etc.), and enter your API key
164+
165+
## Backups
166+
167+
### PostgreSQL
168+
169+
PostgreSQL stores all critical configuration data: users, projects, API keys, prompts, datasets, and evaluation configs. It is the most important component to back up.
170+
171+
**Recommended**: Enable snapshot policies on the PostgreSQL volumeset via the Control Plane console. Volumeset snapshots capture the full disk state and restore quickly by re-attaching the snapshot as a new volume.
172+
173+
### ClickHouse
174+
175+
ClickHouse data files are stored directly in your object store (S3 or GCS) and are inherently durable — the volumeset only holds local metadata. A full ClickHouse restore can be performed by redeploying and pointing it at the existing bucket.
176+
177+
### Redis
178+
179+
Redis holds the transient BullMQ ingestion queue and short-lived cache. Backup is not required.
180+
181+
## Supported External Services
182+
183+
- [Langfuse Documentation](https://langfuse.com/docs)
184+
- [Langfuse SDK Reference](https://langfuse.com/docs/sdk)
185+
- [Control Plane Cloud Accounts](https://docs.controlplane.com/guides/create-cloud-account)
186+
- [Langfuse Self-Hosting Guide](https://langfuse.com/docs/deployment/self-host)

0 commit comments

Comments
 (0)