[IanCou]

Adds a local People Portal development stack based on the version that passed the complete from-ZIP restore, service verification and persistence test. Contributors can bootstrap Authentik, Gitea, MongoDB, Redis, Postgres and Mailpit locally, then run the portal and UI through the existing Nx wrapper.

• Uses conventional default ports: portal 3000, UI 5173, MongoDB 27017, Redis 6379, Authentik 9000, Gitea 3001, Gitea SSH 2222, Mailpit 8025 and SMTP 1025. Docker publishes only on 127.0.0.1; Postgres stays internal.
• Keeps every host port configurable. Up and verify print selected ports. Startup checks IPv4/IPv6 loopback availability before Compose up and names the exact override variable when a port is busy. Existing running services in the selected Compose project are accepted.
• Generates private local credentials once, reconciles Authentik/Gitea, preserves existing server/UI env files, and provides project-scoped reset plus 16 backing-service smoke checks.
• Removes the unfinished S3 service and bootstrap. Updates contributor, environment and local development documentation, including the existing master-based branching and PR wording from the tested copy.
• Changes only peopleportal/webui/vite.config.ts outside the dev-stack/docs scope. It reads PP_DEV_PORTAL_PORT and PP_DEV_WEBUI_PORT from the UI environment. With neither variable set, its resolved config equals origin/master: /api targets http://localhost:3000, Vite defaults to 5173, and there is no host or strictPort override. An explicit UI port enables strictPort. The env renderer emits each PP_DEV_* variable only for a non-default port; --write-env also creates webui/.env.development.local with those overrides if absent.
• No dependency or package-lock changes, generated credentials, bundled dependencies or machine-specific paths are included.

How to try it

Requirements: Docker with Compose v2.20+, Bash, curl, OpenSSL, Python 3.9+ for the port preflight, and Node.js 22.12+ with npm for the host applications. Windows requires WSL2 with Docker integration; run the commands inside WSL2.

From a fresh clone:

cd peopleportal/dev-stack
./scripts/up.sh --write-env
cd ../..
./nx serve pplserver
# In another terminal at the repository root:
./nx serve pplui

Open http://localhost:5173 and sign in as akadmin with AUTHENTIK_BOOTSTRAP_PASSWORD from peopleportal/dev-stack/.env. Mail appears at http://localhost:8025. Keep the generated env output private.

If a port is busy, export its override before first setup, for example PORTAL_PORT=3100, WEBUI_PORT=5174, GITEA_PORT=3101 or REDIS_PORT=6380. For later changes, stop this project's services and the host applications, edit dev-stack/.env, clear the corresponding derived URL, and rerun setup. Existing env files are preserved, so update them from the printed output. The README lists every exact variable and explains how to remove stale UI overrides when returning to defaults.

From peopleportal/dev-stack, use ./scripts/verify.sh for service checks, docker compose stop to preserve data, and ./scripts/reset.sh for a confirmed deletion of only this project's service data. Reset changes the Gitea token on the next bootstrap; update the server env afterward.

Validation in this worktree

• shellcheck -x and bash -n pass on all eight shell scripts.
• docker compose config --quiet passes with throwaway settings for both the default configuration and --profile '*'. The stack defines no optional profiles. Resolved config assertions confirm eight services, seven named volumes, expected default ports, loopback-only Docker publications and no S3 service.
• python3 -m py_compile passes for all three Python helpers, with bytecode written outside the repository.
• Temporary fixture checks cover default, backend-only, UI-only and combined env overrides, mode 600 files and preservation of existing server/UI env files.
• Port checks cover free ports, occupied IPv4/IPv6 ports and ports belonging to this project's running containers. A mocked Docker invocation proves up.sh fails on an occupied portal port before Compose up/bootstrap, names PORTAL_PORT and releases its lock.
• The Vite config was evaluated with the existing Vite loadEnv implementation and compared to origin/master. Default config equality and file/process overrides pass. No Vite server was started and no dependencies were installed or copied.
• git diff --check, including separate whitespace checks for new files, passes. Hex/base64 token and literal-password scans report no findings. Scans also find no machine-specific user paths, homelab references, old high-port defaults or references to the removed storage service.
• Git status contains only the intended five docs, dev-stack files and Vite config. Package locks are unchanged. No commit or push was made.

The Docker stack and host applications were deliberately not run in this worktree. Runtime verification of these contributor-facing port and env changes remains for the fresh-clone test. The earlier successful from-ZIP test establishes the copied base's runtime provenance, not a new runtime result for these adaptations. Browser OIDC login/logout is also outside the smoke checks.

Known gaps

• S3 storage is absent, so resume/avatar uploads fail. Garage, SeaweedFS and versitygw are candidates for follow-up evaluation; none is promised. S3 settings remain dummy placeholders. The server currently ignores S3_ENDPOINT, S3_FORCE_PATH_STYLE and AWS_ENABLED=false, so adding storage alone will not wire uploads.
• AWS provisioning, Organizations/Budgets, Slack actions and other external integrations are unsupported locally. Dummy settings satisfy startup checks only. Do not enable AWS provisioning on local teams. Discord and photo checks remain disabled.
• Windows requires WSL2. Native Windows shell support is not provided. Docker, Python, Node.js and npm are prerequisites rather than bundled tools.

Notes for reviewers

• The old manual setup instructions are kept at the bottom of local-development.md under "Manual setup (without the dev stack)", with headings demoted one level.
• The dev stack's default GITEA_PORT (3001) matches the pinned port of the wiki dev server (npm start in corpwiki/). The guide notes to set GITEA_PORT=3002 if both run.
• Windows is documented as WSL2 only.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.