docs: make the documented local setup match what the project does

[dmccoystephenson]

Summary

Three documentation inaccuracies were found during triage, all on the path a new contributor follows to run this project locally. All three are fixed here; no application code is touched.

• JWT_SECRET was undocumented outside dpc-api/README.md. compose.yml declares it as ${JWT_SECRET:?...}, which aborts docker compose up — and therefore ./up.sh — when it is unset. README.md's Docker Compose setup step and CONTRIBUTING.md's docker compose up line both told the reader to run those commands bare, so the first command a new contributor ran failed, with the explanation living in a file the root README.md did not link. A JWT_SECRET entry has been added to CONFIG.md's Environment Variables section (required, no default, min 32 bytes, a runtime secret rather than a build-time inline), and both commands now set it (JWT_SECRET is required to start the stack but is documented nowhere in the root docs #290).
• CONFIG.md pointed Docker Compose users at .env.local. Compose resolves ${VAR} from the shell or from .env; it does not read .env.local, and Dockerfile copies no env file into the website image, so that instruction had no effect on a Compose run. The Environment Variables section now carries a small table naming which file each path actually reads, and the Docker Compose Configuration section documents .env. Since that file is now where JWT_SECRET goes, .env has been added to .gitignore — .env*.local was ignored, but a bare .env was not (CONFIG.md points Docker Compose users at .env.local, a file Compose never reads #289).
• README.md omitted dpc-api and mislabelled the Compose stack. The repository holds a Spring Boot back end that .github/workflows/build.yml builds with ./mvnw verify -B under Java 17 and that compose.yml runs, yet the README described the project as a Next.js application alone, listed Node.js as the only prerequisite, and linked every doc except dpc-api/README.md. Its Compose section was also headed "Test Server with Hot-Reloading", which that stack is not: Dockerfile runs npm run build and starts next start, and the service mounts no source volume, so an edit needs a rebuild. npm run dev — previously the afterthought below it — is now named as the hot-reloading path (README omits the dpc-api backend entirely, and calls the Compose stack hot-reloading when it is a production build #291).

Test plan

• Every claim was verified against source at 63b8c7a: compose.yml (the ${JWT_SECRET:?...} declaration, the five services and which ports are published), Dockerfile (the COPY list, RUN npm run build, CMD npm run start), .github/workflows/build.yml (the build-api job), .gitignore, and dpc-api/README.md (the DPC_SYNC_* table the new cross-reference points at).
• Both new intra-repo links were checked: CONFIG.md#jwt_secret resolves to the new ### JWT_SECRET heading, and dpc-api/README.md exists.
• npm run lint, npm test and npm run build were not run locally — no Node.js runtime is available in the environment this was prepared in. The diff is Markdown and .gitignore only, so none of those checks covers a changed file; CI on this PR's head SHA remains the authoritative signal and must be green before merge.

Closes #289
Closes #290
Closes #291

Deferred this cycle

• up.sh/down.sh call the retired docker-compose v1 binary and have a commented-out shebang #292 (up.sh/down.sh call the retired docker-compose v1 binary and have a commented-out shebang) was filed during the same triage but left out deliberately: it changes executable scripts whose verification needs a real Docker run, which neither CI nor this environment provides, whereas everything here is documentation.
• The remaining open backlog — Pull discord server announcements into News page as posts #24, Add nginx proxy to compose.yml to allow TLS #57, Allow editing the plugin cards data JSON file from the website #87, Discord announcements persist on the News page after being deleted on Discord #142, Plugin cards show no version or Minecraft-version compatibility — server owners' first question #162, Epic: community profiles via UserAuth — log in, like plugins/guides, and a social layer #167, Plugin reviews + ratings, with moderation (#167 Phase 3) #192–Notifications for replies and likes (#167 Phase 3) #196, Epic: turn the plugin catalogue into a resource hub #271, Discussion threads on resource pages, with reporting and moderation (#271 Phase 4) #274–Catalogue discovery: tags, categories, and Minecraft-version filters (#271 Phase 6) #276, Per-plugin install reporting, so a review can be marked verified (#271 prerequisite) #278, dpc-api: issue revocable MCP access tokens tied to a UserAuth account #280–Add a knowledge-base section backed by the DPC Zettelkasten #282 — is untouched. Those are epics or multi-phase features well beyond a documentation-sized change, and several are gated on work that has not shipped (Discord announcements persist on the News page after being deleted on Discord #142 depends on Pull discord server announcements into News page as posts #24; Per-plugin install reporting, so a review can be marked verified (#271 prerequisite) #278 on an install signal dpc-api does not receive).

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Review

Reviewed at head 1c3dc22, with both required checks passing (Build Website (Node.js), Build & Test API (Java)). Every factual claim in the diff was checked against compose.yml, Dockerfile, .github/workflows/build.yml, up.sh/down.sh, .gitignore and dpc-api/.

Findings (all four addressed in 1c3dc22)

• README.md:112 — medium. The Docker Compose setup steps were self-contained (Docker Desktop → JWT_SECRET → ./up.sh), and the new intro says front-end work needs only Node.js, so the Compose path could be followed without ever running npm install. compose.yml bind-mounts ./node_modules:/app/node_modules; on a fresh clone that host directory does not exist, Docker creates it empty, and it shadows the node_modules the image installed — so CMD npm run start fails with next: not found in a restart: always loop despite a clean image build. An npm install step and the reason for it were added.
• CONFIG.md:11 — low. The env-file table asserted the two run paths "read different files" and mapped the npm path to .env.local alone. Next.js also loads a plain .env (with .env.local taking precedence), so the very file this change tells Compose users to create is read by npm run build too — a .env holding NEXT_PUBLIC_BASE_URL=http://localhost:3000 would silently inline a localhost origin into a production bundle's canonical URLs, og:image and sitemap. The table now lists both files, states the precedence, and warns about that overlap.
• CONTRIBUTING.md:79 — low. The manual-testing command was docker compose up with no --build, while the same change establishes elsewhere that the website image copies source in at build time with no source volume. A contributor with a cached image would have tested stale code and seen none of their edits. --build was added, and CONFIG.md's Compose section now says the same thing explicitly.
• README.md:39 — low. The heading "Docker Compose (Recommended for Development)" was left untouched under Installation while the section it points at was rewritten to say that stack is a production build which does not hot-reload — steering a skimming reader to Compose as the recommended development workflow, the same mislabelling README omits the dpc-api backend entirely, and calls the Compose stack hot-reloading when it is a production build #291 set out to remove. Retitled, and it now names both paths.

Rubric

• Scope: PASS — the diff is five documentation files plus one .gitignore line. The .gitignore addition is not incidental: this change is what makes .env the documented home for JWT_SECRET, and .env*.local did not cover a bare .env, so a secret would have been committable. No formatting churn or unrelated edits.
• Tests-new: N/A — no functions were added. Each claim was traced to the file that determines it, listed in the PR body's test plan.
• Tests-fix: N/A — this fixes documentation, not behaviour. There is no code path to revert, so the stash-and-run check does not apply. The corresponding evidence is that each corrected statement contradicts a specific line of source, cited above and in the PR body.
• Sibling structure: PASS — the new ### JWT_SECRET entry follows the Type/Default/Description/Example shape of the two entries above it, and the new ### Backend (dpc-api/) heading in README.md matches CONTRIBUTING.md's.
• Sibling renames: PASS — README.md's Development subsections were renamed as a pair, and the Installation cross-reference that pointed at the old name was updated in 1c3dc22.
• Docs: PASS — CHANGELOG.md carries entries under [Unreleased] → Changed; CONFIG.md, README.md and CONTRIBUTING.md are the subject of the change. USER_GUIDE.md needs nothing: it documents site navigation for visitors, not local setup.
• Issue resolution: PASS — CONFIG.md points Docker Compose users at .env.local, a file Compose never reads #289 (.env.local under Docker Compose, plus the .gitignore follow-on it names), JWT_SECRET is required to start the stack but is documented nowhere in the root docs #290 (JWT_SECRET in CONFIG.md, README.md and CONTRIBUTING.md) and README omits the dpc-api backend entirely, and calls the Compose stack hot-reloading when it is a production build #291 (dpc-api in the description, prerequisites, documentation list and testing section; the hot-reloading heading) each have their named surface area changed in full.
• no-any / mui-only / env-vars-documented: N/A — no .ts or .tsx file is touched. JWT_SECRET is not read by this application's code at all; it is a Compose-level variable consumed by UserAuth, and it is now documented in CONFIG.md regardless.
• CI: PASS — both required checks pass on 1c3dc22.

Caveat on verification

npm run lint, npm test and npm run build could not be run where this was prepared: no Node.js runtime is present. That is recorded as UNVERIFIED-not-applicable rather than treated as green — the diff contains no file any of those three commands inspects, and CI ran all three on this head anyway. The one thing genuinely outside any automated coverage is the npm install / --build / JWT_SECRET sequence itself, which needs Docker to exercise; the failure modes behind those steps were derived from compose.yml and Dockerfile rather than observed, so a real ./up.sh on a fresh clone would be the confirming test.

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson