For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Copy to LLMGithubGo to App
DocumentationIntegrationsAgent OptimizationSelf-hosting OpikSDK & API referenceOpik University
DocumentationIntegrationsAgent OptimizationSelf-hosting OpikSDK & API referenceOpik University
  • Getting Started
    • Home
    • Quickstart
    • Quickstart notebook
    • Roadmap
    • FAQ
    • Changelog
  • Observability
    • Concepts
    • Log traces
    • Log conversations
    • Log user feedback
    • Log media & attachments
    • Cost tracking
    • Opik Assist
  • Evaluation
    • Overview
    • Concepts
    • Manage datasets
    • Evaluate single prompts
    • Evaluate your agent
    • Evaluate agent trajectories
    • Evaluate multimodal traces
    • Evaluate multi-turn agents
    • Manually logging experiments
    • Re-running an existing experiment
    • Annotation Queues
  • Prompt engineering
    • Prompt management
    • Prompt Playground
    • Prompt Generator and Improver
    • Opik's MCP server
  • Testing
    • Pytest integration
  • Production
    • Production monitoring
    • Online Evaluation rules
    • Gateway
    • Guardrails
    • Anonymizers
    • Alerts
    • Dashboards
  • Administration
    • Overview
    • Roles and Permissions
  • Contributing
    • Contribution Overview
      • Documentation
      • Local Development Setup
      • Python SDK
      • TypeScript SDK
      • Opik Optimizer
      • Frontend
      • Backend
LogoLogo
Copy to LLMGithubGo to App
On this page
  • Contributing to the Backend
  • Project Structure
  • Setting Up Your Development Environment
  • 4. Code Formatting
  • 5. Running Tests
  • 6. Submitting a Pull Request
  • Advanced Backend Topics
ContributingSpecific Contribution Guides

Backend

Was this page helpful?
Previous

Bounty Program

Next
Built with

Contributing to the Backend

This guide will help you get started with contributing to the Opik backend.

Before you start, please review our general Contribution Overview and the Contributor License Agreement (CLA).

Project Structure

The Opik backend is a Java application (source in apps/opik-backend) that forms the core of the Opik platform. It handles data ingestion, storage, API requests, and more.

Setting Up Your Development Environment

We provide multiple ways to develop the backend. Choose the approach that best fits your workflow:

Local Process Mode (Recommended)
Docker Mode
Manual Setup

Best for rapid development

This mode runs the backend as a local process while infrastructure and other services run in Docker:

Linux/Mac
Windows
$# From repository root - restart everything
$scripts/dev-runner.sh --be-only-restart
$
$# Or just start (faster if already built)
$scripts/dev-runner.sh --be-only-start

The backend API will be accessible at http://localhost:8080.

Benefits:

  • Fast rebuilds and restarts
  • Easy debugging
  • Faster code changes without Docker container rebuilds

Prerequisites:

  • Java Development Kit (JDK) 21
  • Apache Maven 3.8+

For comprehensive documentation on all development modes, troubleshooting, and advanced workflows, see our Local Development Guide.

4. Code Formatting

We use Spotless for code formatting. Before submitting a PR, please ensure your code is formatted correctly:

Using dev-runner (Recommended)
Manual Maven
Linux/Mac
Windows
$# From repository root
$scripts/dev-runner.sh --lint-be

Our CI (Continuous Integration) will check formatting using mvn spotless:check and fail the build if it’s not correct.

5. Running Tests

Ensure your changes pass all backend tests:

$cd apps/opik-backend
$mvn test

Tests leverage the testcontainers library to run integration tests against real instances of external services (Clickhouse, MySQL, etc.). Ports for these services are randomly assigned by the library during tests to avoid conflicts.

6. Submitting a Pull Request

After implementing your changes, ensuring tests pass, and code is formatted, commit your work and open a Pull Request against the main branch of the comet-ml/opik repository.

Advanced Backend Topics

Health Check

To check the health of your locally running backend application, you can access the health check endpoint in your browser or via curl at http://localhost:8080/healthcheck.

Database Migrations (Liquibase)

Opik uses Liquibase for managing database schema changes (DDL migrations) for both MySQL and ClickHouse.

  • Location: Migrations are located at apps/opik-backend/src/main/resources/liquibase/{{DB}}/migrations (where {{DB}} is db for MySQL or dbAnalytics for ClickHouse).
  • Automation: Execution is typically automated via the apps/opik-backend/run_db_migrations.sh script, Docker images, and Helm charts in deployed environments.

Running Migrations in Local Development:

Using dev-runner (Recommended)
Manual Execution
Linux/Mac
Windows
$# From repository root
$scripts/dev-runner.sh --migrate

This command will:

  • Start infrastructure services if needed
  • Build the backend if no JAR file exists
  • Run both MySQL and ClickHouse migrations automatically

Requirements for DDL Migrations:

  • Must be backward compatible (new fields optional/defaulted, column removal in stages, no renaming of active tables/columns).
  • Must be independent of application code changes.
  • Must not cause downtime.
  • Must have a unique name.
  • Must contain a rollback statement (or use empty if Liquibase cannot auto-generate one). Refer to Evolutionary Database Design and Liquibase Rollback Docs.
  • For more complex migration, apply the transition phase. Refer to Evolutionary Database Design
Data Migrations (DML)

DML (Data Manipulation Language) migrations are for changes to data itself, not the schema.

  • Execution: These are not run automatically. They must be run manually by a system admin using a database client.
  • Documentation: DML migrations are documented in CHANGELOG.md (link to GitHub: CHANGELOG.md) and the scripts are placed at apps/opik-backend/data-migrations along with detailed instructions.
  • Requirements for DML Migrations:
    • Must be backward compatible (no data deletion unless 100% safe, allow rollback, no performance degradation).
    • Must include detailed execution instructions.
    • Must be batched appropriately to avoid disrupting operations.
  • Must not cause downtime.
  • Must have a unique name.
  • Must contain a rollback statement.
Accessing ClickHouse Directly

You can query the ClickHouse REST endpoint directly. For example, to get the version:

$echo 'SELECT version()' | curl -H 'X-ClickHouse-User: opik' -H 'X-ClickHouse-Key: opik' 'http://localhost:8123/' -d @-

Sample output: 23.8.15.35