docs(website): Phase 2 PR 9 — the modules mount, and Phase 2 complete #134

wtclaude · 2026-08-11T05:51:07Z

wtclaude commented

2026-08-11 05:51:07 +00:00

Docs half of RunicGateway/website#136. Records the last Phase 2 PR and closes the phase.

§2.5 amended: a bind mount, not a named volume

The section said modules get "the same treatment uploads already gets", reaching for a named volume by analogy. The build settled it the other way, and the reason is in that same section: hand-placing a module directory is a supported install, and a named volume routes it through docker cp into a running container — the least discoverable mechanism Docker offers, for the one install path an operator without the admin panel has. Nothing else about install, uninstall or purge changes.

Two things the plan had not considered

Both are silent failures rather than errors, which is why they are written down:

The directory has to be tracked, because Docker recreates a missing bind-mount source as root:root and the container runs as uid 1000 — so deleting modules/ from a checkout breaks the next install with a permission error that names no cause.
.dockerignore has to exclude it, because COPY . . would bake a builder's checked-out module into every image, and Docker seeds a fresh named volume from image contents — so it could have surfaced on a deployment that never installed it.

Also

MODULE_API.md §4.1 gains the concrete Compose values, and states outright that a missing modules directory is not an error — the loader has always caught and returned, and the contract never said so.

The PR 9 entry records the container verification: the §7.7 browser smoke was re-run against the containerised stack rather than a working tree, and the negative case (directory removed by hand → startup_failed/require) confirms the §2.4 rule end to end.

Phase 2's exit criterion held: routes.manifest.json went 229 → 230 across the whole phase, and the one added line is PR 6's deliberate GET /api/v1/public/modules.

AI-assisted — Claude Code (Claude Opus 5)

🤖 Generated with Claude Code

https://claude.ai/code/session_018ocYxQWk3EhZe5gWRJXFU8

Docs half of RunicGateway/website#136. Records the last Phase 2 PR and closes the phase. ## §2.5 amended: a bind mount, not a named volume The section said modules get "the same treatment `uploads` already gets", reaching for a named volume by analogy. The build settled it the other way, and the reason is in that same section: **hand-placing a module directory is a supported install**, and a named volume routes it through `docker cp` into a running container — the least discoverable mechanism Docker offers, for the one install path an operator without the admin panel has. Nothing else about install, uninstall or purge changes. ## Two things the plan had not considered Both are silent failures rather than errors, which is why they are written down: - The directory has to be **tracked**, because Docker recreates a missing bind-mount source as `root:root` and the container runs as uid 1000 — so deleting `modules/` from a checkout breaks the next install with a permission error that names no cause. - `.dockerignore` has to **exclude** it, because `COPY . .` would bake a builder's checked-out module into every image, and Docker seeds a fresh named volume from image contents — so it could have surfaced on a deployment that never installed it. ## Also `MODULE_API.md` §4.1 gains the concrete Compose values, and states outright that **a missing modules directory is not an error** — the loader has always caught and returned, and the contract never said so. The PR 9 entry records the container verification: the §7.7 browser smoke was re-run against the containerised stack rather than a working tree, and the negative case (directory removed by hand → `startup_failed`/`require`) confirms the §2.4 rule end to end. Phase 2's exit criterion held: `routes.manifest.json` went 229 → 230 across the whole phase, and the one added line is PR 6's deliberate `GET /api/v1/public/modules`. --- - [x] AI-assisted — Claude Code (Claude Opus 5) 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_018ocYxQWk3EhZe5gWRJXFU8

wtclaude added 1 commit 2026-08-11 05:51:09 +00:00

docs(website): Phase 2 PR 9 — the modules mount, and Phase 2 complete 8a7b099c2d

Records the last Phase 2 PR and closes the phase.

Amends §2.5: the mount is a bind mount of ./modules, not the named volume the
section reached for by analogy with uploads. Hand-placing a module directory is
a supported install in that same section, and a named volume routes it through
`docker cp` — the least discoverable mechanism Docker offers, for the one
install path an operator without the admin panel has.

Two things the build settled that the plan had not considered, both silent
failures rather than errors: the directory has to be tracked, because Docker
recreates a missing bind-mount source as root-owned and the container is uid
1000; and .dockerignore has to exclude it, because COPY . . would otherwise bake
a builder's checked-out module into every image — and Docker seeds a fresh named
volume from image contents, so it could have surfaced on a deployment that never
installed it.

MODULE_API §4.1 gains the concrete Compose values and states outright that a
missing modules directory is not an error, which the loader has always done and
the contract never said.

Website side: RunicGateway/website#136.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech merged commit 12e4eaad10 into main

2026-08-11 05:58:00 +00:00

whitlocktech deleted branch docs/module-compose-volume

2026-08-11 05:58:01 +00:00

whitlocktech referenced this issue from a commit

2026-08-11 05:58:02 +00:00

Merge pull request 'docs(website): Phase 2 PR 9 — the modules mount, and Phase 2 complete' (#134) from docs/module-compose-volume into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#134