Dev workflow¶
Everyday commands. All driven by the project Makefile; under the hood they call systemctl --user on services symlinked from services/.
Services¶
| Service | Port | Notes |
|---|---|---|
danbyte-backend |
:8000 |
Django dev server |
danbyte-workers |
- | RQ worker (default + high + low queues) |
danbyte-fastlane |
- | The fast lane - sub-minute checks (make fastlane-logs) |
danbyte-mockups |
:8080 |
Static design mockup server (design/) |
danbyte-docs |
:8001 |
This documentation site (Zensical) |
danbyte-infra |
:5432/:6379 |
Postgres + Redis via docker compose (no-op if Docker isn't installed) |
The most common loop¶
# Restart after a code change (Django dev server auto-reloads, so this is rarely needed)
make backend-restart
# Re-seed demo data after a model change
.venv/bin/python manage.py seed_demo --wipe
# Build the DC-TEST hall for exercising the 3D room view: ten rows of ten
# cabinets in hot/cold pairs, A/B vertical PDUs stamped from a rack type,
# photo-faceplate gear, ~1100 cables, power feeds and overhead tray.
.venv/bin/python manage.py seed_dc_test --wipe
# Tail backend logs
make backend-logs
# Status of all services
make status
Reseeding from scratch¶
When the model changes in a way that's incompatible with the existing DB rows (e.g. new non-null FK), wipe and start over:
sudo -u postgres psql -c "DROP DATABASE danbyte;" \
&& sudo -u postgres psql -c "CREATE DATABASE danbyte OWNER danbyte;"
rm -f api/migrations/0001_initial.py api/migrations/0002_initial.py core/migrations/0001_initial.py
DB_HOST=127.0.0.1 DB_USER=danbyte DB_PASSWORD=danbyte DB_NAME=danbyte \
.venv/bin/python manage.py makemigrations core api
DB_HOST=127.0.0.1 DB_USER=danbyte DB_PASSWORD=danbyte DB_NAME=danbyte \
.venv/bin/python manage.py migrate
DB_HOST=127.0.0.1 DB_USER=danbyte DB_PASSWORD=danbyte DB_NAME=danbyte \
.venv/bin/python manage.py seed_demo
make backend-restart
Releases that need an operator step¶
When a change needs something on the host that no migration can do (a
reverse-proxy location, a volume, a package), add an UpgradeNote to
core/upgrade_notes.py in the same change: id, version, title, a short
body, the snippet to paste, the docs anchor, and the platforms it applies
to. Admins see it after upgrading until they mark it done - see
Upgrading → After an upgrade.
Cutting a release¶
Pushing a v* tag runs .github/workflows/release.yml:
test (tests.yml) ─┬─ bundle ─ smoke ─ publish GitHub Release + offline bundle
└─ images (container.yml) ghcr.io images
tests.yml is the one test gate: the backend suite, migrations and
makemigrations --check, the OpenAPI schema, and the frontend build,
typecheck and unit tests. Nothing publishes unless it passes, and it runs once
per tag. A manual run of the Container images workflow runs tests.yml
itself before it builds. ci.yml runs the same tests.yml on every pull
request and every push to main or a dev/** branch, so a failing test shows
up when the change lands, not on release day.
The backend suite runs as twelve parallel shard jobs, each
manage.py test --keepdb --parallel auto --shard K/16 on a copy of one test
database that the test-db job migrated once (applying the migration graph
takes about ten minutes). The test runner (danbyte/test_runner.py) cuts the
slices from the whole discovered suite at run time, one test module per
slice, balanced by the measured seconds in danbyte/test_timings.json. A new
test module needs no CI change: it lands in a slice with an estimated weight,
and the checks job's manage.py test --shard-check 12 fails unless every
test is in exactly one slice. When the shards drift apart, refresh the
weights with make test-timings, or from a CI run's test-timings-*
artifacts (one JSON of seconds per module per shard; merge them into one
file).
Locally, make test-fast runs the suite across every core
(--parallel auto; PARALLEL=<n> caps it, ARGS= passes labels or
--keepdb). Each worker gets its own test database and its own cache key
prefix.
After the tag, on the branch for the next release, record the release's migration state and commit it:
It rewrites scripts/upgrade/migration_baseline.json. The test
api.tests_upgrade_db_defaults then requires a db_default on every NOT NULL
column added to an existing table since that release, because the previous
release's processes keep inserting rows without it while an upgrade runs.
Use final releases only, not -devN tags. Skipping the step is safe but
stale: the gate keeps comparing with the older release.
Docs while you work¶
make docs-up # serves at http://localhost:8001
make docs-logs # tail
make docs-restart # if you edited zensical.toml
The docs hot-reload Markdown changes on save.