Cómo instalar Langfuse en un VPS

Requisitos previos

Usa Ubuntu 22.04 o 24.04 con SSH, IP pública, Docker y un dominio como langfuse.example.com. Los mínimos oficiales son 4 núcleos CPU, 16 GB RAM, 100 GB disco. Langfuse ejecuta PostgreSQL, ClickHouse, Redis, MinIO y dos contenedores de aplicación (unos 6 contenedores en total). Deja disco adicional para trazas, índices y object storage.

Aviso de zona horaria: Tanto PostgreSQL como ClickHouse deben ejecutarse en la zona horaria UTC. Una configuración que no use UTC produce resultados incorrectos en las consultas, un fallo silencioso y difícil de diagnosticar. Verifica la zona horaria del servidor con timedatectl antes de desplegar.

Necesitas un destino de backup, un generador de contraseñas y una política para los prompts y entradas de usuarios que pueden aparecer en las trazas. Define la retención antes de enviar tráfico real.

Paso 1, Conectarte a tu servidor

Prepara el host y una carpeta solo para administradores:

ssh root@SERVER_IP
apt update && apt upgrade -y
apt install -y ca-certificates curl git
mkdir -p /opt/langfuse
cd /opt/langfuse
chmod 750 /opt/langfuse

Deja 80 y 443 para el reverse proxy. No publiques en internet los puertos de base de datos, cache u object storage.

Paso 2, Instalar Docker y Docker Compose

Instala Docker Engine y Compose según las instrucciones oficiales de Docker para Ubuntu:

docker --version
docker compose version
systemctl enable --now docker

Comprueba el espacio libre antes de descargar el stack mantenido. Fija los tags después de probar una versión.

Paso 3, Ejecutar el stack mantenido de Langfuse

Langfuse publica un despliegue Compose para self-hosting en su documentación y repositorio oficiales. Usa los archivos actuales, en lugar de crear un Compose corto que omita storage analítico o migraciones. Colócalos en /opt/langfuse y respeta la estructura de la versión.

Crea el archivo de entorno con valores nuevos. Todas las variables requeridas se enumeran a continuación:

Variables de entorno requeridas

DATABASE_URL=REPLACE_WITH_THE_DOCUMENTED_DATABASE_URL
NEXTAUTH_SECRET=REPLACE_WITH_A_LONG_RANDOM_VALUE
SALT=REPLACE_WITH_A_RANDOM_VALUE
ENCRYPTION_KEY=REPLACE_WITH_64_HEX_CHARS
CLICKHOUSE_URL=http://clickhouse:8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=REPLACE_WITH_A_RANDOM_VALUE
CLICKHOUSE_MIGRATION_URL=http://clickhouse:8123
CLICKHOUSE_CLUSTER_ENABLED=false
REDIS_CONNECTION_STRING=redis://default:REPLACE_WITH_A_RANDOM_VALUE@redis:6379
LANGFUSE_S3_EVENT_UPLOAD_BUCKET=langfuse-events

Variable	Descripción	Cómo generar
NEXTAUTH_SECRET	Obligatorio, cifrado de sesión NextAuth	openssl rand -base64 32
SALT	Obligatorio, sal para claves API hasheadas	openssl rand -hex 16
ENCRYPTION_KEY	Obligatorio, exactamente 64 caracteres hex (256 bits)	openssl rand -hex 32
CLICKHOUSE_URL	Endpoint HTTP de ClickHouse (red interna Docker)	http://clickhouse:8123
CLICKHOUSE_MIGRATION_URL	URL de ClickHouse para migraciones	http://clickhouse:8123
CLICKHOUSE_CLUSTER_ENABLED	false para despliegues de un solo nodo	false
REDIS_CONNECTION_STRING	Conexión Redis para colas y caché	redis://default:...@redis:6379

Usa los nombres y formatos exactos del release oficial. No uses valores de ejemplo en producción y nunca subas .env.

Aviso: El despliegue con Docker Compose está pensado para pruebas y uso a baja escala. Los despliegues de producción deben usar el Helm chart de Kubernetes o los módulos de Terraform del repositorio oficial de Langfuse.

Valida y arranca el proyecto suministrado:

docker compose config
docker compose pull
docker compose up -d
docker compose ps

Si la versión incluye un comando separado de migración, ejecútalo exactamente como indica la documentación. Revisa por separado los logs web, worker y base de datos.

Paso 4, Configurar el proxy inverso

Dirige langfuse.example.com al puerto localhost privado del servicio langfuse-web (puerto 3000) indicado por el Compose. Si necesitas acceso directo a MinIO para gestión de objetos, enruta un subdominio al puerto de MinIO (9090). Deja que Caddy, Nginx o el proxy de tu plataforma termine HTTPS y conserve las cabeceras reenviadas.

Establece NEXTAUTH_URL como la URL HTTPS pública de tu instancia (https://langfuse.example.com). Esto es necesario para que los callbacks de autenticación funcionen correctamente.

Mantén ingestión, base de datos y storage en redes privadas. Abre 80 y 443 y prueba el certificado. Confirma que payloads grandes y peticiones largas no se cortan por límites demasiado bajos del proxy.

Paso 5, Primer acceso y configuración inicial

Abre el hostname HTTPS, crea la organización y genera un par de claves para el proyecto. Usa la pública donde el SDK la necesite, pero guarda la secreta en configuración de servidor. Envía una traza de prueba, añade una versión de prompt y comprueba los metadatos en el panel.

Decide qué campos pueden contener información personal o confidencial. Enmascara o excluye esos valores en el punto de instrumentación, no solo mediante permisos del dashboard.

Mantenimiento

Haz backup de todos los componentes persistentes indicados por el despliegue, incluidos storage analítico y secretos de cifrado. Define retención y monitoriza el crecimiento del disco. Actualiza en una ventana de mantenimiento, lee las migraciones y conserva rollback probado.

Si falla la ingestión, revisa en orden los logs del proxy, web, workers y persistencia. No borres datos analíticos para resolver un problema de auth o DNS.