Skip to content

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

git clone https://github.com/danbyte-net/danbyte.git
cd danbyte
cp deploy/docker/.env.example .env

Edit .env - at minimum set the two secrets and the DB password. Generate each secret with:

python -c "import secrets; print(secrets.token_urlsafe(64))"

Then bring the stack up:

docker compose -f docker-compose.prod.yml --env-file .env up -d --build
podman-compose -f docker-compose.prod.yml --env-file .env up -d --build

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):

docker compose -f docker-compose.prod.yml exec backend python manage.py createsuperuser
podman-compose -f docker-compose.prod.yml exec backend python manage.py createsuperuser

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):

docker compose -f docker-compose.prod.yml exec scheduler python manage.py run_scheduler --once

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):

  workers:
    security_opt:
      - seccomp=unconfined
      - apparmor=unconfined

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:

BASE_IMAGE_REGISTRY=harbor.example.com/dockerhub-proxy/library

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:

docker compose -f docker-compose.prod.yml ps scheduler

Confirm the upgrade took

After it settles, the running version should match the tag you checked out:

curl -s localhost/api/health/    # {"status":"ok",...,"version":"0.12.0"}

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 default HTTP_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-compose is the simplest path; if you prefer Kubernetes YAML, generate it from the running pod with podman 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.