Skip to content

Add parallel dev-stack slots, PR checkout helper and fixtures - #143

Open
IanCou wants to merge 1 commit into
masterfrom
feat/parallel-dev-stacks
Open

IanCou wants to merge 1 commit into
masterfrom
feat/parallel-dev-stacks

Conversation

@IanCou

@IanCou IanCou commented Nov 14, 2026

Copy link
Copy Markdown
Collaborator

What

Run several independent People Portal dev stacks side by side, one per pull request, without touching the default ppdev stack.

  • Slots (up.sh --slot N / --pr N): each slot is its own Compose project (ppdev-sN), volumes, network, secrets and hostname (ppN.localhost), with a fixed port block 20000 + N*20 + offset and state under the gitignored dev-stack/slots/N/. Ports and hostname are forced by common.sh, so two slots can never collide.
  • scripts/pr.sh <n>: fetches pull/<n>/head into a detached worktree at ${PP_PR_DIR:-~/pp-pr}/<n>, installs deps with npm ci (lockfile-hash stamp, npm install --no-package-lock fallback, lockfile restored afterwards), brings the slot up, loads a fixture and starts the server and UI from the worktree on the slot's ports. --down [--purge] tears it down. Idempotent.
  • scripts/slot.sh: list, urls, server, ui, stop-apps, down [--purge], all accepting N or pr:N.
  • scripts/fixture.sh: save / load / check / list. Snapshots capture Mongo, the Authentik Postgres database and the Gitea volume; loading realigns the Authentik admin password and token, reapplies the blueprint for the target slot's redirect URIs, resets the Gitea admin and token, and retargets Gitea webhooks to the new portal port. fixtures/default is a committed, idempotent recipe (13 users, two teams, 10 applications; password portal-dev). fixture-check.py verifies every Mongo pk reference against Authentik.
  • Server: PEOPLEPORTAL_CORS_ORIGINS (comma separated, default unchanged) so a slot's UI origin can be allowed.
  • Docs: dev-stack/PARALLEL.md, fixtures/README.md, a "Parallel stacks" section in the dev-stack README.

Why

Reviewing or testing more than one PR at a time currently means tearing down and re-seeding the single stack. With slots, each PR gets a full, isolated environment with the same seeded data, reachable at its own ppN.localhost host so browser sessions don't clobber each other.

How to use

cd peopleportal/dev-stack
./scripts/pr.sh 123                 # worktree + deps + slot + default fixture + server + UI
./scripts/slot.sh list
./scripts/fixture.sh save mystate --slot 1 && ./scripts/fixture.sh load mystate --slot 2
./scripts/pr.sh 123 --down --purge  # containers, volumes, slot state and worktree

Gotchas

  • Each slot runs eight containers (roughly 1.5 to 2 GB); raise Docker's memory limit before running three or more.
  • Slot commands refuse slot 0; the default stack is still managed with docker compose stop / reset.sh.
  • PRs older than Add one-command local dev stack (authentik, Gitea, Mongo, Redis, Mailpit) and update local dev docs #105 lack the Vite PP_DEV_PORTAL_PORT override and would proxy /api to localhost:3000; pr.sh warns.
  • Saved snapshots contain generated secrets and are gitignored; only recipes are committed.
  • The scripts always run from this checkout's dev-stack; a PR that changes the stack itself has to be run from its own worktree.

How it was tested

  • Two open PRs (Grey out management controls for users without permissions (#94) #138 and Refresh the All RSVPs list after submitting an RSVP #116) brought up side by side with pr.sh: slots 1 and 2, 16 containers healthy, no overlapping listeners (lsof), default stack ports untouched.
  • Default fixture loaded into both: fixture.sh check reports 26 cross-service references, 0 orphaned; 10 applications and 15 Authentik users per slot.
  • Server and UI respond on both slots; the proxied /api/auth/login redirect carries each slot's own redirect_uri (ppN.localhost:<portal port>).
  • Headless OIDC login (Authentik flow executor API, then the portal callback and /api/auth/userinfo) succeeds for seeded users on both slots.
  • fixture.sh save test-snap --slot 1 then load test-snap --slot 2: a marker written in slot 1 appears in slot 2, Gitea webhooks retargeted, consistency check clean, logins still work in both slots afterwards.
  • pr.sh re-run on a running slot: worktree already at head, dependencies skipped, apps restarted. This surfaced a shutdown race in slot.sh stop-apps (fixed: it now waits for the process tree to exit).
  • pr.sh --down --purge for both PRs: containers, volumes, slot state, registry entries and worktrees removed.
  • bash -n and shellcheck on the scripts.

Each slot is an independent Compose project (ppdev-sN) with its own
ports, hostname (ppN.localhost), secrets and state under dev-stack/slots/N.
scripts/pr.sh checks a pull request out into a worktree and runs it on a
slot; slot.sh manages slots; fixture.sh saves, loads and checks complete
slot states, with fixtures/default as a committed seed recipe. The server
gains PEOPLEPORTAL_CORS_ORIGINS so a slot's UI origin can be allowed.
Documented in dev-stack/PARALLEL.md.
Copilot AI balanced review requested due to automatic review settings November 14, 2026 07:17

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants