Skip to content

installation.md

Latest commit

 

History

History
100 lines (68 loc) · 5.18 KB

installation.md

File metadata and controls

100 lines (68 loc) · 5.18 KB

Installation Instructions

Steps for setting up a local development environment.

If you get stuck, ask in the #civictechjobs-dev Slack channel or email Civictechjobs@hackforla.org. Pair-programming with an existing contributor is also an option.

Required downloads

  • Git: Windows / macOS / Linux
  • Docker Desktop (or Docker Engine on Linux): Windows / macOS / Linux
  • Node.js 24 LTS + npm: needed for the pre-commit JS hooks (ESLint / Stylelint / Prettier) that run on the host.
  • Python 3.13 + pre-commit: needed for the pre-commit framework itself plus its Python hooks (ruff).

For backend development outside Docker (rarely needed), also install Poetry.

Recommended editor setup

  • ESLint VS Code extension (marketplace): inline lint errors as you type.
  • Stylelint VS Code extension (marketplace): inline CSS Modules lint errors.
  • Prettier VS Code extension (marketplace): format-on-save; pairs with the pre-commit Prettier hook so your code is auto-formatted before commit. Use the equivalents for your editor of choice.
Note for macOS The macOS Git installer pulls in Homebrew, which can occupy several GB of disk space. If that's a problem, install a minimal Homebrew via Xcode Command Line Tools. Be aware Docker Desktop and the project's container images will also use a few GB; plan disk space accordingly.

Repository setup

  1. Fork the repository to your own GitHub account.
  2. Clone your fork locally.
  3. Add the upstream remote so you can pull updates from hackforla/CivicTechJobs.

Forking (instead of branching directly on hackforla/CivicTechJobs) is the standard HfLA contribution model; it keeps the canonical repo clean of in-progress branches and lets you experiment freely on your own copy.

Develop branches off develop, not main:

cd CivicTechJobs
git remote add upstream https://github.com/hackforla/CivicTechJobs.git
git fetch upstream develop
git checkout -b develop upstream/develop

main is what's deployed; develop is the integration branch where work merges before a release. See git-branch-structure.md for the branching model.

Running the app locally

  1. From the repo root, copy the dev env template:

    cp dev/dev.env.example dev/dev.env

  2. Edit dev/dev.env and fill in the placeholders (database name, secret key, etc.). The lines marked <...> need real values; the rest can stay as defaults.

  3. Start the full stack:

    docker compose up --watch

  4. Open the app:

docker compose up --watch enables hot reload; file edits in frontend/ or backend/ sync into the running containers automatically. Docker for local dev keeps the environment consistent across contributors (same Postgres version, same Node and Python versions inside the containers) without anyone needing a local Postgres install.

dev.env values

Variable What to put
POSTGRES_DB Any name (postgres works)
POSTGRES_USER Any username
POSTGRES_PASSWORD Any password
SECRET_KEY Random string of length 50; python -c "import secrets; print(secrets.token_urlsafe(50))" works
SQL_DATABASE Same as POSTGRES_DB
SQL_USER Same as POSTGRES_USER
SQL_PASSWORD Same as POSTGRES_PASSWORD

Local-dev auth

Stage 1 local dev runs Django's default session authentication; no Cognito, no PeopleDepot, no auth env vars needed beyond what's already in dev.env.example.

Bootstrap an admin / PM account with:

docker compose run django python manage.py createsuperuser

That account can sign into Django admin at http://localhost:8000/admin/ and is what you'll use to exercise PM-gated flows. Subsequent admin and PM elevations happen through Django admin's UI.

Stage 2 will introduce Cognito JWT verification and PeopleDepot client mocks; that work lands when the upstream PeopleDepot deployment posture stabilizes. See backend.md for the Stage 2 design.

Additional Resources