refactor(devcontainer): support local environment overrides (#433)

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.

Author: plexoos

.devcontainer/.env

@@ -1 +1 @@
-../.env
+../.env.compose

.env .devcontainer/.env.defaults.env renamed to .devcontainer/.env.defaults

@@ -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"

.devcontainer/devcontainer.json

@@ -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

.devcontainer/initialize-compose-env.sh

@@ -2,5 +2,6 @@
 .github/
 .devcontainer/
 .env
+.env.*
 .venv
 __pycache__/

.dockerignore

@@ -1,4 +1,5 @@
 *~
+/.env.*
 dd4hepplugins/examples/drich-dev/
 dd4hepplugins/examples/calibrations/
 dd4hepplugins/examples/fieldmaps/

.gitignore

@@ -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)

README.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