Skip to main content

Getting Started

This guide covers everything needed to set up a local development environment for IdeGYM, run the test suites, and make your first code change.

Prerequisites​

Required for all development​

ToolVersionPurposeInstall
uv>= 0.10.0Python package managerSee below
GitanyVersion controlSystem package manager

Install uv (the only tool you need to install manually):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv will manage Python 3.12 for you — no separate Python install required.

Required for integration tests​

ToolVersionPurposeInstall
Docker>= 24Build and run containersDocker Desktop or brew install docker

Integration tests build real Docker images and push them to a local registry. They require:

  1. A running Docker daemon.
  2. A container registry. Start one with: 
    docker run -d -p 5000:5000 --name registry registry:2

    [!WARNING] On macOS, AirPlay Receiver (Control Center) occupies port 5000 by default. If the command above fails with address already in use, use port 5001 instead:

    docker run -d -p 5001:5000 --name registry registry:2

    To free port 5000 permanently, turn off AirPlay Receiver in System Settings → General → AirDrop & Handoff → AirPlay Receiver. See also: Port 5000 already in use.

  3. The IDEGYM_TEST_REGISTRY environment variable set to the registry address: 
    export IDEGYM_TEST_REGISTRY=localhost:5000   # or localhost:5001 on macOS

In CI this registry is provided automatically as a Docker service container. Locally you need to start it manually before running the integration suite.

Required for e2e tests and local deployment​

ToolVersionPurposeInstall
kubectl>= 1.28Kubernetes CLIbrew install kubernetes-cli
minikube>= 1.35Local Kubernetes clusterbrew install minikube

See Local Deployment and E2E Tests for full setup instructions.

Installation​

1. Clone the repository​

git clone https://github.com/JetBrains-Research/idegym.git
cd idegym

2. Install Python​

uv manages the Python version declared in .python-version (3.12):

uv python install

3. Create a virtual environment​

uv venv --seed

--seed pre-installs pip, setuptools, and wheel into the virtual environment alongside uv's own tooling. Some build backends and older packages rely on these tools being present; without --seed they may not be available inside the venv.

This creates .venv/ in the project root. Activate it if needed by your IDE or shell:

# Activate (optional — uv run handles this automatically)
source .venv/bin/activate   # Linux / macOS
.venv\Scripts\activate      # Windows

4. Install all dependencies​

uv sync --all-packages --all-extras --all-groups

This installs every package across all workspace members, including dev and test dependencies.

5. Install pre-commit hooks​

pre-commit install

Hooks run automatically on git commit to enforce code style.

Running Tests​

Unit tests​

Fast, self-contained tests with no external dependencies:

uv run pytest -m unit

Integration tests​

Tests that build Docker images and push them to a local registry.

Prerequisites (see Required for integration tests above):

  • Docker daemon running
  • Local registry started (port 5000, or 5001 on macOS if AirPlay Receiver is active)
  • IDEGYM_TEST_REGISTRY set to the registry address
IDEGYM_TEST_REGISTRY=localhost:5000 uv run pytest -m integration
# macOS with AirPlay Receiver enabled:
IDEGYM_TEST_REGISTRY=localhost:5001 uv run pytest -m integration

End-to-end tests​

E2E tests require a running Minikube cluster with specific addons. See E2E Tests for the full setup, then run:

uv run pytest -m e2e

Speed up subsequent runs by reusing a running cluster:

uv run pytest -m e2e --skip-build --reuse-resources

Verbose output​

uv run pytest -vv -s -o log_cli=true --log-cli-level=INFO

Code Style​

IdeGYM uses Ruff for formatting and linting.

Configuration (pyproject.toml):

  • Line length: 120 characters
  • Indent: 4 spaces
  • Quotes: double
  • Line endings: LF

Auto-format code​

uv run ruff format

Check for lint errors​

uv run ruff check

Fix auto-fixable lint errors​

uv run ruff check --fix

Pre-commit hooks run both ruff format and ruff check on every commit.

Run all pre-commit hooks manually​

pre-commit run --all-files

Type Conventions​

  • Use Optional[X] for optional types (not X | None)
  • Use built-in generics for non-optional: dict[str, Any], list[str] (not Dict, List)
  • Target Python 3.12+ features where appropriate

IDE Setup​

PyCharm / IntelliJ IDEA​

  1. Open the project root as the project directory.
  2. Set the Python interpreter to .venv/bin/python.
  3. Mark e2e-tests/ as a Source Root (right-click → Mark Directory As → Sources Root).
  4. Install the Kubernetes plugin for working with manifests.

VS Code​

  1. Install the Python extension.
  2. Select the interpreter from .venv/bin/python.
  3. The workspace is already configured — open the root folder.

Package Manager Notes​

This project uses uv exclusively. Never use pip directly — it bypasses uv's lockfile and workspace management.

Instead ofUse
pip install <pkg>uv add <pkg>
pip install -r requirements.txtuv sync
python -m pytestuv run pytest
python script.pyuv run python script.py

Next Steps​