Como instalar o Comet Opik em um VPS

A implantação com Docker Compose descrita aqui foi criada para desenvolvimento local e avaliação. Para uso em produção, implante o chart oficial do Helm para Kubernetes.

Pré-requisitos

Use Ubuntu 22.04 ou 24.04 com SSH, um IP público, um domínio como opik.example.com e CPU, RAM e disco suficientes para a versão atual do Opik. A pilha do Opik inclui o ClickHouse, que consome muita memória. Planeje alguns GB de RAM: um VPS com 1 GB provavelmente ficará sem memória. A pilha é maior que um único contêiner de aplicação e pode incluir um banco de dados analítico, uma interface e serviços em segundo plano.

Prepare um destino externo para backups e uma política de dados para prompts, respostas geradas, identificadores de usuário e resultados de avaliação. Mantenha o servidor privado até que HTTPS e o controle de acesso estejam prontos.

Etapa 1, Conectar ao servidor

Atualize o sistema e crie um diretório protegido:

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

Permita apenas SSH, HTTP e HTTPS. Não exponha as portas internas do banco de dados ou da fila.

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

Verifique o disco e a memória antes de baixar as imagens. Fixe a versão exata do Opik depois de testá-la.

Etapa 3, Executar a pilha oficial do Opik

Clone o repositório oficial do Opik e use o script wrapper ./opik.sh em vez de montar comandos docker-compose manualmente. Coloque toda a implantação em /opt/opik; não a substitua por um contêiner apenas com a interface, pois a ingestão e a análise precisam dos outros serviços.

Crie o arquivo .env a partir do exemplo fornecido e substitua todos os segredos:

OPIK_VERSION=<tag>
OPIK_HOST=opik.example.com
OPIK_DATABASE_PASSWORD=REPLACE_WITH_A_RANDOM_VALUE
OPIK_SECRET_KEY=REPLACE_WITH_A_LONG_RANDOM_VALUE
OPIK_STORAGE_PASSWORD=REPLACE_WITH_A_RANDOM_VALUE

Use os nomes exatos exigidos pela versão. Não versione o arquivo nem reutilize os valores da documentação. Fixe OPIK_VERSION em uma tag de versão específica, em vez de usar latest sem fixá-la.

Valide e inicie o projeto fornecido:

./opik.sh
docker compose ps

Interrompa a pilha com ./opik.sh --stop. Acompanhe as migrações e a integridade dos serviços na primeira inicialização. Se o projeto oficial exigir um comando de inicialização, execute-o antes de criar um espaço de trabalho.

Se o ClickHouse falhar com No macro 'shard' in config, confirme que você está usando os arquivos docker-compose mais recentes do repositório.

Etapa 4, Configurar o proxy reverso

Direcione opik.example.com para a porta do serviço web público especificada no arquivo Compose oficial. Encerre o TLS com Caddy ou Nginx, preserve os cabeçalhos encaminhados e mantenha os bancos de dados analíticos privados. Configure o suporte a WebSocket se a interface atual precisar de atualizações em tempo real.

Restrinja o painel com contas robustas ou uma camada de controle de acesso anterior. Teste uma solicitação de ingestão de rastreamento por HTTPS e confirme que cargas grandes são aceitas sem deixar os limites do proxy ilimitados.

Etapa 5, Primeiro acesso e configuração inicial

Abra o painel, crie o primeiro espaço de trabalho e gere um par de chaves do SDK. Depois do primeiro acesso, execute pip install opik && opik configure --use_local para apontar o SDK para sua instância auto-hospedada. Use o valor público apenas nos locais em que o SDK o exigir e mantenha os valores secretos na configuração do servidor. Envie um rastreamento de teste com prompts sintéticos, crie uma avaliação e confira o resultado.

Revise as regras de mascaramento, retenção e permissões de usuário antes de conectar modelos de produção. Documente quais campos sua instrumentação envia e quem pode acessá-los.

Manutenção

Faça backup dos bancos de dados, do armazenamento de objetos e dos segredos de ambiente necessários para a pilha oficial. Os dados persistem em ~/opik: inclua esse diretório na estratégia de backup. Monitore o crescimento do disco e defina a retenção antes da primeira carga de produção. Atualize depois de ler as notas de migração e verifique a ingestão e os painéis após cada versão.

Quando os rastreamentos desaparecerem, inspecione a solicitação do SDK, os logs do proxy, o serviço de ingestão e o banco de dados analítico, nessa ordem. Não exclua volumes para corrigir uma incompatibilidade de chave ou nome de host.