Skip to content

Add local setup documentation for backend, admin portal, and website #40

Description

@nora-weisser

Goal

Add setup documentation so a newcomer can get every part of the platform running locally: the backend, the admin portal (frontend), and the community website (frontend). Group these guides under a dedicated docs/ folder so setup instructions have one clear home.

Scope

Create a docs/ folder at the repo root with a short index plus one setup guide per component:

  • docs/README.md — index linking to each setup guide and giving a one-line description of each component and which repository it lives in.
  • docs/setup-backend.md — how to run the WCC backend (wcc-backend): prerequisites (Java 21, Docker), start PostgreSQL, run the Spring Boot app, API key / auth basics, Swagger UI URL, and how the QA suite points at it via tests/.env.
  • docs/setup-admin-portal.md — how to run the admin portal frontend (Next.js admin-wcc-app): npm installnpm run dev, required NEXT_PUBLIC_* env vars, default local admin credentials, and how it connects to the backend.
  • docs/setup-website.md — how to run the community website frontend (WomenCodingCommunity.github.io): prerequisites, install, and local serve command.

Each guide should:

  • Link out to the source repository rather than duplicating its full README — keep instructions QA-focused (what a tester needs to stand the environment up).
  • Note any environment variables and where to obtain values, reminding that real credentials must never be committed.
  • Include a quick "verify it's running" step (health endpoint / URL to open).

Acceptance criteria

  • docs/ folder exists at the repo root with an index (docs/README.md)
  • Separate setup guides exist for backend, admin portal, and website
  • Each guide links to its source repository and lists prerequisites, install/run steps, and a verification step
  • Env-var handling notes that real credentials must never be committed
  • All added links resolve
  • CONTRIBUTING.md / README.md reference the new docs/ folder (coordinate with Add CONTRIBUTING.md #22 and Add Contributing + Community sections to README.md #24)

Part of the open-source readiness epic (#33).

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions