ContributingSpecific Contribution Guides

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:

Best for rapid development

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

$# 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:

$# 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

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.

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:

$# 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

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.

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