Self-hosting drobek

docs/SELF-HOSTING.md at v0.5.2 · View on GitHub · Markdown

drobek is one image (ghcr.io/freema/drobek) plus Postgres, Redis and Caddy. Caddy terminates TLS for the dashboard and for every app host, and proxies everything to drobek on the internal network. This guide takes a clean server to a working instance — dashboard over TLS, an agent connected over MCP, a published app — and covers backups, upgrades and every setting.

Measured: the whole quickstart below (init → TLS dashboard → user → MCP → published app with an uploaded file) took 33 s in the local rehearsal (task selfhost:rehearsal, tls internal, image already built), a backup 7 s, a restore on a second "machine" (fresh checkout + task selfhost:init + task restore) 33 s; the image build itself 145 s (a VPS pulls it instead). Local = macOS, Docker Desktop, arm64, 2026-09-23.

Quickstart (clean Ubuntu 24.04 + Docker)

What you need:

• a server with a public IPv4 (and/or IPv6), linux/amd64 (there is no ARM image in v1), ports 80 and 443 reachable from the internet;

• a domain for the dashboard and a domain for the apps. Create these DNS records before step 3 (Let's Encrypt checks them):

  Record	Points at	Example
  A (and/or AAAA) for the dashboard host	the server	drobek.example.com
  wildcard A/AAAA *.<APPS_DOMAIN>	the server	*.apps.example.net

  A separate registrable domain for the apps (example.net next to example.com) is the safer choice; apps.<your dashboard domain> works too. No DNS at all (a test box)? Use DOMAIN=localhost in step 3 — Caddy's local CA (tls internal), reachable only from the machine itself.

• an SMTP account (host, port, user, password, a sender address) or a Resend API key — sign-in codes go out by e-mail.

Every command runs as root (or prefix sudo).

1. Docker, git and go-task

curl -fsSL https://get.docker.com | sh
apt-get install -y git openssl
snap install task --classic
docker compose version     # → Docker Compose version v2.x (or newer)
task --version             # → Task version: v3.x

2. The drobek files (the compose file, the scripts, the env template — the image itself comes from GHCR)

git clone https://github.com/freema/drobek /opt/drobek
cd /opt/drobek
git checkout "$(git tag -l 'v*' --sort=-v:refname | head -n 1)"   # the newest release (skip before the first one)

3. Configuration — generates every secret, writes .env.production (mode 600), renders deployments/Caddyfile with the image's own generator (no Node on the host):

DOMAIN=drobek.example.com APPS_DOMAIN=apps.example.net \
TLS_ACME_EMAIL=you@example.com SUPERADMIN_EMAIL=you@example.com \
SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_USER=no-reply@example.com \
EMAIL_FROM=no-reply@example.com \
task selfhost:init

Expected output (abridged):

✓ created .env.production from .env.production.example (mode 600)
✓ generated POSTGRES_PASSWORD
✓ generated DROBEK_MASTER_KEY
✓ generated TLS_ASK_TOKEN
✓ dashboard https://drobek.example.com · apps https://<slug>.apps.example.net
✓ TLS mode for the app hosts: on-demand
✓ rendered deployments/Caddyfile (on-demand)
✓ docker compose config: OK

Then put the SMTP password in (never on the command line):

nano .env.production       # SMTP_PASS='…'   (single quotes if it has $, # or spaces)

task selfhost:init never asks anything and never overwrites a secret; run it again whenever you like (after changing TLS settings: then task tls:reload). The TLS default for a real domain is on-demand (one Let's Encrypt certificate per app host, gated by drobek); TLS_MODE=wildcard-file or TLS_MODE=dns pick a wildcard certificate instead — see "TLS" in docs/SELF-HOSTING.md.

4. Start

docker compose --env-file .env.production -f docker-compose.production.yaml up -d --wait

The first start pulls the images and drobek applies every database migration. Expected: Container drobek-prod-postgres-1 Healthy, …-redis-1 Healthy, …-drobek-1 Healthy, …-caddy-1 Healthy.

curl -s https://drobek.example.com/healthz      # → {"ok":true,"db":"up","redis":"up"}
curl -s https://drobek.example.com/api/version  # → {"name":"drobek","sha":"<commit>","version":"vX.Y.Z","commitTime":"…","startedAt":"…","modules":[…]}

Tip: alias dc='docker compose --env-file .env.production -f docker-compose.production.yaml' — the rest of this guide spells the command out.

5. Sign in — open https://drobek.example.com, enter your SUPERADMIN_EMAIL, type the 6-digit code from the e-mail. You land on /me with a personal workspace.

6. Connect an agent (Claude Code)

claude mcp add --transport http drobek https://drobek.example.com/mcp

Claude Code discovers drobek's OAuth server, opens the consent page in your browser (read, write, publish) and gets a token bound to you. Without a browser on the agent's machine, mint an API key on the server instead and pass it as a header:

docker compose --env-file .env.production -f docker-compose.production.yaml exec drobek \
  node node_modules/@drobek/oauth/dist/cli/api-key-create.js \
  --email you@example.com --name laptop --scopes read,write,publish
# → drk_…   (shown once)
claude mcp add --transport http drobek https://drobek.example.com/mcp \
  --header "Authorization: Bearer drk_…"

7. Publish an app — ask the agent: "Build a tip calculator on drobek and publish it." It calls create_app → write_files → publish; open the published_url it returns (https://tip-calculator.apps.example.net). With on-demand TLS the very first request to a new app host waits a few seconds for its certificate.

A test box without DNS — the same steps with Caddy's local CA:

DOMAIN=localhost SUPERADMIN_EMAIL=you@example.com SMTP_HOST=… task selfhost:init   # → TLS mode internal
docker compose --env-file .env.production -f docker-compose.production.yaml up -d --wait
docker compose --env-file .env.production -f docker-compose.production.yaml cp \
  caddy:/data/caddy/pki/authorities/local/root.crt ./drobek-root.crt
curl --cacert drobek-root.crt https://localhost/healthz

Trust drobek-root.crt in your browser / OS to use it without warnings (Node clients: NODE_EXTRA_CA_CERTS=drobek-root.crt). App hosts are https://<slug>.apps.localhost, which browsers resolve to the machine itself. HTTPS_PORT=8443 (plus HTTP_PORT=8080) moves Caddy off 443 — every URL then carries the port.

Hosts

DNS: an A/AAAA record for the dashboard host and a wildcard *.<APPS_DOMAIN> record, both pointing at the server. The dashboard may sit on the apex of APPS_DOMAIN (drobek.app + *.drobek.app) — it never serves an app — but a separate registrable domain for the apps is the safer choice.

Production compose

docker-compose.production.yaml runs drobek, postgres 17, redis 7 and caddy, all restart: unless-stopped with a healthcheck each. Only Caddy publishes ports (80, 443, 443/udp — HTTP_PORT / HTTPS_PORT / PUBLISH_IP move them); drobek, postgres and redis stay on the internal network. Nothing secret is written in the file — every value comes from .env.production (--env-file for interpolation, env_file for drobek). A missing secret or host stops docker compose before anything starts (${VAR:?}); a missing mail transport (SMTP_HOST, or RESEND_API_KEY with EMAIL_TRANSPORT=resend) stops drobek itself at start, and docker compose --env-file .env.production -f docker-compose.production.yaml config prints no warnings. The compose project is drobek-prod (not drobek, the dev stack's name in a checkout — a down -v here can never reach the dev volumes).

.env.production.example documents every variable (what it is, how it is generated, which ones are secrets). The compose file fixes, for drobek: NODE_ENV=production, TRUST_PROXY=x-real-ip, APPS_URL_SCHEME=https, FILES_DIR=/data/files, ASSETS_DIR=/data/assets, DATABASE_URL / REDIS_URL of the bundled services, PUBLIC_ORIGIN defaulting to PUBLIC_APP_URL, and DROBEK_MODULES defaulting to all six built-ins.

The file is read by docker compose and by docker run --env-file (the Caddyfile generator): one KEY=value per line, no inline comments; quote a value that contains $, # or spaces with single quotes. Careful: docker compose lets a variable exported in your shell override the same key in --env-file — don't export drobek settings in the shell you run compose from. The task commands (selfhost:*, backup, restore, tls:reload) go through scripts/selfhost-compose.sh, which removes every key of .env.production from the environment first, so the file always wins there.

The compose file sets TRUST_PROXY=x-real-ip for drobek: behind Caddy the client IP (every per-IP rate limit) comes only from the X-Real-IP header Caddy sets from the TCP peer — a client-sent X-Real-IP or X-Forwarded-For is overwritten/ignored. Leave TRUST_PROXY unset only when a different proxy (e.g. nginx with X-Real-IP $remote_addr) is in front. Per-IP limits need a resolved client IP: a request that arrives without a trusted header (a proxy that does not set X-Real-IP, a request that bypassed the proxy) gets no per-IP bucket at all — not a shared one — so only the per-app, per-user and per-code limits hold it. drobek logs one rate_limit_no_client_ip warning per limit (once per start) when that happens; seeing it in production means the proxy header is missing.

Platform modules (the backends apps use through import { drobek } from 'drobek') are enabled with DROBEK_MODULES (comma-separated; a short name x loads the package drobek-module-x from the server's dependencies, or from DROBEK_MODULES_DIR for a module you installed with task selfhost:module:add — Third-party modules). The server applies each module's migrations on start and refuses to start on a module it cannot load. Limits come from their env vars or, with LIMITS_PROVIDER_URL + LIMITS_PROVIDER_SECRET, from your own signed limits endpoint. The image ships the built-in auth, email, forms, data, proxy and files (DROBEK_MODULES=auth,email,forms,data,proxy,files, the compose default; forms requires email). Proxy upstreams may only use ports 80 and 443 (PROXY_ALLOWED_PORTS); an upstream on a private address needs its hostname on PROXY_ALLOWED_HOSTS (keep it empty in production). The old /<ws>/api/proxy/<name>/* dashboard-host route is gone: an app calls /__drobek/v1/proxy/<name>/* once the upstream is assigned to it. files stores end-user uploads on disk under FILES_DIR (/data/files, the files_data volume): one file per distinct content, the type sniffed from the bytes, at most FILES_MAX_BYTES (10 MiB) per file and FILES_QUOTA_PER_APP (500 MiB) per app. Enabling data on a server that stored records through the pre-module Data API imports them (collections → the app's data config, access modes → rules, live documents → records) and drops the old collections / app_documents tables in its first migration — back up the database first. An app's preview and production hosts share its records. Module e-mail uses the same SMTP settings as the dashboard login and is capped server-wide by EMAIL_GLOBAL_HOURLY_MAX (default 500 recipients per hour). End users' sign-in codes get a reserved part of it, EMAIL_SIGNIN_HOURLY_MAX (default 20 % of the cap, at least 50, at most half — 100 of 500), one app at most EMAIL_SIGNIN_APP_HOURLY_SHARE percent of those (default 25, at least 10 — raise it on a single-app server); notifications (forms, notifyAdmins) get the rest, and one app at most EMAIL_APP_HOURLY_SHARE percent of that (default 25); one workspace (all its apps) at most EMAIL_WORKSPACE_HOURLY_SHARE percent of each (default 50 — raise it to 100 on a single-workspace server). Past its budget a class pauses for exactly EMAIL_GLOBAL_PAUSE_MINUTES, then starts a fresh hourly budget — notifications pausing never blocks sign-in — and the log gets an email_global_pause ALERT line (with class) — alert on it. The contract and the provider protocol are in MODULES.md.

Volumes (named drobek-prod_<name>):

Environment reference

Every variable drobek, its compose files and its tests read. The production compose file sets the ones marked (compose) itself; everything else is optional unless the table says otherwise, and every limit has a production default. The same variables, with longer comments, are in .env.example (the dev stack) and .env.production.example (self-host). A limit marked (plan) can also come per workspace from the limits provider.

Hosts, image and ports

Secrets and TLS

Sign-in, e-mail and the operator

Apps, compiler and serving

Platform modules

Custom domains, abuse and the gallery

Development and tests only

Backup and restore

task backup
# ✓ backups/drobek-20260923T201500Z.tar.gz — 1234567 bytes in 4 s
#   apps 12 · files 40 · assets 3 · core migrations 20 · image ghcr.io/freema/drobek:v1.2.0 (v1.2.0 abc1234)

One archive (mode 600, in backups/, override with BACKUP_DIR=): db.dump (pg_dump -Fc of the whole database — one consistent snapshot), files.tar (the files_data volume), assets.tar (the assets_data volume), modules.tar (the modules_data volume), caddy_data.tar, SHA256SUMS and a manifest.json with the image tag / id / version / commit, the checkout's commit, a fingerprint of DROBEK_MASTER_KEY, row counts and the size + sha256 of every part. It runs online: postgres is started if it is not running, nothing else is touched; the uploads and assets are archived after the dump, so every file and asset row in the dump finds its bytes (only one deleted or replaced in between can be missing — stop drobek first for a quiesced backup). Schedule it with cron and copy the archives off the machine:

15 3 * * * cd /opt/drobek && task backup >> /var/log/drobek-backup.log 2>&1

Not in the archive: .env.production — it holds DROBEK_MASTER_KEY, without which the restored upstream secrets (proxy module) cannot be decrypted. Keep a copy of it somewhere safe, separately from the backups. Redis is not backed up (sessions, caches, rate-limit counters).

Restore into a stack whose database is empty — a new machine, or this one after docker compose … down -v:

# on the new machine: steps 1–2 of the quickstart (the same or a newer release), then
scp old-server:/opt/drobek/.env.production /opt/drobek/.env.production   # the SAME secrets
task selfhost:init                                     # renders the Caddyfile, keeps every secret
task restore BACKUP=backups/drobek-20260923T201500Z.tar.gz
# ✓ …verified — created 2026-09-23T20:15:00Z, image ghcr.io/freema/drobek:v1.2.0 (v1.2.0 abc1234)
# ✓ restored in 25 s — /healthz {"ok":true,"db":"up","redis":"up"}
#   apps 12 · files 40 (backup: apps 12 · files 40)

task restore verifies the checksums, refuses a DROBEK_MASTER_KEY that does not match the backup's fingerprint (ALLOW_KEY_MISMATCH=1 restores anyway, without usable upstream secrets), refuses a non-empty database (FORCE=1 drops and recreates it — back it up first), stops drobek and caddy, restores the database, replaces files_data, assets_data (left empty when the archive has no assets.tar) and caddy_data, and starts the stack (up -d --wait). Restore with the backup's image version or a newer one (image_version in manifest.json) — a newer image migrates the restored database forward on start; an older one does not know its migrations. Point the DNS records at the new machine; the restored caddy_data carries the certificates over. Sessions (dashboard users and apps' end users) live in Redis, which is not in the backup: after a restore on a new machine everyone signs in again; API keys and OAuth clients are in the database and keep working. A FORCE=1 restore on the same machine leaves Redis as it is.

Upgrades and rollback

The server applies pending migrations itself on every start (the core journal drizzle.__drizzle_migrations_core, then one __drizzle_migrations_mod_<name> per module). An upgrade still runs them as their own step first, so a failing migration stops the upgrade while nothing new is serving:

cd /opt/drobek
git fetch --tags && git checkout vX.Y.Z      # the compose file + scripts of the new release
sed -i 's/^DROBEK_IMAGE_TAG=.*/DROBEK_IMAGE_TAG=vX.Y.Z/' .env.production   # pin it (or keep latest)
task selfhost:upgrade

task selfhost:upgrade is exactly:

task backup                                                   # the rollback point
docker compose --env-file .env.production -f docker-compose.production.yaml pull --ignore-buildable
docker compose --env-file .env.production -f docker-compose.production.yaml pull caddy     # (DNS-01 Caddy: build --pull caddy)
docker compose --env-file .env.production -f docker-compose.production.yaml up -d --wait postgres redis
docker compose --env-file .env.production -f docker-compose.production.yaml stop drobek
task selfhost:migrate     # the new image: applies the release's migrations, exits
task selfhost:migrate     # again: "migrations: nothing to apply (up to date)"
docker compose --env-file .env.production -f docker-compose.production.yaml up -d --wait

task selfhost:migrate is docker compose … run --rm --no-deps -T drobek node dist/server/migrate.js: the server's start-up checks, then every migration, without listening. Running migrations twice (and every later start) is safe: drizzle records each applied migration in its journal table inside the same transaction as the migration itself, so a second run finds everything recorded and applies nothing — the second migrate is the proof that the first one completed, and the up -d that follows migrates nothing. A migration that fails rolls back its transaction and leaves the journal as it was; the old container is already stopped, so fix the cause (or roll back) before starting.

Rollback. previous is the release that was latest before the newest one — but it moves with the next release, so roll back to the exact version:

sed -i 's/^DROBEK_IMAGE_TAG=.*/DROBEK_IMAGE_TAG=vX.Y.W/' .env.production    # the release you came from
# the new release migrated the database? (the migrate output said "applied N")
task restore FORCE=1 BACKUP=backups/<the backup task selfhost:upgrade just took>
# it did not ("nothing to apply" on the first run too):
docker compose --env-file .env.production -f docker-compose.production.yaml up -d --wait

Migrations only go forward; an older image on a database migrated by a newer one is not supported, which is why the upgrade takes a backup first.

Check a live server end to end. The @smoke suite drives the whole MCP loop against a running server over public HTTP only: list_apps, create_app (or re-use), write_files, the preview host, publish and the production host. Give it a service identity that needs no mailbox; --create-user creates the user when that e-mail never signed in:

docker compose --env-file .env.production -f docker-compose.production.yaml exec -T drobek \
  node node_modules/@drobek/oauth/dist/cli/api-key-create.js \
  --email smoke@drobek.example.com --name smoke --scopes read,write,publish --create-user
# on the operator's machine, from a checkout of the same release:
BASE_URL_WEB=https://drobek.example.com SMOKE_API_KEY=drk_… task e2e:smoke

The smoke key always works on one app, smoke-<12 hex>, derived from the key, and publishes a new version of it on every run, so nothing piles up.

Third-party modules

A platform module that does not ship in the image (your company's, one from npm) is installed into the modules_data volume (/data/modules = DROBEK_MODULES_DIR) — no image build, no package manager in the running server:

task selfhost:module:add -- drobek-module-acme-erp@1.2.0
# · npm install drobek-module-acme-erp@1.2.0 → drobek-prod_modules_data:/data/modules/.staging-1a2b3c4d (node:22-alpine, --ignore-scripts)
# ✓ drobek-module-acme-erp@1.2.0 installed as the module "acmeerp" (contract ^1.1) → /data/modules/acmeerp
#   modules.lock.json: sha512-…
#
# Next: enable it in .env.production and restart drobek (it applies the module's migrations on start):
#   DROBEK_MODULES=auth,email,forms,data,proxy,files,drobek-module-acme-erp
#   ./scripts/selfhost-compose.sh up -d --wait drobek

The spec is anything npm install accepts: a registry version (drobek-module-acme-erp@1.2.0, @acme/drobek-module-erp@^1), a tarball URL or a local .tgz path (npm pack output; mounted read-only into the npm container), a git URL (git+https://…/x.git#v1.2.0 — the package must have its dist/ committed). add runs in two steps:

1. npm in a throwaway container — docker run --rm node:22-alpine over the volume: npm install --prefix /data/modules/.staging-<id> --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts <spec>;
2. the image's own installer — ./scripts/selfhost-compose.sh run --rm --no-deps drobek node node_modules/@drobek/modules/dist/cli/module-lock.js add …: the package must declare @drobek/modules as a peer dependency in a range this server satisfies; nested copies of @drobek/*, zod and drizzle-orm are deleted (the server provides them); the module is imported once for its name and checked like at start (its contract against the server's module contract); it moves to /data/modules/<name> and is recorded in modules.lock.json with the server's hashModuleTree() — the same function checks it at every start — then loaded the way the server will load it, the migration lint included. Anything failing leaves the previous install and lockfile in place.

Then put the printed DROBEK_MODULES line into .env.production (the short name for a drobek-module-<name> package, else the full package name) and restart drobek; the start applies the module's migrations and /api/version lists it with "source":"dir". The script prints this and stops: it never edits .env.production and never restarts anything.

task selfhost:module:list
# NAME     PACKAGE                 VERSION  CONTRACT  INTEGRITY           IN DROBEK_MODULES  STATUS
# acmeerp  drobek-module-acme-erp  1.2.0    ^1.1      sha512-q8vN0Lr2Xc…  yes                ok
task selfhost:module:remove -- acmeerp

list reads the lockfile and hashes every module again: changed (files edited after the install), missing (a lock entry without its directory) and unrecorded (a directory the lockfile does not list) refuse the start when DROBEK_MODULES names them — add the module again or remove it. remove deletes /data/modules/<name> and its lock entry and warns when DROBEK_MODULES still names it (take it out before drobek restarts). It never touches the database: the module's tables (mod_<name>, mod_<name>_*) and its journal drizzle.__drizzle_migrations_mod_<name> stay, so adding the module again finds its data. To drop them for good, take a task backup first, list them with the query remove prints and DROP TABLE each in psql (./scripts/selfhost-compose.sh exec postgres psql -U drobek -d drobek).

Upgrade = add with the new version (it replaces the directory and the lock entry; the output names the version it replaced), then restart drobek. Rollback = add of the old version, or task restore of the backup taken before (modules_data is part of every task backup, the lockfile with it). What the script never does: run a package's install scripts, change the image, edit .env.production or restart drobek. A module runs inside the server with the whole database — install only modules you trust (MODULES.md → Installing an external module).

Derived image

An operator with their own CI can bake the modules into an image instead — the same layout, lockfile and start-time checks, built by the image's own installer:

# Dockerfile.drobek — drobek + your modules
ARG DROBEK_TAG=vX.Y.Z
FROM node:22-alpine AS modules
RUN npm install --prefix /modules/.staging-erp --omit=dev --omit=peer --legacy-peer-deps \
      --ignore-scripts --no-audit --no-fund @acme/drobek-module-erp@1.2.0

FROM ghcr.io/freema/drobek:${DROBEK_TAG}
COPY --from=modules --chown=node:node /modules/ /opt/drobek-modules/
RUN node node_modules/@drobek/modules/dist/cli/module-lock.js add \
      --dir /opt/drobek-modules --staging .staging-erp --spec @acme/drobek-module-erp@1.2.0

One RUN npm install + module-lock.js add pair per module (the build fails on anything add refuses). Build it where the stack runs (or docker load it from your CI) under a local tag — docker build -f Dockerfile.drobek --build-arg DROBEK_TAG=vX.Y.Z -t ghcr.io/freema/drobek:vX.Y.Z-acme . — and set in .env.production: DROBEK_IMAGE_TAG=vX.Y.Z-acme, DROBEK_MODULES_DIR=/opt/drobek-modules and the DROBEK_MODULES entries. The directory is outside /data/modules on purpose: the compose file mounts the modules_data volume there, which would hide the image's copy. A local tag cannot be pulled, so an upgrade is a rebuild with the new DROBEK_TAG followed by the task selfhost:upgrade steps without pull. task selfhost:module:* refuse to run with such a DROBEK_MODULES_DIR: the image is the source of its modules.

Image tags

ghcr.io/freema/drobek (linux/amd64 only in v1 — no ARM image):

A release is a pushed vX.Y.Z tag: CI runs the quality gate and the e2e suite against the image it builds from that tag (GIT_SHA = the tag's commit, VERSION = the tag, COMMIT_TIME = that commit's time, all in /api/version), pushes that exact image as vX.Y.Z, then retags in the registry: the former latest → previous, vX.Y.Z → latest. A pre-release tag (vX.Y.Z-rc.1) gets only its own tag. To rebuild a release image yourself: git checkout vX.Y.Z && task build (same sources and lockfile; the build args come from the checkout).

The same tag publishes the npm packages for module authors at its version: @freema/drobek-modules, @freema/drobek-sdk and create-drobek-module (MODULES.md → Writing a module; module code imports the first two as @drobek/modules / @drobek/sdk through npm aliases) — @freema/drobek-modules@X.Y.Z is the module contract of the image vX.Y.Z. node scripts/npm-packages.mjs pack (after pnpm build:packages) writes the same tarballs into dist-npm/.

TLS

The dashboard host always gets a normal ACME certificate (Let's Encrypt via HTTP-01/TLS-ALPN — ports 80 and 443 must be reachable). The app hosts *.<APPS_DOMAIN> use exactly one of three paths; the Caddyfile generator picks it from the environment and refuses combinations. task selfhost:init TLS_MODE=<mode> sets the variables below in .env.production and renders deployments/Caddyfile (gitignored) with the image's generator; after editing them by hand, re-run task selfhost:init and task tls:reload:

TLS_ACME_EMAIL (optional) is the ACME account e-mail for expiry notices.

The generator reads .env.production, refuses ambiguous or invalid settings instead of guessing, and writes a Caddyfile that contains no secrets: the ask token is referenced as {$TLS_ASK_TOKEN} and DNS credentials as {env.NAME} placeholders, both resolved from Caddy's own environment. In a development checkout task caddy:config runs the same generator on the host (Node 22 + the built @drobek/core) from .env.

(a) Wildcard certificate files

You obtain a *.<APPS_DOMAIN> certificate yourself (any ACME client with DNS-01, or a commercial CA) and renew it yourself.

task selfhost:init TLS_MODE=wildcard-file
# .env.production now has (paths INSIDE the caddy container):
#   TLS_WILDCARD_CERT_FILE=/certs/wildcard.crt
#   TLS_WILDCARD_KEY_FILE=/certs/wildcard.key
#   TLS_CERTS_DIR=./certs      (host directory mounted read-only at /certs)

Put the full chain in certs/wildcard.crt and the key in certs/wildcard.key. After every renewal:

task tls:reload   # caddy reload --force: re-reads the config AND the certificate files

A plain caddy reload skips an unchanged config, so it would keep serving the old certificate — the task passes --force. Hook task tls:reload into your renewal tool's deploy hook. Generated app block:

*.apps.example.com {
	tls /certs/wildcard.crt /certs/wildcard.key
	import drobek
}

(b) DNS-01 with a Caddy DNS module

Caddy obtains and renews the wildcard itself over ACME DNS-01. That needs a Caddy binary with a DNS provider module, which deployments/Dockerfile.caddy builds with xcaddy:

task selfhost:init TLS_MODE=dns TLS_DNS_PROVIDER=<provider> \
  CADDY_DNS_MODULE=github.com/caddy-dns/<provider>
# .env.production now has CADDY_IMAGE=drobek-caddy:dns, CADDY_BUILD_TARGET=dns,
# CADDY_DNS_MODULE, TLS_DNS_PROVIDER and TLS_DNS_PROVIDER_ARGS={env.DNS_API_TOKEN}
# (provider-specific, placeholders only)

# .env.caddy — credentials for Caddy ONLY (drobek never sees them)
DNS_API_TOKEN=…

docker compose --env-file .env.production -f docker-compose.production.yaml build caddy

Modules exist only for some DNS hosts — check github.com/caddy-dns first. There is no Hostinger DNS module: Caddy DNS modules are built on libdns, and github.com/libdns/hostinger does not exist — a zone hosted at Hostinger cannot answer DNS-01 through Caddy directly. Use the CNAME delegation below (or path (a)).

Delegating _acme-challenge with a CNAME. When your zone's DNS host has no module, point the challenge name at a zone you keep at a provider that has one, and tell Caddy to write the TXT record there:

; in the APPS_DOMAIN zone (at the provider without a module)
_acme-challenge.apps.example.com.  CNAME  _acme-challenge.acme-delegate.example.net.

# .env.production — the delegate zone acme-delegate.example.net is hosted at <provider>
TLS_DNS_PROVIDER=<provider>
TLS_DNS_PROVIDER_ARGS={env.DNS_API_TOKEN}
TLS_DNS_CHALLENGE_OVERRIDE_DOMAIN=_acme-challenge.acme-delegate.example.net

The ACME CA follows the CNAME and finds the TXT record in the delegate zone; the credentials only ever touch that small zone. Generated app block:

*.apps.example.com {
	tls {
		dns <provider> {env.DNS_API_TOKEN}
		dns_challenge_override_domain _acme-challenge.acme-delegate.example.net
	}
	import drobek
}

(c) On-demand, one certificate per app host

With no wildcard, Caddy issues a certificate for each app host at its first TLS handshake. That is always gated: before every new certificate Caddy asks drobek, and drobek says yes only for a host of an existing app. task selfhost:init generates TLS_ASK_TOKEN (for every mode) and the compose file hands the same value to drobek and to Caddy.

{
	on_demand_tls {
		ask http://drobek:3000/api/internal/tls/ask?token={$TLS_ASK_TOKEN}
	}
}
*.apps.example.com {
	tls {
		on_demand
	}
	import drobek
}

GET /api/internal/tls/ask?domain=<host>&token=<TLS_ASK_TOKEN>:

The endpoint is internal: Caddy refuses /api/internal/* with 404 on every public site, drobek answers it only on the internal address (drobek:3000, never the public dashboard host), and only with the token. A set-but-weak TLS_ASK_TOKEN (shorter than 32 characters or not URL-safe) stops drobek from starting; the generator refuses on-demand mode without a valid one.

Caveats: the first request to a new app host waits for issuance (seconds); Let's Encrypt limits certificates per registered domain per week (see its rate-limit documentation), and each app has up to three kinds of hosts plus one per version URL you open — fine for a self-host with a handful of apps, not for a busy multi-tenant instance (use (a) or (b) there). Certificates stay cached in caddy_data after an app is deleted until they expire.

Custom domains

An app can also answer on a host name its owner controls (M3-01). The owner adds it on the app's Domains tab in the dashboard (editor or workspace-admin), creates two DNS records and clicks Verify:

• Apex domains (example.org) cannot carry a CNAME. Use the DNS provider's ALIAS / ANAME / CNAME flattening to <slug>.<APPS_DOMAIN>, or plain A/AAAA records with the server's addresses — verification accepts a name whose addresses are all addresses of <slug>.<APPS_DOMAIN>.
• Refused names: anything under APPS_DOMAIN, the dashboard host or drobek.app; IP literals; names that are not a registrable domain or below one per the Public Suffix List (co.uk, github.io); special-use TLDs (.localhost, .local, .internal, …). Names are stored in lower-case ASCII (IDN → punycode).
• Limits: DOMAINS_MAX_PER_APP (default 3) per app, pending and verified together; the next add fails with limit_exceeded. 0 turns custom domains off: the Domains tab says so and offers no add form. The limits provider may set it per workspace (e.g. a plan without custom domains). One host name is verified for at most one app on the instance — an unverified claim never blocks the real owner.
• Serving: a verified domain serves the app's published version (indexable, like <slug>.<APPS_DOMAIN>). Marking one domain primary makes <slug>.<APPS_DOMAIN> answer 302 to it (GET/HEAD, outside /__drobek/); preview and version hosts never redirect. A registered but unverified name answers 404 on the apps side; an unknown name stays the dashboard's.
• Re-check: verified domains are re-checked once every 24 h (a sweep runs every DOMAINS_RECHECK_INTERVAL_MS, default 1 h, under a Redis lease so only one replica does it). A definitive failure — the TXT record gone or wrong, the name no longer pointing at the app — drops the verification (audit domain.unverify) and e-mails the app's workspace editors and admins. A timeout or SERVFAIL never drops anything. Lookups use the system resolver, or DOMAINS_DNS_SERVERS (comma-separated IPs), 5 s per lookup.
• Audit: domain.add, domain.verify, domain.unverify, domain.primary, domain.remove.
• Over MCP an agent does the same as the Domains tab (see AGENT.md): list_domains, add_domain (returns both records), verify_domain, set_primary_domain and remove_domain — same checks, limits and audit rows (actor kind agent). Setting or clearing the primary domain and removing a verified one need the user's explicit yes (user_confirmed: true). The publish result lists the app's verified domains in domains.

TLS for custom domains

The generated Caddyfile carries a catch-all site for every other host name, issued on demand behind the same ask endpoint:

https:// {
	tls {
		on_demand
	}
	import drobek
}

drobek's ask answers 200 only for a verified domain of a live app, so an unknown SNI never triggers an ACME order. The catch-all is on by default in mode (c); in modes (a) and (b) set TLS_CUSTOM_DOMAINS=1 (then TLS_ASK_TOKEN is required as well — the generator refuses otherwise); TLS_CUSTOM_DOMAINS=0 turns it off. Re-run task selfhost:init + task tls:reload after changing it (task caddy:config in a development checkout).

Certificate lifecycle: Caddy obtains the certificate at the first HTTPS request after verification (HTTP-01 on port 80 or TLS-ALPN-01 on 443 — both must reach Caddy; the first request waits a few seconds) and renews it itself. Removing a domain or losing its verification stops serving it and refuses new certificates, but does not revoke the one already issued — it stays in caddy_data until it expires. Let's Encrypt's per-domain rate limits apply per customer domain.

Development: the dev compose file sets DOMAINS_DNS_MOCK=redis, which answers the lookups from Redis keys drobek:dns-mock:<txt|cname|a|aaaa>:<name> (a JSON string array; "SERVFAIL" simulates a transient failure) and admits the .test TLD. It is ignored, with a warning, when NODE_ENV=production.

Abuse and takedowns

Anyone can publish on a public drobek, so the operator (every address in SUPERADMIN_EMAIL) gets a moderation queue. Nothing is blocked automatically.

• Report pointer. Every app host answers GET /.well-known/drobek-report with { report_url, app, terms_url } — report_url is the public form on the dashboard origin, <PUBLIC_APP_URL>/report?host=<host>. Every app-host response also carries X-Drobek-App: <slug>, so a URL or a header in an abuse complaint maps to one app.
• Report form (/report, no login): host, reason (phishing, malware, spam, copyright, illegal, other), details (≤ 2 000 characters), an optional reporter e-mail and a honeypot. ABUSE_REPORTS_PER_IP_HOUR (default 5) valid reports per client IP per hour. A report is stored in abuse_reports (the reporter's IP only as a keyed hash), audited abuse.report in the app's workspace, and e-mailed to the super-admins and OPERATOR_EMAIL (each address once) — at most once per app per hour.
• Queue (/admin/abuse, super-admins only, 403 for everyone else): the open reports with the app and workspace behind each host.
  • Take down (pick a reason category): the app is unpublished and locked (apps.locked_reason). Its production, preview, version and custom-domain hosts answer 451 with a link to TERMS_URL (default <PUBLIC_APP_URL>/terms; set it when your dashboard origin has no terms page); module routes answer JSON 451. The agent's write_files, restore_version, publish and configure_module fail with app_locked_by_admin (naming the category only); new versions, publish and restore are refused for the dashboard too (the module-confirm API answers 423). The owners (editors and workspace-admins of the workspace) get an e-mail. Audited admin.takedown; the app's open reports are resolved.
  • Restore: the lock is lifted — the app is NOT republished, its owner publishes again. Owners get an e-mail; audited admin.restore.
  • Mark resolved: closes a report without acting.
• Publish heuristic. Every publish scans the published version (HTML + JS): a password field AND a word from ABUSE_BRAND_WORDS (comma-separated; unset = a built-in list of ~25 bank / payment / e-mail / social / crypto names plus "bank") in the <title>, an <h1>, the page text or a JS string files a heuristic report into the queue and logs event: abuse_heuristic_flag at warn. The publish itself goes through; one open heuristic report per app at a time.

DMCA notices and the legal side of abuse handling belong to your terms of service, not to drobek.

Public gallery

With GALLERY_ENABLED=true the server keeps a public list of apps whose owners chose to show them. Off by default: a fresh server publishes no app list.

• Listing. On an app's Overview tab (Gallery section; the Settings tab, where visibility and embedding live, links to it) an editor or workspace-admin of a published app ticks "Show in the gallery" and writes a public description (plain text, one or two sentences, at most 160 characters). An agent can do the same with the MCP tool set_gallery_listing (scope publish), but only with user_confirmed: true — its instructions allow that only after the user explicitly said yes. Viewers cannot list (403). Audited app.gallery_listed / app.gallery_unlisted.

• Leaving the gallery. Unlisting takes effect at once. Unpublishing the app or a takedown also ends the listing (the owner lists again after the next publish), and a deleted app is gone with it. The public list filters at query time: only apps that are listed, published, public (no password gate), not taken down, not deleted and not hidden appear.

• Hiding. A super-admin sees every listed app in the Gallery section of /admin/abuse and can hide an entry (or show it again). A hidden app is off the list and neither its owner nor an agent can list it. Audited app.gallery_hidden / app.gallery_unhidden.

• Duplicates. With "Allow duplicates" on (next to "Show in the gallery"; off by default), your gallery website can show a Duplicate button linking to the item's duplicateUrl. A visitor signs in (and comes back), picks a workspace where they are an editor or higher and a name, and gets a new, unpublished app with the published files as version 1 — the MCP tool duplicate_app does the same. The source's module settings are proposed to the copy, and those that need a confirmation wait on its Modules page; e-mail addresses in them and proxy upstreams are dropped. Secrets, data, end users, uploads, app assets, domains and the listing are never copied. Audited app.duplicate (the new app) and app.duplicated (the source, without the copier). DUPLICATES_PER_USER_HOUR (default 10) caps copies per person per hour.

• GET /api/public/gallery on the dashboard host, no login. Each item is { name, description, url, publishedAt, modules, duplicable, duplicateUrl, duplicates, likes, opens, openUrl, likeUrl } — url is the production host https://<slug>.<APPS_DOMAIN>, modules the names of the modules the app has settings for, duplicable whether the owner allows duplicates, duplicateUrl the dashboard page that duplicates it (<PUBLIC_APP_URL>/duplicate/<slug>, null when not duplicable), duplicates how many live copies were made, likes the number of accounts that like the app and opens the visits through openUrl in the last 30 days (UTC). No owner data (no e-mail, workspace or id) and nothing about who liked or opened. Parameters:

  • ?limit= 1–48 (default 24);
  • ?q= a case-insensitive substring of the name or the description (trimmed, at most 100 characters; %, _ and \ match themselves);
  • ?sort=new (default: newest publish first), ?sort=name (A→Z, case-insensitive) or ?sort=popular (5 × likes + opens in the last 30 days, highest first; ties newest first);
  • ?cursor= the previous page's next (cursor mode), or ?page= a 1-based page number (page mode).

  Two response shapes:

  • cursor mode (the default; sort=new without page, or with a cursor): { items, next? } — next is there while more entries follow;
  • page mode (?page= without a cursor, and always with sort=name or sort=popular, which ignore a cursor): { items, page, pages, total } — total and pages count the filtered list (pages is 0 when nothing matches); a page that is not a whole number ≥ 1 is page 1, a page past the last has no items; previews is true when GALLERY_FRAME_ANCESTORS is set (the gallery may frame the listed apps).

  For example ?q=shift&sort=name&page=2&limit=12 → { "items": [ … ], "page": 2, "pages": 3, "total": 29 }, and ?q=shift → { "items": [ … ], "next": "MTc1…" }. Cache-Control: public, max-age=60, Access-Control-Allow-Origin: *, GALLERY_API_PER_IP_MINUTE requests per client IP per minute. Render it on your own website — a server-side fetch or a reverse proxy works as well as the browser.

• Opens. Link a card to its openUrl (/gallery/open/<slug> on the dashboard host): it adds one to the app's count for the day and redirects to url. Only a GET counts — not HEAD, not a browser prefetch or prerender (Sec-Purpose / Purpose) and not more than GALLERY_OPENS_PER_IP_HOUR visits per client IP per hour (the redirect still works). The server stores a count per app and day, never who opened it.

• Likes. Link a like button to likeUrl (/gallery/like/<slug>), with ?back=<your gallery URL> to return there. The page asks the visitor to sign in to drobek (any account), then shows the count and a "Like this app" / "Remove my like" button. One like per account; the public list shows only the count. back is followed only when its origin is one of GALLERY_FRAME_ANCESTORS, otherwise the page stays on drobek. At most GALLERY_LIKES_PER_USER_HOUR changes per account per hour (429 over it). A deleted account or app takes its likes with it.

• Live previews. Apps refuse to be framed by other sites (frame-ancestors). To show each listed app as a live preview (a scaled, sandboxed, non-interactive <iframe> of its url), set GALLERY_FRAME_ANCESTORS to your gallery website's origin(s), e.g. https://www.example.com. Those origins may then frame the production host (and custom domains) of an app the gallery shows right now — listed, published, public, not taken down, not deleted, not hidden. The preview and version hosts never allow it, and other apps keep refusing. Unlisting, hiding, unpublishing, a password gate or a takedown withdraws the permission with the next request (at the latest after the app hosts' 60 s cache). Only while GALLERY_ENABLED is on; an invalid origin stops the server at start. Frame the app non-interactively (e.g. sandbox="allow-scripts allow-same-origin", pointer-events: none, loading="lazy"): each preview load runs the app like any visit and counts in its request stats.

There are no screenshots: drobek never runs an app's code on the server.

Publish approval

Anyone can sign up on a drobek server, create workspaces, and build and preview apps. What goes on an app's public production host is decided in two places:

• The server mode, PUBLISH_APPROVAL:
  • open (the default) — every workspace may publish.
  • approval — a workspace publishes only after a super-admin allowed it, or when a super-admin is one of its members. Needs SUPERADMIN_EMAIL; the server refuses to start without it, and on any other value.
• Each workspace's state, set by a super-admin: default (the mode decides), allowed (may publish in both modes) or blocked (may not publish in either mode). Setting one clears the other.

For one publish: a super-admin publishing is always allowed; a blocked workspace is refused; an allowed workspace, or one with a super-admin member, may publish; otherwise open allows and approval refuses. The check sits in publish() itself, so the dashboard's Publish, an agent's publish and a rollback (a publish too) share it. Previews, versions, restore, data, secrets, domains and everything else are never gated.

Blocking is the switch for an open server: people publish without waiting for you, and you turn a workspace off when it misuses that.

• A blocked publish changes nothing and answers publish_blocked: "Publishing from this workspace was turned off by the operator of this server (<contact>). Previews, versions and everything else keep working; live apps keep serving unless taken down." No approval request is sent; the dashboard shows "Publishing from this workspace was turned off by the operator (<contact>)." and disables the Publish buttons.
• Blocking does not unpublish anything. To remove an app, take it down (the publishing page lists each workspace's live apps with the takedown form of the moderation queue).
• Blocking and unblocking e-mail the workspace's editors and admins what happened and whom to contact (delivery errors are logged, never fatal).

Approval (PUBLISH_APPROVAL=approval):

• An unapproved publish changes nothing and answers publish_not_approved: "Publishing on this server needs approval from <contact> … An approval request was sent to <contact> …".
• The approval request is e-mailed to OPERATOR_EMAIL (else every super-admin) on the first refused publish or when a member clicks Request approval — the workspace, the requester's e-mail (also the Reply-To), the app and a link to /admin/publishing. At most one e-mail per workspace per 24 hours until a super-admin decides; the request is stored on the workspace and audited (workspace.publish_approval_request).
• Owners see it: the workspace's apps list and every app page say "Publishing on this server needs approval from <contact>" with a Request approval button (editor+); the Publish buttons are disabled.

The contact is OPERATOR_EMAIL, else the first SUPERADMIN_EMAIL address. Agents see can_publish, publish_contact and the workspace's publishing state in list_apps and get_app.

Decide at /admin/publishing (super-admins only; linked from /workspaces and the moderation queue): every workspace with its state, admins, apps and live apps; filters for waiting requests, default, allowed and blocked; ?workspace=<slug> shows one. In open mode Block publishing / Unblock come first; in approval mode Approve / Revoke approval / Block publishing. Audited workspace.publish_approve, workspace.publish_revoke, workspace.publish_block and workspace.publish_unblock. A super-admin's agent can do the same with the MCP tool set_workspace_publishing({ workspace, publishing: default | allowed | blocked, user_confirmed }) (user_confirmed: true after the super-admin's explicit yes); other users never see that tool.

Publish notifications (PUBLISH_NOTIFY, off by default): first e-mails OPERATOR_EMAIL (else every super-admin) about the first publish of each app, every about every publish — at most one e-mail per app per hour. The e-mail names the app, its live URL and custom domains, the workspace, who published it from the dashboard or over MCP, the version and whether it was the first publish, a republish or a rollback, with links to the app, its dashboard page and /admin/publishing?workspace=<slug> (take the app down, block the workspace). A super-admin's own publishes are not e-mailed. The e-mail is sent after the publish and never delays or fails it.

Abuse reports go to every super-admin and to OPERATOR_EMAIL (each address once).

Upgrading approves every workspace that already had a published app (migration 0026), so switching to approval never blocks the next publish of an app that was live then; migration 0027 adds the block.

The rehearsal (task selfhost:rehearsal)

scripts/selfhost-rehearsal.sh runs this guide end to end on throwaway stacks (unique COMPOSE_PROJECT_NAMEs, every port on 127.0.0.1, a throwaway Mailpit as the SMTP server): it builds the image, copies only the self-host files into a fresh directory ("machine A"), runs task selfhost:init twice (idempotency) and docker compose config (no warnings), starts the stack, signs a user in over the e-mail code flow, mints an API key with the container CLI, creates + writes + publishes an app over MCP (the official SDK client) and uploads a file through the files module; installs a packed module with task selfhost:module:add, enables it and checks /api/version loads it from the modules directory; then task backup, down -v, a second fresh directory ("machine B") with only machine A's .env.production, task selfhost:init, task restore, and asserts the app serves on its host, the file downloads byte for byte, the same API key works, Caddy's restored CA still validates and the server starts with the same modules.lock.json and the module; a second restore must be refused and a second task selfhost:migrate must apply nothing. It prints the wall-clock time of every phase. Not part of task check or CI (it takes minutes). Knobs: REHEARSAL_HTTPS_PORT (9443), REHEARSAL_SKIP_BUILD=1, REHEARSAL_KEEP=1 (see the script header).

Development: task dev:tls

The dev stack normally runs on plain HTTP (task up, http://localhost:3041, http://<slug>--preview.apps.localhost:3041). To run it behind Caddy with its local CA:

task dev:tls        # generates .caddy/Caddyfile.dev (TLS_INTERNAL=1), starts caddy on :443,
                    # copies Caddy's root CA to .caddy/root.crt
curl --cacert .caddy/root.crt https://localhost/healthz
curl --cacert .caddy/root.crt \
  --resolve x--preview.apps.localhost:443:127.0.0.1 https://x--preview.apps.localhost/
task dev:tls:down   # remove caddy, back to the plain HTTP dev stack

It layers docker-compose.tls.yaml over the dev compose file: drobek switches to PUBLIC_APP_URL=https://localhost, APPS_DOMAIN=apps.localhost, APPS_URL_SCHEME=https and TRUST_PROXY=x-real-ip. If port 443 is taken on your machine, use task dev:tls DEV_TLS_PORT=8443 — every URL then carries :8443.

The root CA stays in the caddy_dev_data volume; drobek never installs it anywhere (skip_install_trust). To make browsers trust it, import .caddy/root.crt into your OS or browser trust store yourself — or keep using curl --cacert / NODE_EXTRA_CA_CERTS=.caddy/root.crt.