Backend Development - macOS Development Environment Setup¶
This guide prepares a macOS 15+ machine to develop this project. It covers required tools and cloning the repo, and stops before make build. You can finish by running make help to see available commands.
Works on Apple Silicon (M1–M4) and Intel Macs.
1) System prerequisites¶
- Admin rights on your Mac (needed to install software).
- macOS 15+.
1.1 Install Xcode Command Line Tools¶
Provides git, make, and compilers used by some tooling.
xcode-select --install
If they’re already installed, macOS will tell you.
2) Install Docker Desktop (includes Docker Compose v2)¶
Install the macOS app from Docker’s official instructions:
After installation, launch Docker Desktop (Applications or Spotlight) and wait until it shows “Docker Desktop is running”.
Verify Docker + Compose:
docker --version
docker compose version
3) Clone the repository¶
Choose HTTPS or SSH and clone to a directory you own (so Docker can bind-mount):
# HTTPS (example)
git clone https://github.com/<your-org>/<your-repo>.git
cd <your-repo>
# or SSH (example)
git clone git@github.com:<your-org>/<your-repo>.git
cd <your-repo>
If you use SSH and haven’t set up keys on your Mac/GitHub yet, do that first in your GitHub account settings.
4) Prepare your environment file¶
For local development we use a .env file in the repo root. Start from the example and edit:
# WARNING: overwrites any existing .env (press 'y' to confirm)
make env
This copies env.dev.example → .env and opens it in nano. At minimum, review and adjust:
- Django & tokens:
SECRET_KEY,JWT_SIGNING_KEY,HEALTH_CHECK_TOKEN,OTEL_WRITE_TOKEN(For local dev, any long random strings are fine.) - Postgres:
POSTGRES_USER,POSTGRES_PASSWORD,POSTGRES_DB - Grafana DB user password:
GF_DATABASE_PASSWORD - Domains (local):
DOMAIN_NAME=localhost,ADMIN_DOMAIN=admin.localhost,PORTAL_DOMAIN=portal.localhost(already set) - Docs variables (optional for dev):
GH_REPOS,GH_PAT, etc., only if you plan to build docs locally.
You’ll also see values like
change-me-in-productionin the example; they can remain placeholders for local dev unless you specifically need those features.
Do not run the secret-generating make targets yet (e.g., make dj-secret, make token-32, make token-64)—they use containers and imply building images. Generate secrets later, after you’ve built.
5) Explore available project commands¶
You’re now set up to continue with the runtime guide. As a last step here, list Make targets:
make help
This prints all supported commands (build, up, logs, Django helpers, linting, docs build trigger, etc.). Use your separate run guide for the next steps (e.g., make build, make up, migrations, etc.).
(Optional) Install a code editor¶
Pick your editor of choice (VS Code, PyCharm, etc.). This project includes docker-compose.pycharm.yml if you prefer PyCharm’s Docker interpreter. An editor is optional for the setup above.