Deploy with Docker / Podman¶
Danbyte ships a production container stack - Postgres, Redis, the Django backend (gunicorn), a separate WebSocket process (daphne), a background worker pool, and nginx serving the built SPA. It runs the same way under Docker and Podman. (Addresses issue #19.)
Bare metal vs containers
For a single VM, the Installation script (systemd units + host nginx) is still the smoothest path. Containers suit hosts where you already run Docker/Podman, or an orchestrator.
Quick start¶
Edit .env - at minimum set the two secrets and the DB password. Generate each
secret with:
Then bring the stack up:
The backend container runs migrations, the idempotent bootstrap, and
collectstatic on first start, then serves. When the web container is healthy,
open http://localhost:8080 (the HTTP_PORT you set).
Create the first admin (or set the DJANGO_SUPERUSER_* vars in .env and the
matching lines in the compose file to have bootstrap do it):
What runs¶
| Service | Image / stage | Role |
|---|---|---|
postgres |
postgres:17 |
Database (named volume postgres_data), from ECR Public |
redis |
redis:7 |
Queues + channels layer, from ECR Public |
backend |
app (runtime) |
gunicorn WSGI + one-time migrate/bootstrap/static |
ws |
app (runtime) |
daphne ASGI - WebSockets only |
workers |
app (runtime) |
rqworker-pool (RQ_WORKERS processes; ICMP-capable) |
scheduler |
app (runtime) |
the periodic beat - the container's systemd timers |
frontend |
node (frontend) |
the SPA server (vite preview) - SSR build |
web |
nginx (web) |
proxies the SPA + /api /ws, serves /assets /static /media; HTTP :80 + HTTPS :443 |
WebSockets run as a separate daphne process, never channels-in-runserver -
putting ASGI in front of all HTTP wedges plain requests. The frontend is a
TanStack Start SSR build, so web proxies the pages to the frontend node
server. The build's hashed files under /assets/ are copied into the web
image from the same build and served by nginx, cached for a year as
immutable and sent as the .gz the build writes. Build web and frontend
together (docker compose build does); an asset the web image lacks still
comes from the frontend server, uncached. Collected static and uploaded media
live on shared volumes the backend writes and nginx serves.
The scheduler¶
Nothing in Danbyte polls on its own: the checks, digests, discovery and
retention all have to be triggered. A bare-metal install gets that from
systemd timers; a container has no init, so the scheduler service runs one
process that reads the same table (core/schedule.py) and calls the same
management commands. Without it the stack looks configured and measures
nothing - assignments never expand into checks, so nothing ever dispatches and
every check sits there having never reported.
What it runs, at the same cadence as the timers:
| Cadence | Work |
|---|---|
| every minute | dispatch due checks, SNMP drift, Outpost work, alert escalation |
| every 5 min | materialise check assignments, discover subnets |
| every 15/30 min | prefix utilisation, hardware health |
| daily | ACME renewal, retention, stale-IP cleanup, flow requirement sweep, link check, certificate expiry, digest |
manage.py run_scheduler --list prints the table. Auto-upgrade is the one timer
a container does not run: the image is the unit of upgrade, so you deploy a
new tag instead.
Occurrences are claimed in Redis, so restarting the container will not re-send this morning's digest and a second replica cannot double-send it. Keep it to one replica anyway - it buys nothing.
To run one pass by hand (a cron-driven install, or when debugging):
ICMP¶
The worker container sets net.ipv4.ping_group_range so the ICMP monitor's
unprivileged pings work - icmplib opens datagram sockets, which is cheaper
than running as root or granting NET_RAW. Podman honours the sysctl too.
Unprivileged LXC containers cannot set this
Inside an unprivileged LXC (Proxmox and friends), writing
net.ipv4.ping_group_range fails with EIO even in the container's own
network namespace, so Docker refuses to start the worker or the sysctl
silently does not apply. ICMP checks then report unknown rather than
up/down, because the socket cannot be opened at all. Run the Docker host in
a privileged LXC or on a VM/bare metal, or use a TCP/HTTP check instead of
ICMP for those targets.
Script sandbox¶
The image includes bubblewrap, which puts each sandboxed
script in its
own namespaces. Docker's default seccomp profile refuses the user
namespaces it needs, and on an AppArmor host the docker-default profile
refuses its mounts. So in a stock stack scripts run under Landlock and
Danbyte's seccomp filter alone, the 0.17 level, and each run log says
Sandbox: bubblewrap is not used - No permissions to create a new
namespace….
To add the namespaces, relax both profiles on the workers service only
(the lines are in docker-compose.prod.yml, commented out):
That trades the container's own seccomp and AppArmor policy on the worker for per-run namespaces; scripts keep Landlock and Danbyte's filter either way. A host without AppArmor needs only the seccomp line. Tested with Docker 29; Podman is untested.
Scripts and the API¶
A script's SDK calls the API at DANBYTE_INTERNAL_URL. Nothing listens on
127.0.0.1:8000 inside the workers container, so the compose file sets it
to the backend service, http://backend:8000, for every app service. The
backend accepts that one extra host name: a set DANBYTE_INTERNAL_URL adds
its host to ALLOWED_HOSTS, and only there; WebSocket origins and the
site's public name still come from your ALLOWED_HOSTS. Override it in
.env only if the backend service is named differently.
DWG drawings¶
The image includes LibreDWG's dwg2dxf, so
floor-plan drawings take DWG as
well as DXF with nothing to install: DANBYTE_CAD_CONVERTER is set to
/usr/local/bin/dwg2dxf in the image. Debian does not package LibreDWG, so
the cad-tools stage of the Dockerfile builds it on Alpine with
deploy/cad/build-dwg2dxf.sh, from the GNU release pinned to one version and
its SHA-256, linked statically; only that binary reaches the runtime image.
The release bundle carries the same build (target cad-dist). The build
fetches the tarball from ftp.gnu.org; a build host without it passes
another GNU mirror as --build-arg GNU_MIRROR=….
LibreDWG is GPLv3. Danbyte does not link it: the worker runs dwg2dxf as a
separate program for each upload, and the image carries LibreDWG's licence
and a notice naming its source at /usr/share/doc/libredwg/. To leave DWG
off, set DANBYTE_CAD_CONVERTER=off in the services' environment.
The converter only runs in the bubblewrap sandbox (no network, no app
directory, .env or media; see
DANBYTE_CAD_SANDBOX),
and the image's bubblewrap meets the same Docker profiles as the
script sandbox. In a stock stack a DWG drawing therefore
fails with …this server cannot build one: No permissions to create a new
namespace…, and the upload form then refuses DWG with the same reason;
DXF works. To take DWG, relax the profiles on the
workers service as shown there. DANBYTE_CAD_SANDBOX=off runs the
converter without the sandbox instead, which hands a hostile file the
worker's database credentials and secret keys if it exploits a converter
bug.
web listens on :80 (HTTP_PORT, default 8080) and :443
(HTTPS_PORT, default 8443) with a self-signed cert baked into the image -
so browsers that force HTTPS still connect (one-time cert warning). Put a real
TLS terminator in front for production and set DANBYTE_HTTPS=True.
The documentation is built into the web image (zensical build in the
Dockerfile's docs stage) and served as static files at /docs/ on the
same ports, e.g. http://localhost:8080/docs/. The in-app Docs links point
there; there is no separate docs container. Rebuilding web picks up docs
changes.
Environment¶
All configuration is in .env (see deploy/docker/.env.example for the full,
commented list). The essentials:
| Variable | Purpose |
|---|---|
DJANGO_SECRET_KEY |
Django secret; unique per deployment. |
MONITORING_SECRET_KEY |
Encrypts stored credentials; required with DEBUG=False. Never just replace it once secrets are stored - rotate it (comma-separated list, newest first). |
DB_PASSWORD |
Postgres password (db + app). |
REDIS_PASSWORD |
Optional. Set, the redis service starts with --requirepass and every Python service sends it; empty (default), no password. See Hardening. |
ALLOWED_HOSTS |
Hosts/IPs served (no scheme/port). |
CSRF_TRUSTED_ORIGINS |
Origins allowed to POST (scheme + host [+ port]). |
DANBYTE_HTTPS |
True when TLS terminates in front - enables secure cookies + HSTS. |
DANBYTE_TRUSTED_PROXY_DEPTH |
Proxies appending to X-Forwarded-For, counting the stack's own nginx: 1 direct (default), 2 with one proxy in front. Finds the client address for the login lockout. |
DANBYTE_CSP_MODE |
The pages' script policy: enforce (default), report or off. See Hardening. |
HTTP_PORT |
Published host port (default 8080). |
RQ_WORKERS |
Worker pool size. |
DANBYTE_INTERNAL_URL |
Where scripts reach the API (default http://backend:8000). See Scripts and the API. |
BASE_IMAGE_REGISTRY |
Where base images come from (default public.ecr.aws/docker/library). See Base images. |
Base images¶
The base images - Postgres, Redis, and the node, nginx and python images
the Dockerfile builds on - come from ECR Public
(public.ecr.aws/docker/library), Amazon's copy of the Docker official images,
not from Docker Hub. Docker Hub limits anonymous pulls per address, and a build
host behind a shared NAT or a CI runner reaches that limit quickly; ECR Public
serves the same images without it. The Dockerfile has no # syntax= line for
the same reason: that line makes BuildKit pull its parser from Docker Hub.
To pull from another mirror (a Harbor or Artifactory proxy, or Docker Hub
itself with a login), set BASE_IMAGE_REGISTRY in .env to the path that
holds the official images:
The compose files use it for postgres and redis and pass it to the build,
so the next build pulls node, nginx and python from there too. The
mirror needs the same tags (postgres:17, redis:7, node:22-slim,
nginx:1.27.5-alpine, python:3.13-slim). A plain docker build takes it as
--build-arg BASE_IMAGE_REGISTRY=….
TLS¶
The web container speaks plain HTTP on :80 (published as HTTP_PORT) and
HTTPS with a self-signed cert on :443 (HTTPS_PORT). Terminate real TLS in
front of it - a host reverse proxy, a cloud load balancer, or a
caddy/traefik sidecar - then set DANBYTE_HTTPS=True and add your external
URL to ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS.
Behind your own nginx¶
A host nginx that owns the public certificate and forwards to the stack. Point
it at the HTTPS port (8443): the container's nginx sets
X-Forwarded-Proto from its own listener, so forwarding to the plain :8080
listener tells Django the request was http - with DANBYTE_HTTPS=True that
is a redirect loop, and without it CSRF rejects every POST from an https
origin. The self-signed hop on 127.0.0.1 is fine; nginx does not verify
upstream certificates by default.
# /etc/nginx/sites-available/danbyte.conf (host nginx, in front of compose)
upstream danbyte_stack { server 127.0.0.1:8443; }
server {
listen 80;
server_name danbyte.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
http2 on;
server_name danbyte.example.com;
ssl_certificate /etc/letsencrypt/live/danbyte.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/danbyte.example.com/privkey.pem;
client_max_body_size 100m;
# WebSockets (presence, SSH terminal). The Upgrade/Connection headers
# must survive this hop, or daphne only ever sees a plain GET.
location /ws/ {
proxy_pass https://danbyte_stack;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 3600s;
}
location / {
proxy_pass https://danbyte_stack;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
Host $host is what makes Django see the public name, so .env needs:
ALLOWED_HOSTS=danbyte.example.com
CSRF_TRUSTED_ORIGINS=https://danbyte.example.com
DANBYTE_HTTPS=True
# The host nginx is a second hop in X-Forwarded-For, in front of the stack's.
DANBYTE_TRUSTED_PROXY_DEPTH=2
DANBYTE_TRUSTED_PROXY_DEPTH tells the login lockout where the client's
address sits in X-Forwarded-For. It has to match the real number of
proxies: too low and every user shares the front proxy's address, too high
and a client can name any address it likes. Failures are counted per client
and account, plus a higher per-account ceiling across all addresses, so a
wrong value is never a way to lock everyone out or to brute-force one
account.
WebSocket troubleshooting¶
docker compose logs ws shows daphne's handshake log. What it says narrows the
cause:
| Log line | Meaning | Look at |
|---|---|---|
no WSCONNECTING at all, browser gets 404/400 |
The upgrade never reached daphne | The location /ws/ block above on every proxy hop |
WSREJECT |
The handshake arrived and the app closed it | The close code in the browser (DevTools → Network → WS) |
| Python traceback | The consumer crashed on connect | Redis / channel layer reachability from the ws container |
Close codes the presence socket uses: 4401 - no authenticated session
reached daphne (the session cookie was not forwarded, or a different
DJANGO_SECRET_KEY on the ws service); 4400 - the session has no active
tenant, or the page opened the socket without an object to watch. Hitting
https://<host>:8443/ directly, bypassing the front proxy, tells the two
layers apart.
Upgrading¶
A container can't upgrade itself - do it from the host
The in-app upgrade (Settings → Updates) is disabled on Docker/Podman
deployments, and the page shows the commands below instead. A process
inside a container can't rebuild its own image or recreate the container it
runs in, so a self-upgrade can only ever half-apply: it may migrate the
database and even swap files inside the running container, but the app
processes keep executing the old code. That mismatch - new schema, old
code - surfaces as confusing errors like "a required field was left empty
(is_uplink)" on an otherwise healthy-looking box. Always upgrade a
container deployment from the host, with the commands here.
git -C /opt/danbyte fetch --tags --force
git -C /opt/danbyte checkout <version> # e.g. v0.12.0
docker compose -f docker-compose.prod.yml --env-file .env build
docker compose -f docker-compose.prod.yml --env-file .env stop scheduler workers fastlane ws
docker compose -f docker-compose.prod.yml --env-file .env up -d
Docker installs upgraded to 0.17.0: upgrade to 0.17.1
Up to 0.17.0 the backups volume was mounted at /app/backups, which is
also the folder of Danbyte's own backups code. Docker fills a named volume
from the image only when the volume is created, so the containers kept
the backups code of the release that first made the volume. 0.17.0
changed that code, and every request answered 500 - /api/me first, so
nobody could sign in. 0.17.1 mounts the volume at
/app/backup-archives and moves the Local backup target with it; your
archives are the same files on the same volume. Upgrade with the commands
above. Going back to 0.16.13 does not help: the database is already
migrated to 0.17.
build is what makes this a real upgrade: it rebuilds the images from the
checked-out source, so the recreated containers actually run the new code. The
backend migrates on start, before it serves; stopping the scheduler, workers,
fast lane and websockets first keeps the previous release's processes from
running against the database while it does (a plain up -d --build recreates
them one by one, some after the migration has started). up -d then starts
them all on the new image. The named volumes keep your data.
ws, workers, fastlane and scheduler start only once the backend's
health check passes, which is after the migration. The check allows the
backend 30 minutes to get there. Up to 0.18.0 it allowed 60 seconds: a longer
migration marked the backend unhealthy, up -d stopped with dependency
failed to start, and those four were left Created or Exited while the
site itself came up. Nothing queued then ever ran - Poll, Refresh
MACs and Sync from SNMP on many devices stayed at 0 / N, and a bulk
action now answers No background worker is running instead (#441). If
ps shows any of them not running, run up -d again:
docker compose -f docker-compose.prod.yml ps ws workers fastlane scheduler
docker compose -f docker-compose.prod.yml --env-file .env up -d
Take a backup first: Settings → Backups → Back up now writes an encrypted
archive to the backups volume (/app/backup-archives in backend and workers).
A restore later runs inside workers without restarting any container - see
Backup and restore. The backend migrates without taking
one of its own.
Before it migrates, the backend runs manage.py prefix_cidrs --check. A
prefix whose CIDR is not an address and that the upgrade can't repair stops
it there, with each row listed in docker compose logs backend, before any
migration runs. See
Prefixes the upgrade can't repair
for the fix.
up -d also creates services added since your last pull - check that
scheduler is among them, because a stack upgraded from before it existed has
never run any periodic work:
Confirm the upgrade took
After it settles, the running version should match the tag you checked out:
If version still shows the old number, the app processes weren't replaced -
usually a missing --build, or containers that weren't recreated. Re-run the
command above.
Podman specifics¶
The stack is rootless-friendly and works with podman-compose. A few notes:
- Rootless ports < 1024: a non-root Podman can't bind
:80/:443. Keep the defaultHTTP_PORT=8080(or higher) and front it with a host proxy. - SELinux volumes: on SELinux hosts, if a bind mount is ever added, append
:Z. The stack uses named volumes, which Podman labels automatically - no change needed. podman play kube:podman-composeis the simplest path; if you prefer Kubernetes YAML, generate it from the running pod withpodman generate kube.
Prebuilt images (ghcr.io)¶
Tagging a release (v*) publishes the three images to GitHub Container
Registry via .github/workflows/container.yml, once the release's test
suite has passed for that tag:
ghcr.io/danbyte-net/danbyte-app:<version> # gunicorn / daphne / workers
ghcr.io/danbyte-net/danbyte-web:<version> # nginx + TLS
ghcr.io/danbyte-net/danbyte-frontend:<version> # vite preview (SSR)
To run from the registry instead of building locally, set the image: fields
in docker-compose.prod.yml to the ghcr paths (and drop the build: blocks),
or keep a small override file. latest tracks the newest release.
Where to host
ghcr.io is the default - it ships with the GitHub repo, authenticates
with the built-in GITHUB_TOKEN, and is free for public images (make the
package public in the repo's Packages settings). Docker Hub, Quay, or a
self-hosted Harbor work identically - change the registry/image
prefix in the workflow. For fully air-gapped installs, prefer the
offline tarball from the release workflow over a registry.
Development¶
For a lightweight dev backend (auto-reload, DEBUG=True, source bind-mounted,
no nginx/frontend container) use docker-compose.dev.yml instead - see the
Dev workflow.