Skip to main content

project-devcontainer-toolbox

The authoritative description of this repository. Framework docs (WORKFLOW.md, PLANS.md, GIT.md, …) are copied unmodified from the fleet template and yield to this file when they disagree.

What this repo is​

DevContainer Toolbox (DCT): a pre-built, multi-arch dev container image plus a one-line installer that gives any project a consistent development environment on Windows, Mac and Linux. Users install languages, frameworks and cloud tools on demand with dev-setup, and keep the container current with dev-update. The documentation site is published at dct.sovereignsky.no.

What it builds / does not build​

  • Builds:
    • the container image (image/Dockerfile, image/entrypoint.sh), published to ghcr.io/helpers-no/devcontainer-toolbox
    • the install, config and service scripts in .devcontainer/additions/
    • the in-container dev-* commands in .devcontainer/manage/
    • the host installers install.sh / install.ps1 and the host commands in host-tools/ (dct-init, dct-exec, dct-find-container). Every dct-* command is installed by the install scripts (Terje, 2026-09-25)
    • the Docusaurus site in website/
  • Does not build:
    • the project templates or the AI workflow templates that dev-template installs. Those live in helpers-no/dev-templates and are downloaded at run time.
    • UIS (the local infrastructure stack). uis inside DCT is a shim that forwards to the UIS container; UIS itself is another project.

Layout​

  • image/ — Dockerfile and entrypoint for the published image
  • .devcontainer/additions/ — install-*.sh, config-*.sh, service-*.sh, their lib/ and tests/
  • .devcontainer/manage/ — dev-* commands and shared lib/
  • host-tools/ — scripts that run on the host, not in the container
  • website/ — Docusaurus site; all documentation is under website/docs/
  • This ai-developer/ folder lives at website/docs/ai-developer/. There is no second copy. It is published on the public site.
  • version.txt — the release version

Repo-specific AI-developer docs​

These are not template concerns, and are kept beside the portable docs:

Commands​

Run inside the devcontainer; the repo is mounted at /workspace.

# Script tests (CI runs the same suite and rejects failing PRs)
.devcontainer/additions/tests/run-all-tests.sh static <script>

# Docs site
cd /workspace/website && npm run start -- --host 0.0.0.0   # dev server
cd /workspace/website && npm run build                      # full build, validates every link

Tool pages are generated by dev-docs. Do not edit tools/index.mdx by hand. CI regenerates the docs after a merge (CI/CD pipeline).

Git host​

GitHub. origin is https://github.com/helpers-no/devcontainer-toolbox. The gh operations in GIT.md apply; AZURE-DEVOPS.md does not.

Devcontainer​

DEVCONTAINER.md applies. This repo is also the product it describes: DCT is developed inside DCT, so a change to the image or to .devcontainer/ affects the environment you are working in only after a rebuild.

Contracts (non-negotiable)​

  1. Never commit directly to main. Every change goes through a feature branch, a PR and a merge, followed by git pull on main and deleting the local branch. Ask before each commit, push and merge. Multi-phase plans commit per phase on one branch and open the PR once.
  2. Version bump before every push or PR. Ask: "Should we bump the version for this change?" If yes, update version.txt — PATCH for fixes and small improvements, MINOR for features and documentation improvements, MAJOR for breaking changes. Users running dev-update only see a change when the version changes. See Releasing.
  3. Docs build check before pushing any change to website/docs/, and always after deleting, moving or renaming a file (including moving plans between backlog/, active/ and completed/). Run npm run build in /workspace/website. Docusaurus validates every internal link, and a broken link fails the Deploy Documentation workflow.
  4. Script tests must pass before committing a script change. CI rejects PRs with failing tests.
  5. Public repository and public site. Everything here is world-readable. No hostnames, IPs, internal topology, credentials or runtime identifiers, in code, docs or plans.
  6. Plans are worked phase by phase. Update the plan file as you go, and stop for the user's confirmation after each phase (see the repo-root CLAUDE.md).

Always-loaded files​

URB fleet​

  • Agent id: devcontainer-toolbox
  • Inbox: ~/.local/bin/urb inbox --id devcontainer-toolbox — open issues labelled to:devcontainer-toolbox in terchris/urb-agents (a query, not a directory)
  • Do not clone urb-agents. Do not copy protocol/ here.

Other documentation​