How to self-host Langfuse
Langfuse, deploy its open-source backend by cloning the langfuse/langfuse GitHub repository and running the backend services with Docker or Kubernetes. Then configure your Langfuse Python SDK or client to point to your self-hosted endpoint for AI observability and tracing.PREREQUISITES
Python 3.8+Docker or Kubernetes installedGit installedLangfuse API key or self-hosted credentialspip install langfuse
Setup
Start by cloning the official langfuse/langfuse GitHub repository, which contains the backend source code and deployment manifests. Install Docker or Kubernetes to run the backend services locally or in your cloud environment. Set environment variables for your Langfuse API key or self-hosted credentials.
git clone https://github.com/langfuse/langfuse.git
cd langfuse
# For local Docker deployment
./scripts/docker-up.sh
# Or deploy on Kubernetes
kubectl apply -f k8s/deployment.yaml
# Install Langfuse Python SDK
pip install langfuse Step by step
Run the Langfuse backend services using Docker Compose or Kubernetes. Then configure the Python Langfuse client to connect to your self-hosted backend by specifying the host URL and your API keys. Use the client to instrument your AI calls and capture observability data.
import os
from langfuse import Langfuse
# Set environment variables for your self-hosted Langfuse
os.environ["LANGFUSE_PUBLIC_KEY"] = "your-public-key"
os.environ["LANGFUSE_SECRET_KEY"] = "your-secret-key"
# Initialize Langfuse client with self-hosted endpoint
langfuse = Langfuse(
public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
secret_key=os.environ["LANGFUSE_SECRET_KEY"],
host="http://localhost:3000" # Replace with your backend URL
)
# Example: instrument a function call
@langfuse.observe()
def call_ai_model(prompt: str) -> str:
# Simulate AI call
return f"Response to: {prompt}"
result = call_ai_model("Hello Langfuse")
print("AI call result:", result) AI call result: Response to: Hello Langfuse
Common variations
You can run the Langfuse backend on different platforms such as bare metal, cloud VMs, or Kubernetes clusters. The Python SDK supports async instrumentation and integration with OpenAI or other AI clients. Customize the host parameter to point to your self-hosted URL. For advanced tracing, use the @observe() decorator or manual context management.
import asyncio
from langfuse import Langfuse
async def main():
langfuse = Langfuse(
public_key=os.environ["LANGFUSE_PUBLIC_KEY"],
secret_key=os.environ["LANGFUSE_SECRET_KEY"],
host="http://localhost:3000"
)
@langfuse.observe()
async def async_ai_call(prompt: str) -> str:
await asyncio.sleep(0.1) # Simulate async call
return f"Async response to: {prompt}"
result = await async_ai_call("Async Langfuse")
print("Async AI call result:", result)
asyncio.run(main()) Async AI call result: Async response to: Async Langfuse
Troubleshooting
- If the client cannot connect, verify your
hostURL and that the backend services are running. - Check Docker or Kubernetes logs for backend errors.
- Ensure your
LANGFUSE_PUBLIC_KEYandLANGFUSE_SECRET_KEYare correctly set and match the backend configuration. - For network issues, confirm firewall or proxy settings allow traffic to your Langfuse backend.
Key Takeaways
- Clone and deploy the Langfuse backend from GitHub using Docker or Kubernetes for self-hosting.
- Configure the Langfuse Python SDK with your self-hosted backend URL and API keys for observability.
- Use the @observe() decorator to instrument AI calls and capture detailed traces.
- Support for async instrumentation and multiple deployment environments enables flexible integration.
- Verify backend service status and environment variables to troubleshoot connection issues.