The Control Plane

Strip the marketing off any PaaS and the same four verbs are left: build code into something runnable, run it somewhere, route traffic to it, and store its state so it survives. Everything else — dashboards, billing, autoscaling, preview environments — is a feature layered on those four.

What separates a platform from a bash script is who does those verbs and when. On your laptop you do them by hand, once. A platform does them on behalf of thousands of tenants, continuously, in response to state changes, and it does so through three distinct layers that are worth naming precisely because every architecture in this document is a variation on them.

The product this is written for

Instatic is a self-hosted CMS where the editor, the content engine and the publisher live in one server process, with SQLite as the database, an uploads folder for media, and published pages baked to plain HTML on disk. The stated backup unit is “the database file plus the uploads folder”. It deploys today as one container per site on Railway, Render or a VPS.

Your variant swaps the runtime for Ruby but keeps that shape, so this course assumes the following and says so up front rather than hedging for twelve sections:

Before scaling anything, be precise about what a single running instance of your product actually needs from the machine underneath it. Every one of these becomes a column in a database table later, so it pays to enumerate them now.

a process

Puma running your app, one or two workers, a few threads. It must start in seconds, exit cleanly on SIGTERM, and never assume it is the only copy in the world.

a port

It listens on one internal port. Nothing on the internet talks to it directly; a reverse proxy in front owns the public ports, the domains and the certificates.

a disk

SQLite is a file. Uploads are files. Published output is files. They must live on a real local filesystem — SQLite over NFS or a network drive corrupts under concurrent writes. This single fact shapes the whole scaling story in §07 and §08.

configuration

Environment variables at start: keys, the tenant’s plan limits, object-storage credentials scoped to that tenant’s prefix. Never baked into the image.

a domain and a certificate

acme.yourplatform.app for free, www.acme.co.ke when they bring their own. Certificates are issued and renewed by the proxy, not the app.

logs

Write to stdout. The host captures, rotates and, later, ships them. An app that writes its own log files inside the container fills the disk on a Sunday.

a health check

One cheap endpoint that returns 200 when the app can serve. The proxy and the deploy process both depend on it; without it there is no zero-downtime anything.

a backup

Copy of the disk contents, off the machine, on a schedule, with a tested restore. Instatic’s own docs name the backup unit as database file plus uploads folder — keep it that simple.

Containers won hosting not because they are clever — a container is a process with a restricted view of the filesystem, network and process table — but because an image is a complete, immutable, content-addressed description of everything a process needs. That makes “run this on that machine” a solved problem, and it is the reason every platform in §09 speaks OCI images even when it runs them in something other than Docker.

Five words

image

A stack of read-only filesystem layers plus metadata (entrypoint, env, ports). Identified by a content digest (sha256:…); tags like :v1.4 are mutable pointers to a digest. Deploy by digest, never by tag.

container

A running (or stopped) instance of an image with a thin writable layer on top. Disposable by design. Anything written inside it and not to a volume is gone on restart.

volume

A host directory mounted into the container that outlives it. Where SQLite and uploads live. Named volumes under /var/lib/docker/volumes or bind mounts to a path you choose.

network

A private virtual network. Containers on the same one reach each other by name. Tenants should not share one, or tenant A can talk to tenant B’s port 3000.

registry

Where images are pushed and pulled from: Docker Hub, GHCR, ECR, or a self-hosted one. The platform’s release artefact lives here.

How code becomes an image

Those five are literally the cases in app/Enums/BuildPackTypes.php in your Coolify clone, and the deploy_*_buildpack() methods in ApplicationDeploymentJob are one per row. Vercel and Laravel Cloud do the same detection with their own build systems. For your product, only the last row matters: you build your platform image once per release and run it N times. Tenants never build anything — which removes the single most complex subsystem of a general-purpose PaaS from your plate.

# ---- build stage: compile gems and assets, then throw the toolchain away
FROM ruby:3.4-slim AS build
RUN apt-get update -qq && apt-get install -y --no-install-recommends \
      build-essential libsqlite3-dev libyaml-dev git && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle config set --local deployment true && \
    bundle config set --local without 'development test' && \
    bundle install -j4
COPY . .
RUN SECRET_KEY_BASE=dummy bundle exec rails assets:precompile

# ---- runtime stage: small, non-root, read-only except /data
FROM ruby:3.4-slim
RUN apt-get update -qq && apt-get install -y --no-install-recommends \
      libsqlite3-0 libyaml-0-2 curl tini && rm -rf /var/lib/apt/lists/* \
    && useradd -r -u 10001 -d /app app
WORKDIR /app
COPY --from=build --chown=app:app /app /app
COPY --from=build /usr/local/bundle /usr/local/bundle

ENV RAILS_ENV=production RAILS_LOG_TO_STDOUT=1 \
    DATABASE_URL=sqlite3:/data/db/production.sqlite3 \
    UPLOADS_DIR=/data/uploads PUBLISH_DIR=/data/public PORT=3000
VOLUME ["/data"]
EXPOSE 3000
USER app
HEALTHCHECK --interval=10s --timeout=3s --start-period=20s \
  CMD curl -fsS http://127.0.0.1:3000/up || exit 1
ENTRYPOINT ["tini","--"]
CMD ["bundle","exec","puma","-C","config/puma.rb"]

What Docker does not give you

Containers share the host kernel. They are a packaging and resource-accounting boundary, not a security boundary in the way a virtual machine is. Two consequences: a kernel exploit in one tenant’s container is a host compromise, and you need to set CPU and memory limits explicitly or one tenant’s runaway import job starves the other forty. §10 covers what to do about the first; the second is two lines of compose:

deploy:
  resources:
    limits:   { cpus: "1.0", memory: 512M }     # hard ceiling, OOM-killed above
    reservations: { memory: 128M }              # scheduler hint

This is the minimal platform, and it is more platform than most people expect. One rented machine, Docker, a reverse proxy that issues certificates, one container per tenant, one directory per tenant. Coolify, Kamal and Dokku are all automation around exactly this picture; understanding it by hand is what makes their behaviour legible.

services:
  caddy:
    image: caddy:2
    ports: ["80:80", "443:443", "443:443/udp"]
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data              # certificates live here. back it up.
    networks: [t-acme, t-bloom]       # caddy joins every tenant network
    restart: unless-stopped

  acme:
    image: ghcr.io/you/platform@sha256:9f1c…      # by digest, never :latest
    environment:
      TENANT_ID: acme
      SECRET_KEY_BASE: ${ACME_SECRET}
      PLAN_MAX_PAGES: "200"
    volumes: ["/srv/tenants/acme:/data"]
    networks: [t-acme]                            # its own network, nothing else
    deploy: { resources: { limits: { cpus: "1.0", memory: 512M } } }
    restart: unless-stopped

  bloom:
    image: ghcr.io/you/platform@sha256:9f1c…
    environment: { TENANT_ID: bloom, SECRET_KEY_BASE: ${BLOOM_SECRET} }
    volumes: ["/srv/tenants/bloom:/data"]
    networks: [t-bloom]
    deploy: { resources: { limits: { cpus: "1.0", memory: 512M } } }
    restart: unless-stopped

networks:
  t-acme:  { internal: false }
  t-bloom: { internal: false }
volumes:
  caddy_data:

acme.plat.app {
    reverse_proxy acme:3000 {
        health_uri /up
        health_interval 10s
    }
    encode zstd gzip
}
bloom.plat.app, www.bloomflorists.co.ke {
    reverse_proxy bloom:3000
    encode zstd gzip
}

Capacity: how many tenants fit?

The honest answer depends on one number you should measure, not guess: what share of tenants are active at once. For a CMS whose published output is static, the Ruby process only works when someone is editing or publishing. That share is small — single-digit percent on a normal day.

Memory of idle processes is the ceiling, which is why §12 introduces hibernation: stop the container of any tenant that has not touched the editor in N hours and start it on the next request. Published sites keep serving from static files regardless. With hibernation, a single box hosts many hundreds of tenants and the ceiling becomes disk and your nerves, not RAM.

“Connect your domain” is the feature every customer expects and the one that generates the most support tickets. It is three separate mechanisms — DNS pointing, ownership verification, and certificate issuance — and each has a right answer that platforms converged on years ago.

The records that matter

A / AAAA

Hostname → IPv4 / IPv6 address. Required at the apex (acme.co.ke) because the DNS spec forbids CNAME there. Means the customer’s DNS holds your IP, which you can then never change without asking every customer to update.

CNAME

Hostname → another hostname (www.acme.co.ke → sites.plat.app). You control what sites.plat.app resolves to forever. The right answer for subdomains and the reason platforms ask for www.

ALIAS / ANAME / flattening

Provider-specific way to get CNAME behaviour at the apex. Cloudflare, Route 53, DNSimple and most modern DNS hosts support it; many registrars’ default DNS does not. Your docs will need both paths.

TXT

Free-form. Used to prove ownership (_plat-verify.acme.co.ke = tok_8f2…) and for DNS-01 ACME challenges.

wildcard

*.plat.app → your ingress. One record, unlimited free-tier subdomains, one wildcard certificate. Set this up on day one.

{
    on_demand_tls {
        ask      http://control-plane.internal:8080/tls/ask
        interval 2m
        burst    5
    }
    email ops@plat.app
}

# free-tier subdomains: one wildcard certificate, DNS-01 challenge
*.plat.app {
    tls { dns cloudflare {env.CF_API_TOKEN} }
    reverse_proxy {http.request.host.labels.2}:3000   # acme.plat.app -> acme:3000
}

# any other hostname: issue on demand, then route by looking the tenant up
https:// {
    tls { on_demand }
    reverse_proxy http://router.internal:8080 {         # a tiny service that
        header_up X-Forwarded-Host {host}               # maps host -> tenant
    }
}

# config/routes.rb
get "/tls/ask", to: "tls#ask"

# app/controllers/tls_controller.rb
class TlsController < ApplicationController
  # Caddy calls this before requesting a certificate for an unknown host.
  # It must be fast and it must say no by default.
  def ask
    host = params[:domain].to_s.downcase.delete_suffix(".")
    ok = Domain.where(hostname: host, status: "verified")
               .joins(:tenant).merge(Tenant.active)
               .exists?
    head(ok ? :ok : :not_found)
  end
end

The three ways to get certificates, compared

Vercel and Laravel Cloud are the third row: Laravel Cloud fronts every cluster with Cloudflare Tunnels and lets Cloudflare own the customer-facing certificates. Coolify is the first row with Traefik. For your product, start with the first row on one node and move customer domains to the third row when you either add a second node or get your first DDoS — whichever comes first.

The moment you have more than a handful of tenants, editing a Caddyfile stops being an option. What replaces it is a database of what should be true plus code that keeps making it true. That is a control plane, and Coolify — sitting in your clone — is a complete, readable example of one.

What a control plane is, minimally

A deployment, as Coolify actually does it

Condensed from ApplicationDeploymentJob::handle() and the methods it calls. Every step is a remote shell command; every result is a log line the UI streams over Soketi.

1. Precheck. Refuse if the queue entry was cancelled; mark IN_PROGRESS with the Horizon worker hostname; bail if $server->isFunctional() is false.
2. Prepare the channel. Write the server’s private key to disk; SSH multiplexing reuses a control socket per server so the dozens of commands that follow don’t each pay a handshake.
3. Learn the network. docker network inspect the destination network to build --add-host entries so the build can resolve sibling containers by name.
4. Pick a builder. The target server by default; a dedicated build server if the app opted in and one exists in the team.
5. Start a helper container (coollabsio/coolify-helper) with /var/run/docker.sock mounted. All git and build work happens inside it, so the host stays clean and the toolchain is versioned with Coolify, not with the server.
6. Build per BuildPackTypes: clone, run Nixpacks/Railpack/Dockerfile/compose, tag the image with the commit, optionally push to a registry.
7. Generate a compose file for the app with environment, volumes, health check, and — crucially — the Traefik labels that are its routing config.
8. Rolling update. docker compose up the new container beside the old one, poll the health check, then stop the old one. If the app maps host ports or pins a container name, rolling is impossible, so it stops-then-starts and says so in the log.
9. Post-deployment. Run the user’s post-deploy command, write configs, gracefully remove the helper, broadcast the status change.

services:
  acme-h3k9s:
    image: acme-h3k9s:8f2c1a9
    networks: [coolify]
    labels:
      - coolify.managed=true
      - coolify.applicationId=42
      - traefik.enable=true
      - traefik.http.routers.https-0-acme.rule=Host(`acme.example.com`) && PathPrefix(`/`)
      - traefik.http.routers.https-0-acme.entryPoints=https
      - traefik.http.routers.https-0-acme.tls=true
      - traefik.http.routers.https-0-acme.tls.certresolver=letsencrypt
      - traefik.http.routers.https-0-acme.middlewares=gzip
      - traefik.http.services.acme.loadbalancer.server.port=3000
      - traefik.http.routers.http-0-acme.rule=Host(`acme.example.com`)
      - traefik.http.routers.http-0-acme.middlewares=redirect-to-https
    healthcheck: { test: ["CMD","curl","-f","http://127.0.0.1:3000/up"], interval: 5s, retries: 10 }

The reconciliation loop, in general

class ReconcileTenantJob
  include Sidekiq::Job
  sidekiq_options retry: 5, lock: :until_executed   # one at a time per tenant

  def perform(tenant_id)
    tenant  = Tenant.find(tenant_id)
    node    = tenant.node
    desired = tenant.desired_container_spec          # image digest, env, limits, volume
    actual  = node.inspect_container(tenant.container_name)   # nil if absent

    case
    when tenant.status == "deleted" && actual
      node.remove_container(tenant.container_name)
    when actual.nil? && tenant.should_run?
      node.run_container(desired)
    when actual && actual.image_digest != desired.image_digest
      node.rolling_replace(tenant.container_name, desired)   # start new, health, stop old
    when actual && !tenant.should_run?
      node.stop_container(tenant.container_name)             # hibernate, keep volume
    end

    tenant.update!(observed_at: Time.current, observed_digest: node.inspect_container(tenant.container_name)&.image_digest)
  end
end

A general PaaS spends most of its complexity budget on builds, because it must turn arbitrary customer repositories into images. You don’t. Your tenants all run one image you built. That simplification is worth naming loudly, because it removes a build farm, a registry-per-customer, buildpack detection and a whole class of support tickets from your plan.

Where the big platforms build

Your build pipeline

1. CI builds the platform image on every tag: multi-stage Dockerfile from §02, pushed to GHCR (or ECR) with both a version tag and, more importantly, a digest.
2. A release row in the control plane records the digest, the changelog, and whether it carries a schema migration.
3. Tenants pin a digest. Rolling out is changing the pinned digest on a set of tenant rows and letting the reconciler from §05 do the rest.
4. Cohorts. Your own tenants first, then 1%, then 10%, then everyone, each step gated on the previous cohort’s error rate and health-check pass rate. The plugin course’s rollout advice applies verbatim.

The per-tenant rolling update, with SQLite in the picture

Coolify’s rolling_update() starts the new container, waits for health, then stops the old one. Kamal’s kamal-proxy does the same and only switches traffic once the new container answers its health check. With a stateless app that is the whole story; with SQLite there are two extra rules:

• Both containers mount the same volume during the overlap. Two Puma processes writing one SQLite file for a few seconds is fine if the database is in WAL mode with a busy timeout (PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000) and catastrophic otherwise. Set it in the image, not in a migration someone can forget.
• Migrations run expand-then-contract. Version N+1 must tolerate rows written by version N during the overlap, and version N must tolerate a schema that N+1 has already extended. Add columns, backfill, switch code, drop later — never rename in one step. If a migration cannot be made additive, that release stops-then-starts instead of rolling, and the reconciler should know which kind it is from the release row.

def rolling_replace(name, spec)
  new_name = "#{name}-#{Time.now.to_i}"
  run_container(spec.merge(name: new_name))              # same volume, same network
  wait_healthy!(new_name, timeout: 60)                    # polls the HEALTHCHECK state
  proxy.point(spec.hostnames, to: "#{new_name}:3000")     # caddy admin API / label swap
  stop_container(name, grace: 20)                         # SIGTERM, then SIGKILL
  rename_container(new_name, name)
rescue HealthTimeout
  remove_container(new_name)                              # old one never stopped
  raise
end

Compute is fungible; state is where hosting gets hard. Your product has three kinds of it per tenant, and each wants a different home. Getting this split right is what makes tenants movable, backups trivial, and published sites survive anything that happens to the Ruby process.

SQLite: three ways to make one file survivable

dbs:
  - path: /data/db/production.sqlite3
    replicas:
      - type: s3
        bucket: plat-tenants
        path: tenants/${TENANT_ID}/db
        endpoint: https://fsn1.your-objectstorage.com     # any S3-compatible
        sync-interval: 1s
        retention: 72h
        snapshot-interval: 6h

Uploads: local disk is a cache, the bucket is the truth

Media is the state that grows without bound and the one that makes tenants heavy to move. The pattern that scales: the app writes uploads to the bucket (directly, or to local disk then a background sync), serves them from the bucket through the CDN, and treats the local uploads/ as a warm cache that can be dropped. Rails ActiveStorage with an S3 service does this natively; give each tenant credentials scoped to its own prefix so a bug in one tenant cannot read another’s files.

Published output: the reason visitors never wake the Ruby process

This is the load-bearing decision for both cost and reliability. Instatic already bakes pages to disk on publish. Push that directory to sites/<tenant>/ in the bucket on every publish, and point the CDN at the bucket for the tenant’s hostnames. Then:

• Traffic to a tenant’s site is a CDN problem, not a Ruby problem. A front-page mention costs you bandwidth, not a rewrite.
• The Ruby container can hibernate whenever the editor is idle. That is your density lever (§12).
• Publishing becomes versioned and atomic: upload to sites/acme/v42/, flip a pointer, keep the previous version for instant rollback. This is exactly Vercel’s “immutable deployment plus alias” model, which its own docs describe as separating static assets from compute artifacts at build time.

Choosing the bucket

Your actual question. The answer is not a machine count; it is a property of the control plane. Make a tenant’s placement a column, and the number of machines stops being an architectural decision and becomes a capacity one. Then start with one.

The trade-offs, without romance

The concrete recommendation

1. Start on one box, but write the placement column on day one. Every tenant row says node: "a" even when there is only a. Every job looks up the node from the row rather than assuming localhost. This costs nothing now and is the difference between “add a node” being an afternoon or a rewrite.
2. Get off-box state working before your tenth customer. Bucket, Litestream, nightly snapshots, and a restore script you have run. With that in place, a one-box failure is an outage of the editor measured in the time to rent a replacement and restore — tens of minutes — not a data-loss event.
3. Move the control plane to its own tiny box early. When the tenant node is unhealthy you need the thing that fixes it to be healthy. A $5 VPS is enough; it is a Rails app and Postgres.
4. Add cells when a metric says to: sustained memory above 70%, disk above 60%, or a plan tier that wants fewer neighbours. Not before. The second node is the expensive one, because it forces the migration job to exist; the tenth is free.
5. Do not reach for Kubernetes, Swarm or Nomad for this shape. They schedule heterogeneous workloads across a fleet. You have one image, hundreds of identical, single-node, disk-pinned instances. The placement table plus a reconciler is your scheduler, and it fits in a few hundred lines you fully understand.

Dedicated versus cloud VPS

The old rule — cloud VPS for flexibility, dedicated for price per core — has sharpened. Hetzner raised cloud server prices substantially with effect from 15 June 2026 (reported multiples of two to three times on the larger CCX and CPX tiers), while dedicated lines remain the cheapest compute per core available to a small operator. For a workload that is mostly idle processes and local disk, a dedicated box with NVMe is close to ideal. Its weaknesses are exactly the ones this course has already designed around: no snapshots (you have the bucket), no live migration (you have the placement job), and a hardware failure means a reinstall (you have a scripted node bootstrap, §11). Keep one cloud VPS as the control plane and one as a warm spare, put tenants on metal, and you have most of the benefits of both.

Four platforms, four very different amounts of money, one shape. Read them for what they chose to own — that is the real architectural decision — and notice how much each one hands to somebody else.

You are running other people’s data, and possibly other people’s code, on one kernel. The question to answer before choosing any technology is: can a tenant execute code I did not write? The answer moves you between two very different worlds.

Instatic’s plugin system runs plugins in QuickJS compiled to WASM with explicit permissions — the same design the plugin course covered for Figma. If your Ruby variant offers plugins, that is the right shape: sandbox the plugin inside your process, never let the tenant run a raw Ruby process. That keeps you in the left column, where Docker is enough.

The container hardening checklist, left column

acme:
  image: ghcr.io/you/platform@sha256:9f1c…
  user: "10001:10001"
  read_only: true                      # image is immutable at runtime
  tmpfs: ["/tmp:size=64m", "/app/tmp:size=64m"]
  volumes: ["/srv/tenants/acme:/data"] # the only writable path
  cap_drop: ["ALL"]
  security_opt: ["no-new-privileges:true"]
  pids_limit: 256
  networks: [t-acme]                   # no shared network, no docker.sock, ever
  deploy: { resources: { limits: { cpus: "1.0", memory: 512M } } }
  logging: { driver: json-file, options: { max-size: "10m", max-file: "3" } }

The rest

• Secrets: one SECRET_KEY_BASE per tenant, S3 credentials scoped to the tenant prefix with an IAM-style policy, injected as environment at start, stored encrypted in the control plane. Never in the image, never in a compose file on disk in plain text (use an env file with 0600 or Docker secrets).
• Ingress: rate limits at Caddy, request size caps, and Cloudflare in front the day you can. A CMS editor is a low-traffic, high-value target; the published sites are high-traffic and static, so let the CDN absorb them.
• The control plane is the crown jewel. It holds SSH keys or an agent token for every node. Separate box, MFA, IP allowlisting on SSH, audit log of every mutation (Coolify logs every remote command), and no public dashboard without SSO.
• Backups are a security control: ransomware, a deleted-by-mistake tenant, a bad migration — all are restore operations if the bucket is versioned and its credentials are write-only from the nodes.

The features people admire in a platform are mostly operations made visible. This is the runbook, ordered by how often each item pages you.

#!/usr/bin/env bash
set -euo pipefail
# 1. base
apt-get update && apt-get install -y ca-certificates curl ufw unattended-upgrades
curl -fsSL https://get.docker.com | sh
# 2. firewall: only ssh, http, https. control plane IP only for ssh.
ufw default deny incoming; ufw allow from "$CONTROL_PLANE_IP" to any port 22
ufw allow 80/tcp; ufw allow 443/tcp; ufw allow 443/udp; ufw --force enable
# 3. layout
mkdir -p /srv/tenants /srv/caddy
# 4. docker daemon defaults: log rotation, live-restore so a dockerd restart
#    doesn't kill every tenant
cat > /etc/docker/daemon.json <<'EOF'
{ "log-driver": "json-file", "log-opts": { "max-size": "10m", "max-file": "3" },
  "live-restore": true, "default-address-pools": [{ "base": "10.200.0.0/16", "size": 28 }] }
EOF
systemctl restart docker
# 5. node agent or ssh key for the control plane; caddy with on-demand TLS
docker compose -f /srv/caddy/docker-compose.yml up -d
# 6. register with the control plane
curl -fsS -X POST "$CONTROL_PLANE/nodes" -H "Authorization: Bearer $NODE_TOKEN" \
     -d "hostname=$(hostname)&ip=$(curl -s https://api.ipify.org)&capacity_gb=$(df --output=avail -BG /srv | tail -1)"

Everything above, assembled into one design for the Instatic-with-Ruby product on rented machines. It is deliberately boring: a Rails control plane, Docker nodes, Caddy, a bucket, a CDN. The interesting decisions are the two that make it cheap — static sites off the container, and hibernating editors.

The tables

Tenant lifecycle

class ProvisionTenantJob
  include Sidekiq::Job
  sidekiq_options retry: 3, lock: :until_executed

  def perform(tenant_id)
    tenant = Tenant.find(tenant_id)
    return unless tenant.status == "provisioning"

    tenant.with_lock do
      tenant.node    ||= Node.active.with_free_capacity.order(:tenant_count).first!
      tenant.release ||= Release.current
      tenant.secret_key_base ||= SecureRandom.hex(64)
      tenant.save!
    end

    node = tenant.node
    ObjectStore.ensure_prefix!(tenant)            # tenants/<slug>/ + scoped creds
    node.exec!("install -d -o 10001 -g 10001 -m 0750 /srv/tenants/#{tenant.slug}")

    node.run_container!(
      name:    tenant.container_name,
      image:   tenant.release.image_ref,          # "ghcr.io/you/platform@sha256:…"
      env:     tenant.runtime_env,                # TENANT_ID, SECRET_KEY_BASE, S3_*
      volume:  "/srv/tenants/#{tenant.slug}:/data",
      network: "t-#{tenant.slug}",
      limits:  tenant.plan.limits,                # cpus, memory, pids
      hardened: true,
    )
    node.run_sidecar!(:litestream, tenant)
    node.wait_healthy!(tenant.container_name, timeout: 60)

    Domain.create!(tenant: tenant, hostname: "#{tenant.slug}.plat.app",
                   kind: "platform", status: "verified")   # wildcard covers it
    node.proxy.upsert_route!(tenant)              # caddy admin API, host -> upstream

    tenant.update!(status: "running", provisioned_at: Time.current)
    AuditEvent.record!(tenant:, node:, command: "provision", result: "ok")
  rescue => e
    tenant.update!(status: "provisioning", last_error: e.message)   # retry-safe
    raise
  end
end

Hibernation: the wake gate

Editor hostnames route through a small gate instead of straight to the container. It is a platform component you trust, so it may talk to the Docker socket. It does one thing: if the tenant’s container is stopped, start it, wait for health, then proxy. The control plane separately stops containers idle for N hours.

require "rack"; require "docker"; require "net/http"

class WakeGate
  WAKING = Rack::Files.new("holding").method(:call)   # a "waking up…" page

  def call(env)
    host   = env["HTTP_HOST"].split(":").first
    tenant = Router.tenant_for(host) or return [404, {}, ["no such site"]]
    c      = Docker::Container.get(tenant.container_name) rescue nil
    return [503, {}, ["provisioning"]] unless c

    unless c.info["State"]["Running"]
      c.start                                        # docker start, ~1 s
      ControlPlane.notify_woke(tenant.id)            # resets the idle clock
      return [503, {"retry-after" => "3", "refresh" => "3"}, [holding_page]]
    end
    return [503, {"refresh" => "2"}, [holding_page]] unless healthy?(c)

    Proxy.forward(env, to: "#{tenant.container_name}:3000")   # normal case
  end
end

What the Ruby app itself must do differently

• Boot fast. Eager-load, precompile assets in the image, no migrations at boot (run them from the reconciler with a lock). A 20-second boot makes hibernation feel broken; a 3-second one makes it invisible.
• Publish = write to the bucket, then flip a pointer. Bake to /data/public, sync to sites/<slug>/v<n>/, then tell the control plane to mark v<n> live. The CDN mapping changes; nothing on the node needs to keep serving it.
• Media through the bucket. ActiveStorage S3 service with the tenant’s scoped credentials; local disk is a cache.
• WAL mode, busy timeout, one writer. Set on connection. Never run two app containers for one tenant except during the seconds of a rolling replace.
• Report activity. A middleware that touches last_editor_activity_at (batched, once a minute) is what the hibernation job reads.

In this order, each step shippable

1. The image and the volume contract. Multi-stage Dockerfile, everything mutable under /data, health endpoint, WAL mode. Run it by hand on your laptop with a bind mount. This is a week and it is the foundation of everything.
2. One node, by hand. Caddy with the wildcard certificate, five tenants in a compose file, a cron tar to a bucket. Onboard your first real users on this. Yes, really.
3. The control plane, minimal. Rails, the seven tables, ProvisionTenantJob, ReconcileTenantJob, SSH channel. Replace the hand-edited compose file with the reconciler. Nothing the customer sees changes.
4. Static publishing to the bucket + CDN. The moment visitors stop hitting Ruby, your cost curve bends and your uptime story becomes real.
5. Litestream sidecars and the restore drill. Rehearse a restore to a scratch node with a stopwatch. Write the number down.
6. Custom domains with the ask endpoint and the DNS checker.
7. Hibernation. The wake gate and the idle job. Watch memory fall.
8. Cohort rollouts from release rows.
9. The second node and the migration job — only when a metric asks. Then Cloudflare in front of the editors, and its custom-hostname product in front of the sites, when you want the DDoS story or the second region.

Glossary

Anycast

Announcing one IP from many locations so the network routes each client to the nearest. Vercel and Fly’s front door; not something a small operator needs.

Cell

A complete, independent unit of the data plane — a node with its own proxy and tenants — sharing only the control plane with other cells.

Control plane

The software that holds desired state and makes reality match it. Never on the request path.

Data plane

Where tenant workloads and their state actually run and are served from.

Digest

The content hash of an image. The only trustworthy way to name what you deployed.

Hibernation

Stopping an idle tenant’s process while keeping its state, and restarting it on demand.

On-demand TLS

Issuing a certificate at the first TLS handshake for a hostname, after asking the control plane whether to.

Placement

The row that says which node a tenant runs on. The column that makes scaling out a capacity decision.

Reconciler

An idempotent job that reads desired state, observes actual state, and issues the commands that close the gap.

Rolling replace

Start the new container, wait for health, switch traffic, stop the old one. Zero-downtime deploy.

Volume

A host directory mounted into a container that outlives the container. Where all tenant state lives on the node.

WAL

SQLite’s write-ahead log mode. Required for concurrent readers, for Litestream, and for the seconds of overlap in a rolling replace.