FastAPI backend and React frontend behind Caddy. Every merge to main deploys to one VM.
browser --> Caddy (web) --+-- /api/* --> backend:8000 (FastAPI)
|
+-- else ----> /srv (React build)
Needs uv, Node 22 and Docker.
| Command | What it does |
|---|---|
make setup |
Install backend and frontend deps |
make check |
Lint, format, tests, types, build, infra (as CI) |
make fmt |
Format and autofix all code |
make dev-be |
Backend on http://localhost:8000 with reload |
make dev-fe |
Frontend on http://localhost:5173, proxies /api |
make up |
Full stack in Docker on http://localhost |
make down |
Stop the Docker stack |
- Work on a branch and open a PR. No direct push to
main. - Run
make checkbefore every push. - Every merge to
maindeploys. Merge only what works. - Backend routes live only under
/api. - The frontend calls the API only from
src/api.ts. - Secrets live only in the server
.env. Never commit them. - Before the demo, set the repo variable
DEPLOY_FROZEN=trueto stop deploys. - Follow the code rules in CONTRIBUTING.md.
PR ---------> backend (ruff, pytest)
frontend (tsc, oxlint, prettier, build)
infra (actionlint, shellcheck)
push main --> backend + frontend + infra --> images --> deploy
| |
| +- scp compose file + deploy.sh
| +- ssh: deploy.sh <sha>
| healthy: keep, save tag
| unhealthy: roll back to last good tag
+- push ghcr.io/<owner>/<repo>/{backend,web}:<sha>
deploy is skipped when the repo variable DEPLOY_FROZEN is true.
- Install Docker with the compose plugin.
- Open ports 80 and 443.
- Make a deploy user that can run
docker, and add the public half of an SSH key to its~/.ssh/authorized_keys. - Make the deploy folder, for example
/opt/junction, and put.envin it (see.env.example). SetSITE_ADDRESSto the domain to get HTTPS, and point the DNS A record to the VM.
- Settings > Environments: create
production. - Settings > Secrets and variables > Actions, add secrets:
DEPLOY_HOST: VM IP or host nameDEPLOY_USER: deploy userDEPLOY_SSH_KEY: private half of the SSH keyDEPLOY_PATH: deploy folder, for example/opt/junction
- Variables:
DEPLOY_FROZENset tofalse(settrueto freeze). - Branch protection on
main: require PR and thebackend,frontendandinfrachecks. Private repos need a paid plan for this. "Use this template" does not copy it, so set it again in each new repo.