Como instalar o Langfuse em um VPS

Pré-requisitos

Use Ubuntu 22.04 ou 24.04 com SSH, um IP público, Docker e um domínio como langfuse.example.com. Os requisitos mínimos oficiais são 4 núcleos de CPU, 16 GB de RAM e 100 GB de disco. O Langfuse executa PostgreSQL, ClickHouse, Redis, MinIO e dois contêineres de aplicação (cerca de 6 contêineres no total). Reserve espaço extra em disco para rastreamentos, índices analíticos e armazenamento de objetos.

Aviso sobre fuso horário: PostgreSQL e ClickHouse devem usar o fuso horário UTC. Configurações diferentes de UTC geram resultados de consulta incorretos, um erro silencioso e confuso. Confira o fuso horário do servidor com timedatectl antes da implantação.

Você também precisa de um destino para backups, um gerador de senhas e estar ciente de que dados de observabilidade podem conter prompts e dados de entrada dos usuários. Defina uma política de retenção antes de enviar tráfego real.

Etapa 1, Conectar ao servidor

Prepare o servidor e um diretório acessível apenas pelo administrador:

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

Reserve as portas 80 e 443 para o proxy reverso. Não exponha as portas do banco de dados, do cache ou do armazenamento de objetos à internet.

Etapa 2, Instalar o Docker e o Docker Compose

Instale o Docker Engine e o plugin Compose seguindo as instruções oficiais do Docker para Ubuntu:

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

Confirme que há espaço livre suficiente no servidor antes de baixar a pilha mantida. Fixe as tags das imagens depois de testar uma versão.

Etapa 3, Executar a pilha mantida do Langfuse

O Langfuse publica uma implantação Compose para hospedagem própria na documentação oficial e no repositório do código-fonte. Use os arquivos de implantação atuais, em vez de criar um arquivo Compose de três linhas que omita o armazenamento analítico ou as migrações. Coloque os arquivos em /opt/langfuse e siga a estrutura de diretórios da versão.

Crie o arquivo de ambiente com valores recém-gerados. Todas as variáveis necessárias estão listadas abaixo:

Variáveis de ambiente obrigatórias

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

Variável	Descrição	Como gerar
NEXTAUTH_SECRET	Obrigatória, usada para criptografar sessões do NextAuth	openssl rand -base64 32
SALT	Obrigatória, gera salt para chaves de API com hash	openssl rand -hex 16
ENCRYPTION_KEY	Obrigatória, exatamente 64 caracteres hexadecimais (256 bits)	openssl rand -hex 32
CLICKHOUSE_URL	Endereço HTTP do ClickHouse (rede interna do Docker)	http://clickhouse:8123
CLICKHOUSE_MIGRATION_URL	URL do ClickHouse para migrações (pode ser igual à anterior)	http://clickhouse:8123
CLICKHOUSE_CLUSTER_ENABLED	Defina como false para implantações de nó único	false
REDIS_CONNECTION_STRING	Conexão Redis para filas e cache	redis://default:...@redis:6379

Use os nomes e formatos exatos da versão oficial. Não use os valores de exemplo da documentação em produção e nunca inclua .env no Git.

Aviso: A implantação com Docker Compose destina-se a testes e uso em pequena escala. Para produção, use o chart do Helm para Kubernetes ou os módulos Terraform do repositório oficial do Langfuse.

Valide e inicie o projeto fornecido:

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

Se a versão incluir um comando de migração separado, execute-o exatamente como documentado antes de aceitar tráfego. Inspecione separadamente os logs da interface web, dos processos em segundo plano e do banco de dados.

Etapa 4, Configurar o proxy reverso

Direcione langfuse.example.com para a porta privada local do serviço langfuse-web (porta 3000) no arquivo Compose fornecido. Se precisar acessar diretamente o MinIO para gerenciar objetos, direcione um subdomínio para a porta 9090 do MinIO. Use Caddy, Nginx ou o proxy da sua plataforma para encerrar o HTTPS e preservar os cabeçalhos encaminhados do nome de host e do protocolo.

Defina NEXTAUTH_URL como a URL HTTPS pública da sua instância (https://langfuse.example.com). Isso é necessário para que os retornos de autenticação funcionem corretamente.

Mantenha os serviços de ingestão, banco de dados e armazenamento em redes privadas. Abra as portas 80 e 443 no firewall e teste o certificado. Confirme que cargas grandes de rastreamentos e solicitações demoradas não são rejeitadas por limites muito baixos de tamanho do corpo ou tempo limite no proxy.

Etapa 5, Primeiro acesso e configuração inicial

Abra o nome de host HTTPS, crie a primeira organização e gere um par de chaves de projeto. Use a chave pública onde o SDK exigir, mas mantenha a chave secreta na configuração do servidor. Envie um rastreamento de teste, adicione uma versão de prompt e confira se o rastreamento e os metadados aparecem no painel.

Decida quais campos podem conter informações pessoais ou confidenciais. Mascare ou omita os valores sensíveis na camada de instrumentação, em vez de confiar apenas nas permissões do painel.

Manutenção

Faça backup de todos os componentes persistentes listados na implantação atual, incluindo o armazenamento analítico e os segredos de criptografia. Defina limites de retenção e monitore o crescimento do disco. Atualize durante uma janela de manutenção, leia as notas de migração e mantenha um plano de reversão testado.

Quando a ingestão falhar, inspecione os logs de acesso do proxy, o serviço web, os processos em segundo plano e a camada de persistência, nessa ordem. Não exclua dados analíticos para resolver um problema de autenticação ou DNS.