chore: Use devcontainers

PierreQuinton · PierreQuinton · commit 74677dddd2b1 · 2026-05-28T11:40:45.000+02:00
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
@@ -0,0 +1,27 @@
+FROM python:3.14-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential git ca-certificates curl \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+ENV UV_NO_SYNC=1
+ENV CC=gcc
+ENV PYTHONPATH=/workspaces/TorchJD/tests
+ENV VIRTUAL_ENV=/opt/venv
+ENV PATH=/opt/venv/bin:$PATH
+
+COPY pyproject.toml /tmp/torchjd-install/pyproject.toml
+COPY README.md /tmp/torchjd-install/README.md
+COPY src/ /tmp/torchjd-install/src/
+
+WORKDIR /tmp/torchjd-install
+RUN uv venv /opt/venv \
+    && uv pip install --python-version=3.14 -e '.[full]' --group check --group doc --group test --group plot
+
+WORKDIR /workspaces/TorchJD
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -0,0 +1,26 @@
+{
+  "name": "TorchJD",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "astral-sh.ruff",
+        "astral-sh.ty"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/opt/venv/bin/python",
+        "python.languageServer": "None",
+        "[python]": {
+          "editor.defaultFormatter": "astral-sh.ruff"
+        },
+        "ruff.importStrategy": "fromEnvironment",
+        "ty.importStrategy": "fromEnvironment"
+      }
+    }
+  },
+  "postCreateCommand": "uv pip install -e '.[full]' --group check --group doc --group test --group plot && uv run pre-commit install"
+}
diff --git a/.dockerignore b/.dockerignore
@@ -0,0 +1,12 @@
+.git
+.venv
+venv
+__pycache__
+*.pyc
+docs/_build
+.pytest_cache
+.mypy_cache
+.ruff_cache
+build/
+dist/
+*.egg-info/
diff --git a/.github/workflows/build-devcontainer.yml b/.github/workflows/build-devcontainer.yml
@@ -0,0 +1,42 @@
+name: Build Devcontainer
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '.devcontainer/Dockerfile'
+      - 'pyproject.toml'
+      - '.github/workflows/build-devcontainer.yml'
+  pull_request:
+    paths:
+      - '.devcontainer/Dockerfile'
+      - 'pyproject.toml'
+      - '.github/workflows/build-devcontainer.yml'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push devcontainer image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: .devcontainer/Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ghcr.io/${{ github.repository }}/devcontainer:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
@@ -64,21 +64,44 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 
-  build-doc:
-    name: Build and test documentation
+  build-devcontainer:
+    name: Build devcontainer image
     runs-on: ubuntu-latest
+    permissions:
+      packages: write
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
 
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v7
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
         with:
-          python-version: '3.14'
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: ./.github/actions/install-deps
+      - name: Build and push devcontainer image
+        uses: docker/build-push-action@v6
         with:
