Important: If you're using or looking to use Opik or Comet enterprise version please reach out to [email protected] to gain access to the correct deployment documentation.

To run Opik locally we recommend using Docker Compose. It's easy to setup and allows you to get started in a couple of minutes but is not meant for production deployments. If you would like to run Opik in a production environment, we recommend using our Kubernetes Helm chart.

Before running the installation, make sure you have Docker and Docker Compose installed:

• Docker
• Docker Compose

Installation

To install Opik, you will need to clone the Opik repository and run the following commands:

Navigate to the opik folder

cd opik

Start the Opik platform

./opik.sh

Opik will now be available at [http://localhost:5173](http://localhost:5173)
</Tab>
<Tab value="Windows" title="Windows">

```powershell
# Clone the Opik repository
git clone https://github.com/comet-ml/opik.git

# Navigate to the opik folder
cd opik

# Start the Opik platform
powershell -ExecutionPolicy ByPass -c ".\opik.ps1"

Opik will now be available at http://localhost:5173

pip install opik

opik configure --use_local

or in python:

import opik

opik.configure(use_local=True)

This will create a ~/.opik.config file that will store the URL of your local Opik instance.

All the data logged to the Opik platform will be stored in the ~/opik directory, which means that you can start and stop the Opik platform without losing any data.

Stopping the Opik platform

You can stop the Opik server by running the following commands:

# Ensure you are running this command for the root of the Opik repository you cloned
./opik.sh --stop

# Ensure you are running this command for the root of the Opik repository you cloned
powershell -ExecutionPolicy ByPass -c ".\opik.ps1 --stop"

Note: You can safely stop the Opik platform without losing any data.

Upgrading and restarting the Opik platform

To upgrade or restart the Opik platform, you can simply run the opik script again:

# Ensure you are running this command for the root of the Opik repository you cloned
./opik.sh

# Ensure you are running this command for the root of the Opik repository you cloned
powershell -ExecutionPolicy ByPass -c ".\opik.ps1"

Advanced configuration - Docker compose

Using Docker Compose directly instead of using the opik.sh or opik.ps1 scripts provides you with some additional options.

Starting Opik with Docker Compose

Instead of using the opik.sh or opik.ps1 scripts, you can also run the docker compose command directly with service profiles:

# Navigate to the opik/deployment/docker-compose directory
cd opik/deployment/docker-compose

# Start full Opik platform (equivalent to ./opik.sh)
docker compose --profile opik up --detach

# Start only infrastructure services (equivalent to ./opik.sh --infra)
docker compose up --detach

# Start infrastructure + backend services (equivalent to ./opik.sh --backend)
docker compose --profile backend up --detach

Uninstalling Opik

To remove Opik, you can use the script or remove containers and volumes manually:

# Using the script (recommended)
./opik.sh --stop

# Or manually remove containers and volumes
cd deployment/docker-compose
docker compose --profile opik down --volumes

Running a specific version of Opik

You can run a specific version of Opik by setting the OPIK_VERSION environment variable:

OPIK_VERSION=latest

./opik.sh

Building the Opik platform from source

You can also build the Opik platform from source using the provided script:

# Clone the Opik repository
git clone https://github.com/comet-ml/opik.git

# Navigate to the opik directory
cd opik

# Build the Opik platform from source
./opik.sh --build

This will build the Frontend and Backend Docker images and start the Opik platform.

Troubleshooting

If you get this error when running docker compose

java.lang.Throwable: Code: 139. DB::Exception: No macro 'shard' in config while processing substitutions in '/clickhouse/tables/{shard}/opik/automation_rule_evaluator_logs' at '20' or macro is not supported here. (NO_ELEMENTS_IN_CONFIG) (version 24.3.6.48 (official build))

Please make sure you get the latest files from deployment/docker-compose folder