From b54e1921880f38aeb3759ddb7881f1426a43b69d Mon Sep 17 00:00:00 2001 From: Dmitri Smirnov Date: Fri, 31 Jul 2026 21:48:17 +0000 Subject: [PATCH] refactor(devcontainer): support local environment overrides Move the tracked Dev Container build defaults from the repository-level .env file to .devcontainer/.env.defaults. Generate an ignored .env.compose during initializeCommand by copying the defaults and appending optional values from .env.local. Point .devcontainer/.env at the generated file so Compose discovers the merged configuration without requiring an extra setup command. Ignore root-level .env variants in Git and Docker build contexts, document dependency overrides and per-checkout Compose project names, and broaden the editor guidance to IDEs implementing the Development Container Specification. --- .devcontainer/.env | 2 +- .env => .devcontainer/.env.defaults | 0 .devcontainer/devcontainer.json | 5 +++- .devcontainer/initialize-compose-env.sh | 15 ++++++++++++ .dockerignore | 1 + .gitignore | 1 + README.md | 7 +++--- docs/getting-started.md | 31 ++++++++++++++++--------- 8 files changed, 46 insertions(+), 16 deletions(-) rename .env => .devcontainer/.env.defaults (100%) create mode 100755 .devcontainer/initialize-compose-env.sh diff --git a/.devcontainer/.env b/.devcontainer/.env index 4a82335f5e..b3e31bc136 120000 --- a/.devcontainer/.env +++ b/.devcontainer/.env @@ -1 +1 @@ -../.env \ No newline at end of file +../.env.compose \ No newline at end of file diff --git a/.env b/.devcontainer/.env.defaults similarity index 100% rename from .env rename to .devcontainer/.env.defaults diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index b2b273e19d..1321c34823 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -15,7 +15,10 @@ "version": "23" } }, - "initializeCommand": "mkdir -p \"${localEnv:HOME}/.codex\"", + "initializeCommand": { + "codex-home": "mkdir -p \"${localEnv:HOME}/.codex\"", + "compose-env": "bash \"${localWorkspaceFolder}/.devcontainer/initialize-compose-env.sh\"" + }, "postCreateCommand": "curl -fsSL --output /tmp/codex-install.sh https://chatgpt.com/codex/install.sh && CODEX_NON_INTERACTIVE=1 sh /tmp/codex-install.sh; status=$?; rm -f /tmp/codex-install.sh; exit $status", "mounts": [ "source=${localEnv:HOME}/.codex,target=/home/dev/.codex,type=bind" diff --git a/.devcontainer/initialize-compose-env.sh b/.devcontainer/initialize-compose-env.sh new file mode 100755 index 0000000000..2d5c715e86 --- /dev/null +++ b/.devcontainer/initialize-compose-env.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash + +set -euo pipefail + +repo_root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd) +compose_env="${repo_root}/.env.compose" +user_name=${USER:-$(id -un)} +checkout_name=$(basename -- "${repo_root}") + +cp "${repo_root}/.devcontainer/.env.defaults" "${compose_env}" +printf '\nCOMPOSE_PROJECT_NAME=simphony-%s-%s\n' ${user_name} ${checkout_name} >> ${compose_env} +if [[ -f "${repo_root}/.env.local" ]]; then + printf '\n' >> "${compose_env}" + cat "${repo_root}/.env.local" >> "${compose_env}" +fi diff --git a/.dockerignore b/.dockerignore index c5974fba2f..9b3d5ce78d 100644 --- a/.dockerignore +++ b/.dockerignore @@ -2,5 +2,6 @@ .github/ .devcontainer/ .env +.env.* .venv __pycache__/ diff --git a/.gitignore b/.gitignore index 5be058f46b..2fc7bcc3e2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ *~ +/.env.* dd4hepplugins/examples/drich-dev/ dd4hepplugins/examples/calibrations/ dd4hepplugins/examples/fieldmaps/ diff --git a/README.md b/README.md index 3724536e57..b665724f72 100644 --- a/README.md +++ b/README.md @@ -50,9 +50,10 @@ devcontainer exec bash The source tree is mounted into the container. Once inside, use the same CMake commands above and rerun only the relevant build and tests as you work. -The root `.env` selects the OS and toolchain versions. See [Choose dependency -versions](docs/getting-started.md#choose-dependency-versions) before changing -them. +The `.devcontainer/.env.defaults` file selects the default OS and toolchain +versions. See [Choose dependency +versions](docs/getting-started.md#choose-dependency-versions) to override them +locally. To run GPU-backed code, install the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) diff --git a/docs/getting-started.md b/docs/getting-started.md index f1faec6f6a..1a491b0d10 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -45,17 +45,21 @@ create one with `git switch -c new-branch`. ### Choose dependency versions -Skip this section if the default dependency versions meet your needs. The root -`.env` file selects the OS and toolchain used to build the Dev Container. -`.devcontainer/.env` links to it so Compose can discover the same settings. -Edit `.env` when you want to use another supported combination or experiment -with a new dependency version. +If the default dependency versions meet your needs, skip this section and +continue to [Start the environment](#start-the-environment). + +The `.devcontainer/.env.defaults` file contains the default OS and toolchain +used to build the Dev Container. To use another supported combination or +experiment with a new dependency version, put your overrides in the `.env.local` +file at the repository root. During `devcontainer up`, the initialization step +combines the defaults and local overrides into the `.env.compose` file that +Compose reads. The defaults match the `base` alias in the [published container matrix](../README.md#published-container-images). Start with another `base` combination from this matrix when possible. -After editing `.env`, recreate the container so it uses the new values: +After editing `.env.local`, recreate the container so it uses the new values: ```shell devcontainer up --remove-existing-container @@ -89,15 +93,20 @@ devcontainer up --remove-existing-container You do not need to recreate the container after switching source branches. The checkout remains mounted directly into the environment. -The default Compose project name keeps different system users from colliding, -even when they share a Docker daemon. If one account uses multiple checkouts or -runs concurrent jobs, set a unique project name before starting the container: +The default Compose project name includes the system user and checkout +directory name, keeping users and checkouts from colliding when they share a +Docker daemon. To use a different name, append it to `.env.local` before +starting the container: ```shell -export COMPOSE_PROJECT_NAME="simphony-${USER}-my_cool_feature" +echo "COMPOSE_PROJECT_NAME=simphony-${USER}-my_cool_feature" >> .env.local ``` -The same configuration also works with the VS Code Dev Containers extension. +Replace `my_cool_feature` with a short unique name for that checkout. + +This configuration also works with IDEs and tools that support the [Development +Container Specification](https://containers.dev/). When using VS Code, its Dev +Containers extension also installs the recommended extensions. ### Build and test