-          groups: doc
+          context: .
+          file: .devcontainer/Dockerfile
+          push: true
+          tags: ghcr.io/${{ github.repository }}/devcontainer:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  build-doc:
+    name: Build and test documentation
+    needs: build-devcontainer
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/${{ github.repository }}/devcontainer:${{ github.sha }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Sync project installation
+        run: uv pip install -e '.[full]' --group doc
 
       - name: Build Documentation
         working-directory: docs
@@ -90,19 +113,16 @@ jobs:
 
   code-quality:
     name: Code quality (ty and pre-commit hooks)
+    needs: build-devcontainer
     runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/${{ github.repository }}/devcontainer:${{ github.sha }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
 
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v7
-        with:
-          python-version: '3.14'
-
-      - uses: ./.github/actions/install-deps
-        with:
-          groups: check test plot
+      - name: Sync project installation
+        run: uv pip install -e '.[full]' --group check --group test --group plot
 
       - name: Run pre-commit hooks
         run: uv run pre-commit run --all-files
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -19,63 +19,72 @@ with the affected code.
 
 ## Installation
 
-To work with TorchJD, we suggest you to use [uv](https://docs.astral.sh/uv/). While this is not
-mandatory, we only provide installation steps with this tool. You can install it by following their
-[installation documentation](https://docs.astral.sh/uv/getting-started/installation/). We also
-suggest to use VSCode with the `Python`, `ty` and `ruff` extensions (without `Pylance`).
+TorchJD provides a **[devcontainer](https://containers.dev/)** configuration that gives you a
+ready-to-use development environment with all dependencies pre-installed. This is the recommended way
+to set up your environment.
 
-1) Pre-requisites: Use `uv` to install a Python version compatible with TorchJD and to pin it to the
-  `TorchJD` folder. From the root of the `TorchJD` repo, run:
-   ```bash
-   uv python install 3.14.0
-   uv python pin 3.14.0
-   ```
+### Using the devcontainer
 
-2) Create a virtual environment and install the project in it. From the root of `TorchJD`, run:
+1. Install [Docker](https://docs.docker.com/get-docker/) and
+   [VS Code](https://code.visualstudio.com/) with the
+   [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
+2. Clone the repository and open it in VS Code:
    ```bash
-   uv venv
-   CC=gcc uv pip install --python-version=3.14 -e '.[full]' --group check --group doc --group test --group plot
-   ```
-   If you want to install PyTorch with a different CUDA version (this could be required depending on
-   your GPU), you'll need to specify an extra index. For instance, for CUDA 12.6, run:
-      ```bash
-   uv venv
-   CC=gcc uv pip install --python-version=3.14 -e '.[full]' --group check --group doc --group test --group plot --index-strategy unsafe-best-match --extra-index-url https://download.pytorch.org/whl/cu126
+   git clone https://github.com/SimplexLab/TorchJD.git
+   code TorchJD
    ```
+3. When prompted, click **"Reopen in Container"** (or press `Ctrl+Shift+P` and run
+   *"Dev Containers: Reopen in Container"*). The container will build on first launch and install all
+   dependencies automatically.
 
-3) Set environment variables:
+Alternatively, you can use **[GitHub Codespaces](https://github.com/features/codespaces)** directly
+from the repository page — no local setup required.
 
-   We need to use `UV_NO_SYNC=1` to prevent `uv` from syncing all the time. This is because by
-   default, it tries to resolve libraries compatible with the whole range of Python versions
-   supported by TorchJD, but in reality, we just need an installation compatible with the currently
-   used Python version. That's also why we specify `--python-version=3.14` when running
-   `uv pip install`. To follow that recommendation, add the following line to your `.bashrc`:
-   ```bash
-   export UV_NO_SYNC=1
-   ```
-   and start a new terminal. The alternative is to use the `--no-sync` flag whenever you run a pip
-   command that would normally sync (like `uv run`).
+The devcontainer includes:
+- Python 3.14 with all TorchJD dependencies (including optional ones)
+- All development tools: `uv`, `ruff`, `ty`, `pre-commit`, `pytest`
+- Pre-configured VS Code extensions and settings
+- `PYTHONPATH` set up for the `tests/` folder
 
-   Lastly, to run some scripts from the `tests` folder, you'll have to add the `TorchJD/tests`
-   folder to your `PYTHONPATH`. For that, you should add the following line to your `.bashrc`:
-   ```bash
-   export PYTHONPATH="$PYTHONPATH:<path_to_TorchJD>/tests"
-   ```
-   where `<path_to_TorchJD>` is the absolute path to your `TorchJD` repo.
+### GPU support
 
-4) Install pre-commit:
-   ```bash
-   uv run pre-commit install
-   ```
+If you have an NVIDIA GPU and want to run tests on CUDA, add the following to
+`.devcontainer/devcontainer.json` inside the top-level object:
+```json
+"runArgs": ["--gpus", "all"]
+```
 
-> [!TIP]
-> If you're running into issues when `uv` tries to compile `ecos`, make sure that `gcc` is
-> installed. Alternatively, you can try to install `clang` or try to use some older Python version
-> (3.12) for which `ecos` has provided compiled packages (the list is accessible
-> [here](https://pypi.org/project/ecos/#files)).
+### CUDA-specific PyTorch installation
 
-> [!TIP]
-> The Python version that you should specify in your IDE is `<path-to-TorchJD>/.venv/bin/python`.
+By default, the devcontainer installs the CPU-only version of PyTorch. If you need a CUDA version,
+run the following inside the container:
+```bash
+uv pip install --python-version=3.14 -e '.[full]' --group check --group doc --group test --group plot --index-strategy unsafe-best-match --extra-index-url https://download.pytorch.org/whl/cu126
+```
+(replace `cu126` with your CUDA version).
+
+### Adding LaTeX (for trajectory plotting)
+
+The trajectory plotting scripts require LaTeX. Install it inside the container with:
+```bash
+sudo apt-get update && sudo apt-get install -y texlive-latex-extra texlive-fonts-recommended dvipng cm-super
+```
+
+### Manual setup (without devcontainer)
+
+If you prefer a local setup, you'll need:
+- [uv](https://docs.astral.sh/uv/getting-started/installation/)
+- Python 3.14 (install via `uv python install 3.14.0`)
+- `gcc` (for compiling `ecos`)
+
+Then, from the repo root:
+```bash
+uv venv
+CC=gcc uv pip install --python-version=3.14 -e '.[full]' --group check --group doc --group test --group plot
+export UV_NO_SYNC=1
+export PYTHONPATH="$PYTHONPATH:$PWD/tests"
+uv run pre-commit install
+```
 
 > [!TIP]
 > In the following commands, you can get rid of the `uv run` prefix if you activate the `venv`
@@ -85,13 +94,12 @@ suggest to use VSCode with the `Python`, `ty` and `ruff` extensions (without `Py
 
 ### Clean reinstallation
 
-If you want to update all dependencies or just reinstall from scratch, run the following command
-from the root of `TorchJD`:
+If you want to update all dependencies or just reinstall from scratch, run the following inside the
+container:
 ```bash
-rm -rf .venv
-rm -f uv.lock
-uv venv
-CC=gcc uv pip install --python-version=3.14 -e '.[full]' --group check --group doc --group test --group plot
+rm -rf /opt/venv
+uv venv /opt/venv
+uv pip install --python-version=3.14 -e '.[full]' --group check --group doc --group test --group plot
 uv run pre-commit install
 ```
 
