Scripts

General guidelines

Scripts in this folder are meant to be run from the repository base folder. Example:

./scripts/generate_openapi.sh

Scripts list

generate_openapi.sh

Use this script to generate an updated OpenAPI specification file for the documentation application and the SDKs, and also to build the SDKs autogenerated code, for any supported language by Fern.

You require to install Fern to run this script.

See:

• https://buildwithfern.com/

start_openapi_server.sh

Use this script to start a local server with an updated OpenAPI specification file, to be able to test the specification quickly.

Open the server in your browser at http://localhost:3003/

See:

• https://github.com/Redocly/redoc
• https://docs.oracle.com/en/java/javase/23/docs/specs/man/jwebserver.html

sync-codex.sh

Synchronize .agents/rules/*.mdc into Codex-friendly markdown and generate a local AGENTS.override.md for Codex sessions.

Usage:

./scripts/sync-codex.sh .agents AGENTS.md AGENTS.override.md

This script is executed by make codex.

dev-runner.sh

Development environment runner script for local Opik development. This script manages Docker infrastructure, backend, and frontend services for development workflows.

Quick Start

# Full restart with rebuild (default)
./scripts/dev-runner.sh

# Or explicitly
./scripts/dev-runner.sh --restart

Available Commands

Standard Mode (Backend and Frontend as local processes):

BE-Only Mode (Backend as local process, Frontend in Docker):

Other Commands:

Multi-Worktree Support

The dev-runner.sh and opik.sh scripts support running multiple Opik development environments simultaneously from different git worktrees. Each worktree automatically gets isolated ports and Docker containers.

How It Works

1. Worktree Detection: The script identifies your worktree by its directory name
2. Port Offset Calculation: A deterministic offset (0-99) is calculated from an MD5 hash of your project path
3. Port Assignment: All service ports are offset from their base values
4. Docker Isolation: Each worktree gets a unique Docker Compose project name (opik-<worktree-id>)

Port Assignments

Manual Port Override

If you need to use a specific port offset (e.g., to avoid conflicts or use standard ports):

# Use standard ports (offset 0)
OPIK_PORT_OFFSET=0 ./scripts/dev-runner.sh --restart

# Use a specific offset
OPIK_PORT_OFFSET=10 ./scripts/dev-runner.sh --restart

Running Multiple Worktrees

# Terminal 1: Main branch
cd ~/opik
./scripts/dev-runner.sh --restart
# Services running on ports based on hash of ~/opik

# Terminal 2: Feature branch worktree
cd ~/opik-worktrees/feature-xyz
./scripts/dev-runner.sh --restart
# Services running on different ports based on hash of ~/opik-worktrees/feature-xyz

Port Collision Detection

The script automatically checks for port conflicts before starting services. If a collision is detected, you'll see an error message with suggestions:

[ERROR] Port 8122 (Backend) is already in use

Port collision detected! Another process is using one or more required ports.
This might be caused by:
  - Another Opik instance running from a different worktree
  - Stale containers from a previous run
  - Other services using the same ports

To resolve:
  1. Stop other Opik instances: ./scripts/dev-runner.sh --stop
  2. Use a different port offset: export OPIK_PORT_OFFSET=<0-99>
  3. Check running processes: lsof -i :8122

File Isolation

Each worktree also gets isolated log and PID files:

Docker Container Naming

Docker containers are prefixed with the worktree project name:

• Main repo (opik): opik-opik-mysql-1, opik-opik-backend-1, etc.
• Worktree (feature-xyz): opik-feature-xyz-mysql-1, opik-feature-xyz-backend-1, etc.

Environment Variables

SDK Configuration

When using the Opik SDK with a worktree-based development environment, configure it to use your worktree's backend port (shown when you start the environment):

# Configure SDK (use the backend port shown at startup)
export OPIK_URL_OVERRIDE='http://localhost:8080'  # or your worktree's port
export OPIK_WORKSPACE='default'

Or edit ~/.opik.config:

[opik]
url_override = http://localhost:8122
workspace = default