How to install Comet Opik on a VPS

The Docker Compose deployment described here is intended for local development and evaluation. For production use, deploy the official Kubernetes Helm chart instead.

Prerequisites

Use Ubuntu 22.04 or 24.04 with SSH, a public IP, a domain such as opik.example.com and enough CPU, RAM and disk for the current Opik release. Opik's stack includes ClickHouse which is memory-intensive. Plan for several GB of RAM — a 1 GB VPS will likely run out of memory. The stack is larger than a single application container and may include an analytical database, a frontend and background services.

Prepare external backup storage and a data policy for prompts, completions, user identifiers and evaluation results. Keep the server private until HTTPS and access control are ready.

Step 1, Connecting to your server

Patch the host and create a protected directory:

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

Allow only SSH, HTTP and HTTPS. Do not expose internal database or queue ports.

Step 2, Installing Docker and Docker Compose

Install Docker Engine and the Compose plugin from Docker's official Ubuntu instructions:

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

Check disk and memory before pulling images. Pin the exact Opik release once you have tested it.

Step 3, Running the official Opik stack

Clone the official Opik repository and use the ./opik.sh wrapper script instead of hand-rolling docker-compose commands. Put the complete deployment in /opt/opik; do not replace it with a frontend-only container because ingestion and analytics need the other services.

Create .env from the supplied example and replace all secrets:

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

Use the exact names required by the release. Do not commit the file or reuse documentation values. Pin OPIK_VERSION to a specific release tag instead of floating on latest.

Validate and start the supplied project:

./opik.sh
docker compose ps

Stop the stack with ./opik.sh --stop. Watch migrations and service health during the first startup. If the official project requires an initialization command, run it before creating a workspace.

If ClickHouse fails with No macro 'shard' in config, ensure you are using the latest docker-compose files from the repository.

Step 4, Configuring the reverse proxy

Route opik.example.com to the public web service port specified by the official Compose file. Terminate TLS with Caddy or Nginx, preserve forwarded headers and keep analytics databases private. Configure websocket support if the current UI needs live updates.

Restrict the dashboard with strong accounts or an upstream access layer. Test a trace ingestion request through HTTPS and confirm that large payloads are accepted without making proxy limits unlimited.

Step 5, First access and initial setup

Open the dashboard, create the first workspace and generate an SDK key pair. After first access, run pip install opik && opik configure --use_local to point the SDK at your self-hosted instance. Use the public value only where the SDK expects it and keep secret values in server-side configuration. Send a test trace with synthetic prompts, create an evaluation and verify the result.

Review redaction, retention and user permissions before connecting production models. Document the fields your instrumentation sends and who can read them.

Maintenance

Back up the databases, object storage and environment secrets required by the official stack. Data persists in ~/opik — include this directory in your backup strategy. Monitor disk growth and set retention before the first production load. Update after reading migration notes and verify ingestion and dashboards after every release.

When traces disappear, inspect the SDK request, proxy logs, ingestion service and analytical database in that order. Do not delete volumes to fix a key or hostname mismatch.