Cómo instalar Comet Opik en un VPS

El despliegue con Docker Compose descrito aqui esta pensado para desarrollo local y evaluacion. Para produccion, usa el chart oficial de Helm para Kubernetes.

Requisitos previos

Usa Ubuntu 22.04 o 24.04 con SSH, IP pública, un dominio como opik.example.com y CPU, RAM y disco suficientes para el release actual. El stack de Opik incluye ClickHouse, que consume mucha memoria. Prevé varios GB de RAM — un VPS de 1 GB probablemente se quedará sin memoria. El stack es mayor que un contenedor e incluye base analítica, frontend y servicios de background.

Prepara almacenamiento externo para backups y una política para prompts, completions, identificadores y evaluaciones. Mantén el servidor privado hasta tener HTTPS y control de acceso.

Paso 1, Conectarte a tu servidor

Actualiza el host y crea una carpeta protegida:

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

Permite solo SSH, HTTP y HTTPS. No expongas bases o colas internas.

Paso 2, Instalar Docker y Docker Compose

Instala Docker Engine y el plugin Compose según las instrucciones oficiales:

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

Revisa disco y memoria antes de descargar imágenes. Fija el release exacto después de probarlo.

Paso 3, Ejecutar el stack oficial de Opik

Clona el repositorio oficial de Opik y usa el script ./opik.sh en lugar de redactar comandos docker-compose manualmente. Coloca el despliegue completo en /opt/opik; no lo sustituyas por un frontend, porque la ingestión y analítica necesitan el resto de servicios.

Crea .env desde el ejemplo y sustituye todos los secretos:

OPIK_VERSION=
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

Usa los nombres exactos del release. No subas el archivo ni reutilices valores de documentación. Fija OPIK_VERSION a un tag de release concreto en lugar de flotar en latest.

Valida y arranca el proyecto:

./opik.sh
docker compose ps

Detén el stack con ./opik.sh --stop. Vigila migraciones y salud durante el primer arranque. Si el proyecto requiere un comando de inicialización, ejecútalo antes de crear un workspace.

Si ClickHouse falla con No macro 'shard' in config, asegúrate de usar los archivos docker-compose más recientes del repositorio.

Paso 4, Configurar el proxy inverso

Dirige opik.example.com al puerto web indicado por el Compose oficial. Termina TLS con Caddy o Nginx, conserva cabeceras y mantén privadas las bases analíticas. Configura websockets si la UI actual usa actualizaciones en vivo.

Protege el dashboard con cuentas fuertes o una capa de acceso upstream. Prueba ingestión por HTTPS y comprueba payloads grandes sin convertir los límites del proxy en ilimitados.

Paso 5, Primer acceso y configuración inicial

Abre el dashboard, crea el workspace y genera claves para el SDK. Tras el primer acceso, ejecuta pip install opik && opik configure --use_local para apuntar el SDK a tu instancia autoalojada. Usa la pública solo donde la necesite el SDK y conserva las secretas en servidor. Envía una traza con prompts sintéticos, crea una evaluación y comprueba el resultado.

Revisa redacción, retención y permisos antes de conectar modelos de producción. Documenta los campos que envía la instrumentación y quién puede leerlos.

Mantenimiento

Haz backup de bases, object storage y secretos requeridos. Los datos persisten en ~/opik — incluye este directorio en tu estrategia de backup. Monitoriza el disco y define retención antes del primer tráfico real. Actualiza tras leer migraciones y verifica ingestión y dashboards.

Si desaparecen trazas, revisa SDK, proxy, ingestión y base analítica, en ese orden. No borres volúmenes para corregir un problema de key o hostname.