The repository is developed in a Dev Container (.devcontainer/) built from
mcr.microsoft.com/devcontainers/dotnet:2-10.0-noble with PostgreSQL 18 and
local Keycloak sidecars. This page describes the pinned toolchain, how to
provision it, and how to validate it.
| Item | Status |
|---|---|
global.json |
Added. Selects SDK 11.0.100 with rollForward: disable. |
docs/dev-environment.md |
Added (this file). |
.devcontainer/Dockerfile |
Provisions verified SDK/Node archives, Python stdlib and Docker client only. |
.devcontainer/devcontainer.json |
Adds pinned GitHub CLI; existing agent features are preserved. |
.devcontainer/docker-compose.yml |
Includes a development Keycloak and its own PostgreSQL volume. |
.devcontainer/.env.example |
Added local-only placeholders. |
.devcontainer/devcontainer-lock.json |
Generated by Dev Container CLI 0.90.0 upgrade; only GitHub CLI was added. Existing agent feature digests are unchanged. |
| Container image build | Not run. No image has been built or rebuilt. |
Until the container is rebuilt or the exact SDK is provisioned separately,
repo-local dotnet commands fail because of global.json. Rebuild instructions
and the SDK pin must be used together. Do not retarget to SDK 10 as a workaround.
Pins were checked against official sources on 2026-11-11. If an artifact is no longer available, stop and report it; do not substitute another version.
| Tool | Version | Source and integrity check |
|---|---|---|
| .NET SDK | 11.0.100 |
Official archive from the .NET 11 release metadata; SHA-512 checked before extraction; installed in /opt/dotnet11, first on PATH, with DOTNET_ROOT=/opt/dotnet11. SDK 10 stays in its base-image location. |
| Node.js / npm | v24.22.2 / 11.19.1 |
Official linux-x64 tarball from nodejs.org; SHA-256 checked against that release's SHASUMS256.txt; installed in /opt/node. No global npm packages. |
| GitHub CLI | 2.103.3 |
Dev Container feature ghcr.io/devcontainers/features/github-cli:1 with "version": "2.103.3". |
| Docker CLI | 5:29.9.3-1~ubuntu.24.04~noble |
docker-ce-cli from Docker's official Ubuntu Noble apt repository; signing-key fingerprint 9DC858229FC7DD38854AE2D88D81803C0EBFCD88 is checked. |
| Docker Compose plugin | 5.7.0-1~ubuntu.24.04~noble |
docker-compose-plugin from the same repository. |
| Python stdlib | Ubuntu's current libpython3.12-stdlib |
Installed through apt and deliberately not pinned, so security updates still apply. Fixes ModuleNotFoundError: No module named 'json'. |
| PostgreSQL client | Ubuntu's current postgresql-client |
Provides psql for scripts/setup-database.py; installed through apt for security updates. |
Pinned integrity values (linux-x64):
- .NET SDK
dotnet-sdk-11.0.100-linux-x64.tar.gz, SHA-512:1bec9cca2ec689b1e80245b84f2b53c9441d1aa6daccf2ceb27490768bffa95954fa585bd275def31069d874d543d9ba9e6591fe9ade2dbd9f34ec5c0fd0050c - Node
node-v24.22.2-linux-x64.tar.xz, SHA-256:48cc0e21e048790e54c0cf5749c2725005313d652651c40b7a21feb9697aaf75
The existing agent features (copilot-cli:1, claude-code:2, codex:1) keep
their current options and locked digests.
- amd64 only. Docker package versions were verified against the amd64 package index only. The image build should fail fast on other architectures until the arm64 index is checked.
- Docker client only. No Docker daemon,
containerd, privileged mode, or socket mount is configured. Having thedockerCLI does not give access to a Docker host. Daemon access needs separate, explicit approval. - Dev Container features run after the Dockerfile. Confirm after a rebuild that
nodestill resolves to/opt/node/bin/node.
PostgreSQL credentials and the Keycloak bootstrap administrator come from
.devcontainer/.env, which Git ignores. Create it from the sample if no local
file already exists:
cp -n .devcontainer/.env.example .devcontainer/.envThen edit the placeholders. For an existing .env, add
KC_BOOTSTRAP_ADMIN_USERNAME=dev-admin and a randomly generated
KC_BOOTSTRAP_ADMIN_PASSWORD. cp -n will not overwrite an existing .env.
Never commit, print, or share .env.
Changing POSTGRES_* values only affects a new, empty data volume. An
existing postgres-data volume keeps the credentials it was created with. Do not
run docker compose down -v or delete the volume to "reset" credentials without
explicit approval, because that destroys local data.
Keycloak uses a separate keycloak-postgres-data volume, initialized with the
same POSTGRES_* values on its first start. Its bootstrap administrator is also
created only when Keycloak initializes an empty database. Subsequent .env
changes do not change existing database or administrator credentials.
For the application database, follow the
database setup from .env
instructions before starting the backend. The PostgreSQL sidecar alone does not
create the application schema or Data Protection key table.
After rebuilding the dev container, Keycloak starts with it on port 8180. The
dev container forwards that port to the browser. The service imports
deploy/keycloak/dev-realm.json into a new Keycloak database; it contains the
subscribed-dev realm and client, but no users or fixed client secret. Realm
imports are skipped when the realm already exists. This service is for local
development only.
The realm file is mounted as subscribed-dev-realm.json inside the container:
Keycloak requires the import filename to match the realm name.
The default application URL is http://localhost:5080, where the backend serves
the built frontend. Run npm --prefix frontend run build before starting it;
no Angular development server is required. The realm permits explicit login and
logout callbacks on ports 5080 and 4200. Port 4200 is only for the optional Angular
hot-reload workflow described in the frontend guide.
Existing realms are not re-imported; the user-provisioning script below updates
their callback registrations as well.
Open Dev Containers: Show Container Log from the Command Palette if the startup log does not open automatically. To inspect the Keycloak service on the Docker host:
docker logs --tail 100 subscribed_devcontainer-keycloak-1If bootstrap credentials were added to .devcontainer/.env after the container
was created, restarting the existing container does not reload them. Recreate
only Keycloak using the actual Dev Container Compose project name:
docker compose -p subscribed_devcontainer -f .devcontainer/docker-compose.yml \
up -d --no-deps --force-recreate --wait --wait-timeout 240 keycloakThis preserves the database volumes. Once Keycloak is healthy, retry opening the dev container.
On the Docker host, from the repository root, set KC_DEV_ADMIN_PASSWORD to
the bootstrap password from .devcontainer/.env. If the bootstrap username is
not dev-admin, set KC_DEV_ADMIN_USERNAME to that username too. Find the Compose project name
of the dev container's Keycloak and set COMPOSE_PROJECT_NAME to that name
(the Dev Container tooling may use a different name from plain Compose):
docker ps --filter label=com.docker.compose.service=keycloak \
--format 'table {{.Names}}\t{{.Label "com.docker.compose.project"}}'
export COMPOSE_PROJECT_NAME='<project name shown above>'
export KEYCLOAK_COMPOSE_FILE=.devcontainer/docker-compose.yml
bash scripts/dev-keycloak-users.shThe script prints synthetic user credentials and the Keycloak client secret.
In the dev container, set Oidc__ClientSecret to that printed secret before
starting the backend. The default development authority is
http://localhost:8180/realms/subscribed-dev; if local configuration overrides
it, set Oidc__Authority to this value as well. The backend must use the same
authority for household initialization, since member identities include the
issuer. Follow backend/README.md to migrate the application database and
initialize a household for the synthetic user's subject. Restart the backend
after changing its environment. Do not commit the generated credentials.
The standalone deploy/compose.dev.yml offers the same realm and port; run
only one of the two Keycloak setups at a time.
Building the image and replacing the running dev container are separate, user-approved actions. A rebuild can end the sessions running in the current container.
The lockfile is .devcontainer/devcontainer-lock.json (the CLI derives the name
from devcontainer.json; there is no .devcontainer-lock.json). Generate it without rebuilding using the official CLI, then verify the image on
a Docker-capable host from the repository root:
npx --yes @devcontainers/cli@0.90.0 upgrade --workspace-folder .
npx --yes @devcontainers/cli@0.90.0 build --workspace-folder .
npx --yes @devcontainers/cli@0.90.0 build --workspace-folder . --frozen-lockfileInspect the diff afterwards. The only expected change is a new github-cli
entry. Reject any change to the existing agent feature resolutions. Do not delete
the lockfile or write hashes by hand.
Status: lockfile generation passed. Both image-build commands remain unrun because this session has no authorized Docker daemon access.
python3 -I -c 'import json, encodings, ssl, sqlite3'
dpkg -S /usr/lib/python3.12/json/__init__.py
python3 -m unittest discover -s tests -p 'test_agentic_flow.py' -v
git diff --check
git status --shortThese checks cover the Python fix and the workflow tests. They do not show that the image builds, which runtime versions are installed, whether the database is healthy, or whether Docker can connect.
From the repository root:
python3 -I -c 'import json, encodings, ssl, sqlite3'
dotnet --version # 11.0.100
node --version # v24.22.2
npm --version # 11.19.1
gh --version # 2.103.3
docker --version # 29.9.3
docker compose version # 5.7.0
claude --version
codex --version
copilot --version
docker compose --env-file .devcontainer/.env.example \
-f .devcontainer/docker-compose.yml config --no-env-resolution --quietEvery command must exit 0 and report the expected version. The Compose check
uses the sample file and --no-env-resolution, so it does not read or print the
private .env.
On the host, compare the project-prefixed PostgreSQL volume name and creation
timestamp before and after the rebuild. They must be unchanged, and the existing
db service must report healthy. If there is no access to a Docker daemon,
report host validation as blocked. That is not a pass.
The exact .NET and Node archives were downloaded, checksum-verified and executed
in an isolated temporary directory: SDK 11.0.100, Node v24.22.2 and npm
11.19.1 passed. Matching Docker CLI 29.9.3 and Compose 5.7.0 packages were
also executed without a daemon. The sample-only Compose validation above passed.
Dev Container CLI upgrade generated the tracked lockfile without changing the
three existing agent feature entries. These checks do not replace an image build.
The installed Codex CLI was missing codex-code-mode-host; the matching official
@openai/codex@0.167.1 npm distribution includes it. Its sandbox still requires
unprivileged user namespaces, which this running container does not permit.
Do not disable its sandbox or change host kernel policy automatically. Confirm
that the agent features provide all required execution binaries and that the
host permits the intended sandbox after rebuilding.