Architecture

Runtime topology

Everything the installer starts, on one Docker network called sthora-proxy:

                    :80 / :443
                        │
                   ┌────▼─────┐   ACME HTTP-01, docker provider
                   │ traefik  │────────────────────────┐
                   └────┬─────┘                        │
         fallback       │   resource paths             │  labels
        ┌───────────────▼──┐  ┌───▼──────────────┐     │
        │ sthora-web   │  │ sthora-api   │     │
        │ (TanStack Start) │  │ (NestJS + BullMQ)│     │
        └──────────────────┘  └───┬──────────┬───┘     │
                                  │          │         │
                        ┌─────────▼──┐  ┌────▼─────┐   │
                        │ postgres   │  │  redis   │   │
                        └────────────┘  └──────────┘   │
                                  │                    │
                    /var/run/docker.sock                │
                                  │                    │
                   ┌──────────────▼────────────────────▼──┐
                   │ user app compose projects: st-<slug>  │
                   └───────────────────────────────────────┘

• Postgres and Redis publish no host ports. Binding 5432:5432 on a public VPS is how self-hosted platforms get their databases wiped; the compose file uses expose, never ports.
• The API mounts the Docker socket, plus /proc:/host/proc:ro, /sys:/host/sys:ro, and /:/host/root:ro,rslave. Without the host mounts every metric it reports is the container's, not the machine's.
• The worker is deliberately not on the proxy network. It serves no HTTP and nothing should be able to route to it.
• The Traefik dashboard is never exposed, and the socket Traefik mounts is read-only. proxy.service.spec.ts asserts both.

One API container runs both HTTP and workers (APP_ROLE=all) on a small box. The same image runs with APP_ROLE=api or APP_ROLE=worker where they scale separately.

The memory budget

The target box is 2 vCPU / 4 GB / 40 GB.

Queues

BullMQ on Redis. Redis is also the cache and the log-fanout pub/sub bus.

Workers register a graceful shutdown handler — a SIGTERM mid-build fails the deployment cleanly rather than leaving it running forever — and a stalled-job reaper marks orphaned deployments FAILED on boot.

Compose lifecycle: shell out, do not reimplement

Compose v2 has no stable library API.

Mixing them this way is deliberate. Do not try to drive Compose through the API, and do not shell out for stats in a loop.

The one abstraction everything else rests on

Every Docker and filesystem operation is a ServerDriver call. LocalServerDriver is the local machine; AgentServerDriver is the same calls over a WebSocket. That is what makes managing a second machine a new file rather than a rewrite.

The stack