This guide outlines the standard procedures for setting up a local development environment for the OpenML ecosystem. It covers the configuration of the backend servers (API v1 and API v2) and the Python Client SDK.

OpenML currently has two backend architecture:

• API v1: The PHP-based server currently serving production traffic.
• API v2: The Python-based server (FastAPI) currently under active development.

Note on Migration: API v1 is projected to remain operational through at least 2026. API v2 is the target architecture for future development.

This section details the deployment of the legacy PHP backend.

• Docker: Docker Desktop (Ensure the daemon is running).
• Version Control: Git.

Retrieve the OpenML services source code:

git clone https://github.com/openml/services
cd services

To ensure the containerized PHP service can write to the local filesystem, initialize the data directory permissions.

From the repository root:

chown -R www-data:www-data data/php

If the www-data user does not exist on the host system, grant full permissions as a fallback:

chmod -R 777 data/php

Initialize the container stack:

docker compose --profile all up -d

If API v2 (Python backend) containers are present on the system, name conflicts may occur. To resolve this, stop and remove existing containers before launching API v1:

docker compose --profile all down
docker compose --profile all up -d

Validate the deployment by accessing the flow endpoint. A successful response will return structured JSON data.

• Endpoint: http://localhost:8080/api/v1/json/flow/181

To direct the openml-python client to the local API v1 instance, modify the configuration as shown below. The API key corresponds to the default key located in services/config/php/.env.

import openml
from openml_sklearn.extension import SklearnExtension
from sklearn.neighbors import KNeighborsClassifier

# Configure client to use local Docker instance
openml.config.server = "http://localhost:8080/api/v1/xml"
openml.config.apikey = "AD000000000000000000000000000000"

# Test flow publication
clf = KNeighborsClassifier(n_neighbors=3)
extension = SklearnExtension()
knn_flow = extension.model_to_flow(clf)

knn_flow.publish()

This section details the deployment of the FastAPI backend.

• Docker: Docker Desktop (Ensure the daemon is running).
• Version Control: Git.

Retrieve the API v2 source code:

git clone https://github.com/openml/server-api
cd server-api

Build and start the container stack:

docker compose --profile all up

Validate the deployment using the following endpoints:

• Task Endpoint: http://localhost:8001/tasks/31
• Swagger UI (Documentation): http://localhost:8001/docs

This section outlines the environment setup for contributing to the OpenML Python client.

git clone https://github.com/openml/openml-python
cd openml-python

Create an isolated virtual environment (example using Conda):

conda create -n openml-python-dev python=3.12
conda activate openml-python-dev

Install the package in editable mode, including development and documentation dependencies:

python -m pip install -e ".[dev,docs]"

Install pre-commit hooks to enforce coding standards:

pre-commit install
pre-commit run --all-files

The OpenML Python SDK utilizes pytest markers to categorize tests based on dependencies and execution context.

Run the full test suite:

pytest

Run a specific subset (e.g., scikit-learn tests):

pytest -m sklearn

Exclude production tests (local only):

pytest -m "not production_server"

Certain tests require administrative privileges on the test server. These are skipped automatically unless an admin API key is provided via environment variables.

$env:OPENML_TEST_SERVER_ADMIN_KEY = "admin-key"

export OPENML_TEST_SERVER_ADMIN_KEY="admin-key"