Architecture

Why one privileged container holds a whole PaaS, how its parts find each other, and which decisions shaped it. Read this when you operate the platform or want to know what happens behind a button.

One container, many daemons#

The host runs one privileged docker:dind container, dind-hosting, with its data directories bind-mounted from the host. Inside it, a private network platform-net (172.28.0.0/16) hosts:

Why everything in one container? One host-level unit to operate (one container, one Compose file, one set of bind mounts, one address), and the management container and all child daemons become siblings on one network. The host exposure is exactly one address on one bridge network — no published ports.

Talking to every daemon: the socket directory#

Each daemon — main, db, every projects-<alias> — creates its API socket in one shared directory (/platform-data/sockets, bind-mounted from the host). Management mounts the directory and talks to all daemons through the same unix-socket client. It never uses a TCP port, and the main daemon has no TCP listener at all: an unauthenticated Docker API must not be reachable from the hosting network.

Networking: host mode inside a daemon#

• An app binds 0.0.0.0:<port> on its daemon's address. Traefik routes Host(blog.alex…) straight to http://172.28.0.64:10000.
• Cross-daemon access is plain layer 3: an app reaches its database at the database daemon's address, and MinIO at 172.28.0.5:9000. The platform injects those addresses as environment variables.
• Port uniqueness is needed only within one daemon, so allocators are per daemon, DB-backed and never reuse numbers during a daemon's life (no clash with stale connections).

Management: boot and reconcile#

1. Secretsgenerate any that are missing in /secrets
2. Databasereach platform-pg, run Alembic migrations
3. Reconcilenetwork, platform containers, every user's daemon
4. Traefikrebuild from stored ACME settings, recreate on drift
5. Workersmetrics sampler, domain watchdog, backup pruner
6. Serveopen the API, console and MCP

The reconciler creates what is missing and starts what is stopped; it never destroys user data. Only the stateless Traefik container is recreated when its desired spec changes — the spec is hashed into a label and compared on every boot.

The deploy flow, in detail#

1. Fetch — git clone --depth 1 [--branch ref] or an extracted archive (traversal- and size-guarded) into /deploys/build/<user>/<project>/<version>/.
2. Manifest — parse platform.yaml (strict), detect the runtime, resolve the version (manifest → hint → default).
3. Build — render a Dockerfile, stream the context over the daemon's socket (never bind-mounted into a child daemon, so sources never cross users) and build platform/<slug>:<version>-<sha8> plus :latest.
4. Run — stop and remove the old container; start the new one with --network host, the allocated port, the composed environment, volumes and limits, restart=unless-stopped.
5. Record — status, manifest and the full log (to MinIO), an audit row; write the Traefik route after the pre-check.

The pipeline is an in-process background task. If management restarts mid-build, the interrupted deployment is marked failed (interrupted by management restart) and you simply deploy again.

Security model in brief#

The shared database daemon is an accepted trade-off: databases are isolated by container boundary and per-database credentials rather than by daemon. A dedicated db-<alias> daemon removes that sharing for users who need it.

Data model#

Decisions that shaped it#

Not in this version#

Multi-host or Kubernetes deployment · horizontal scaling of the management service · per-project (instead of per-user) isolation · a registry shared between daemons · rollback UI beyond redeploying an older source · SSO and self-registration · direct external database ports · scheduled backups · Prometheus exporters and alerting.