Cross-cutting pattern doc follow-up from parachute-hub#260 / parachute-hub#262 (Phase 1A of v0.6 Render self-host arc).
What to capture
Two related conventions that just shipped in hub#262 are worth a pattern doc before Phase 1B builds on them:
Pattern 1 — Container-mode runtime module install
In container deploys (option A — see project_v06_single_container_hub_as_supervisor memory), modules are installed at runtime via the admin SPA rather than baked into the image. Key conventions:
- `BUN_INSTALL=/parachute/modules` env var pins bun's install target to the persistent disk path (not the ephemeral image layer).
- Hub's admin SPA exposes install/restart/upgrade/uninstall API on `/api/modules/*` (admin-scoped for destructive operations).
- Operation registry pattern for async ops: install/upgrade return `{ operation_id }` immediately, status polled via `GET /api/modules/operations/:id`.
- On container restart, hub reads services.json + re-spawns each registered module from `${BUN_INSTALL}/node_modules/@openparachute//`.
Pattern 2 — Hub-as-supervisor (attached children, restart-on-crash, log multiplex)
Locally hub spawns children detached (operator-driven lifecycle in `commands/lifecycle.ts`). In container mode, hub IS PID 1 — children must be attached to the hub process so OS shutdown propagates. Key conventions:
- Attached spawn (no `detached: true`, no `proc.unref()`).
- Line-buffered `[] ` prefix multiplex of child stdout/stderr to hub's stdout (so Render log viewer surfaces everything in one stream).
- Restart-on-crash with sliding-window budget (default: 3 crashes in 60s, then "given up" state surfaced to UI).
- Operator-stop is distinct from crash (`stopRequested` flag suppresses auto-restart).
- Test seams: injectable `now()`, `sleep()`, `spawnFn`, `killFn` for deterministic restart-window tests.
Cross-references
- parachute-hub#260 (issue body has full architecture sketch)
- parachute-hub#262 (PR implementing both patterns)
- project_v06_single_container_hub_as_supervisor (memory)
- Existing patterns/service-to-service-auth.md (operator bearer pattern complements supervisor)
Priority
Medium. Phase 1B work (hub#259 wizard, hub#260 follow-ups) will reference these conventions; the pattern should exist before they build on them.
Suggested file
`patterns/container-mode-module-install-and-supervision.md` — or split into two if they grow large enough to deserve separate docs.
Cross-cutting pattern doc follow-up from parachute-hub#260 / parachute-hub#262 (Phase 1A of v0.6 Render self-host arc).
What to capture
Two related conventions that just shipped in hub#262 are worth a pattern doc before Phase 1B builds on them:
Pattern 1 — Container-mode runtime module install
In container deploys (option A — see project_v06_single_container_hub_as_supervisor memory), modules are installed at runtime via the admin SPA rather than baked into the image. Key conventions:
Pattern 2 — Hub-as-supervisor (attached children, restart-on-crash, log multiplex)
Locally hub spawns children detached (operator-driven lifecycle in `commands/lifecycle.ts`). In container mode, hub IS PID 1 — children must be attached to the hub process so OS shutdown propagates. Key conventions:
Cross-references
Priority
Medium. Phase 1B work (hub#259 wizard, hub#260 follow-ups) will reference these conventions; the pattern should exist before they build on them.
Suggested file
`patterns/container-mode-module-install-and-supervision.md` — or split into two if they grow large enough to deserve separate docs.