Deployment profiles
These are the three existing deployment layouts. Build Host with go build -o simple-host ./cmd/simple-host.
Build Hack with go build -o simple-hack ./cmd/simple-hack.
The settings registry is settings.json; its only
required: true entries are ADMIN_API_KEY and DB_DSN
(docs/advanced/settings.json:585, docs/advanced/settings.json:3130).
Addresses, persistence and sign-in still need the profile-specific choices below.
The offline check is bash scripts/check-profiles.sh.
Hosted systemd
What runs
Simple Host at simple-host.app uses /usr/local/bin/simple-host.
Simple Hack at simple-hack.app uses /usr/local/bin/simple-hack. The programs come from
one commit, with separate accounts, databases and data directories
(deploy/prod/simple-host.service, deploy/hack/simple-hack.service).
The Host unit runs as simplehost, writes /srv/simple-host/sites and reads
/etc/simple-host.env; Hack runs as simplehack, writes /srv/simple-hack/sites
and reads /etc/simple-hack.env. Both restart on failure and have a 768M memory
cap (deploy/prod/simple-host.service:8,
/etc/systemd/system/simple-host.service:8,
/etc/systemd/system/simple-hack.service:7, read on 2026-11-04).
nginx fronts the HTTP listeners: Host on 127.0.0.1:8090, Hack on 127.0.0.1:8091
(deploy/prod/nginx-sites-content-host.conf:25, deploy/hack/README.md:4).
Workers run inside each server process; see the shared worker list below.
How settings are supplied
systemd loads the respective EnvironmentFile. Neither inspected unit exposes
individual setting names or values; the env files were not opened.
Each must supply ADMIN_API_KEY and DB_DSN, with different databases for the
two instances. Set SITE_DOMAIN, PUBLIC_BASE_URL, DATA_DIR, PORT and
BIND_ADDR to that instance’s address, directory and loopback listener; Hack
accepts EVENTS=hosted or unset for compatibility. Host refuses EVENTS=hosted;
the program selects the product, not the environment. This describes the required operator contract,
not a verification of secret-file contents (deploy/prod/simple-host.service:11,
/etc/systemd/system/simple-hack.service:9, host/config/config.go:16,
deploy/hack/README.md:4). Hosted family addresses use PERSON_HOSTS=canonical
and SITE_HOSTS=canonical (ARCHITECTURE.md, Deploy).
Migration ownership
Hosted: the operator owns migrations; startup migration is off.
Neither inspected unit sets MIGRATE_ON_START. Before installing, run the
candidate’s migrate -status and then migrate, once per database, as that
unit’s user with its environment. Host uses /tmp/simple-host.new.
Hack uses /tmp/simple-hack.new. Each candidate embeds its own migration set;
Host refuses Hack’s recorded database. The migration command takes the
advisory lock. Use migrate -mark FILE only for SQL already applied by hand.
A fresh empty database needs the matching program’s
migrate -init -record-product; do not load schema.sql separately. An existing
database with no product record needs that program’s explicit
migrate -record-product once. Ordinary startup checks the recorded product
and schema (host/server/migrate.go, host/server/build.go).
The shared migration rules below apply.
Upgrade steps and rollback
Before changing either instance, take paired database and site-directory backups
and retain its settings/sealing keys. Build both programs from one commit under
the memory cap and migrate each target database with its matching candidate.
Back up /usr/local/bin/simple-host with a .bak-<timestamp> suffix.
Back up /usr/local/bin/simple-hack with the same timestamp. Install both
candidates at their respective paths, and restart both services. See CLAUDE.md for the paired command.
Rollback restores both programs from the same timestamp and restarts both
services, provided their commit is no older than the coordination file’s
oldest-safe floor. To undo the initial split, restore the previous Hack unit
and the saved combined program, reload systemd and restart both services.
Binary rollback does not undo SQL or data moves. See the shared compatibility
limits below; a data restore includes the matching database, site directory,
configuration/keys and program together.
Verify /healthz, /readyz, the changed route and site/person/legacy addresses
from a client, and check neighbouring sites and startup logs. Run
/usr/local/bin/simple-host version. Also run /usr/local/bin/simple-hack version.
Both programs must print the same release and commit.
Docker Compose small box
What runs
The root compose.yaml runs Postgres 16, one server container and Caddy.
The server image is the nonroot Go binary, HTTP 8090, DATA_DIR=/data/sites;
Caddy publishes 80/443 by default. Named volumes hold the database, sites,
Caddy logs, certificates and config. Caddy proxies APIs and can serve site files
from its read-only sites mount (compose.yaml:14, compose.yaml:37,
compose.yaml:277, Dockerfile:31, deploy/compose/Caddyfile:86).
The root Dockerfile defaults to its host target and starts simple-host
directly. Root Compose does not pass EVENTS through. Its optional static
profile renders a simple-host static service with read-only site files and a
separate writable state volume. It is off by default; routing and end-to-end
acceptance belong to D4-S5a, so enabling the profile alone does not change
Caddy’s upstream.
Workers run inside the server process, as listed below.
Standalone Hack and its Coolify variant are the same Compose profile, with a
different package: Postgres plus an app container running both Caddy and the
server, and a one-shot release container. Build the root Dockerfile’s hack
target, then use it as the standalone Dockerfile’s SIMPLE_HOST_IMAGE build
argument. The standalone entrypoint starts simple-hack beside Caddy.
Its /data volume holds sites, logs and Caddy state; the server listens on
127.0.0.1:8090, Caddy on 8081/8443 with health on 8080. Default published ports
are 80/443 and loopback 18080. Coolify uses Traefik and TLS passthrough instead
of those host port bindings (deploy/hack/standalone/compose.yaml:9,
deploy/hack/standalone/Dockerfile:12, deploy/hack/standalone/start.sh:68,
deploy/hack/standalone/coolify/compose.yaml:133).
How settings are supplied
Compose substitutes .env/shell values into explicit container environment
entries. Root Compose requires DB_PASSWORD and ADMIN_API_KEY, constructs
DB_DSN, and passes SITE_DOMAIN and PUBLIC_BASE_URL. Blank SITE_DOMAIN
deliberately enters browser setup; configure the real domain/base URL before
normal use. Dockerfile supplies the persistent DATA_DIR and port
(compose.yaml:19, compose.yaml:40, Dockerfile:37).
Standalone also requires PASSCODE_ENC_KEY, ANALYTICS_SALT and SITE_DOMAIN;
it derives PUBLIC_BASE_URL and enables password sign-in by default. With password
sign-in off, it requires either complete OIDC settings or RESEND_API_KEY plus
MAIL_FROM for sign-in. TLS_MODE/ACME_CA configure its
wrapper/Caddy, not Go server settings (deploy/hack/standalone/compose.yaml:14,
deploy/hack/standalone/start.sh:16, deploy/hack/standalone/start.sh:68).
Migration ownership
Compose: the installer migrates before starting the new app.
The root installer pulls the image, starts the database, runs
docker compose run --rm -T app migrate -init -record-product, then starts
the app. Failure leaves the app unrestarted. Compose also gates app startup on
the one-shot migrate service, which initializes an empty database or records
an existing install and applies pending migrations under the advisory lock.
Standalone’s installer stops the app and runs release before starting it;
Compose also gates app startup on successful release. Its entrypoint runs
simple-hack migrate -init -record-product, initializing the platform and Hack
schemas together. Both products keep their site volumes across restarts.
The installer rehearsals build local images, sign in, publish a site and check
it after restarting the app; they also run the pre-D4-S7b Compose files with
the new images (deploy/install/product_init_test.py).
Upgrade steps and rollback
Take paired DB/files backups and keep .env and sealing keys. Re-run the
versioned installer; root Compose uses the published image, not a local build.
Standalone’s upgrade.sh delegates to its new package’s installer
(deploy/install/install.sh:273, deploy/hack/standalone/upgrade.sh:1).
Rollback selects the previous IMAGE/SIMPLE_HACK_IMAGE and recreates the app
with the matching package; keep the existing volumes. SQL stays applied, subject
to the compatibility limits below. If restoring data, restore the DB and sites
volume together (standalone: DB and /data). The database records live versions
while files hold those versions and runtime SQLite/uploads
(ARCHITECTURE.md, Data model; compose.yaml:290).
Check public HTTPS, /healthz, /readyz, a deployed site and logs; check the
actual image’s release with docker compose exec app simple-host version for
Host or docker compose exec app simple-hack version for standalone Hack.
Kubernetes
What runs
The Simple Hack Helm chart and rendered manifests run one server container,
external Postgres, and an existing ingress/load balancer. HTTP is 8090; TLS
ends upstream. One replica and Recreate stop the old pod before the new one
uses the ReadWriteOnce volume. /data/sites and /data/geoip are on /data;
/tmp is an emptyDir. Workers remain inside this one server process
(deploy/kubernetes/simple-hack/templates/deployment.yaml:8,
deploy/kubernetes/simple-hack/templates/configmap.yaml:10,
docs/kubernetes.md:1).
How settings are supplied
envFrom loads a ConfigMap and Secret. Values set SITE_DOMAIN,
PUBLIC_BASE_URL, EVENTS=hosted, persistence paths and port; extraConfig and
extraSecrets add registry names. Set host, a database DSN (or existing Secret),
and password sign-in (on by default), OIDC credentials or email sign-in credentials. ADMIN_API_KEY is generated
and retained by Helm, or supplied in your existing Secret; DB_DSN is supplied
by you. Rendered YAML needs a persistent Secret created separately
(deploy/kubernetes/simple-hack/templates/configmap.yaml:10,
deploy/kubernetes/simple-hack/templates/secret.yaml:11,
deploy/kubernetes/simple-hack/templates/deployment.yaml:72,
deploy/kubernetes/simple-hack/values.yaml:194, docs/kubernetes.md:17).
teamSites.flatHosts (off by default, matching simple-hack.app) renders
TEAM_SITE_FLAT_HOSTS: on, a team’s site is the single label
<team>--<event>.<SITE_DOMAIN> instead of <team>.<event>.<SITE_DOMAIN>, so
the chart’s one *.<host> Ingress rule and certificate cover every event
and team without a per-event ingress.events entry or certificate SAN
(docs/kubernetes.md, certificate prerequisite).
Migration ownership
Kubernetes: the server migrates before listening.
The default migrateOnStart: true renders MIGRATE_ON_START=true. On every start,
the server waits for Postgres, initializes schema.sql if public.users is
absent, applies pending files under the advisory lock, and checks the schema.
The database role must own the database. With migrateOnStart disabled, the
operator must run the same image’s migrate -init first
(deploy/kubernetes/simple-hack/values.yaml:37, cmd/server/main.go:115,
host/db/migrations/migrations.go:417, docs/kubernetes.md:175).
Upgrade steps and rollback
Back up Postgres and the /data volume as a pair, preferably with the pod
scaled to zero, and preserve the Secret, especially PASSCODE_ENC_KEY.
Change the image tag with helm upgrade (or update/apply rendered YAML), wait
for rollout and inspect logs. Recreate means downtime during migration/startup.
Use helm rollback or restore the previous manifest/image for binary rollback;
SQL stays applied. Earlier successful migration files remain committed if a
later file fails. Restore DB plus volume together if data rollback is needed
(docs/kubernetes.md:152, docs/kubernetes.md:187,
host/db/migrations/migrations.go:20). Check external /healthz, /readyz, a team
site, and kubectl exec the pod’s /usr/local/bin/simple-hack version.
The Hack image keeps a simple-host alias for existing chart commands for
this release only; a locally built chart image must use --target hack.
The chart probes healthz for startup/liveness and readyz for readiness
(deploy/kubernetes/simple-hack/templates/deployment.yaml:91).
Shared worker and migration details
Workers are goroutines in the server, not separate queue services in any
profile. cmd/server/main.go starts connector expiry sweep (:379), hosted
Hack cleanup (:421), optional event-domain sweep (:509), API metric flushing
(constructor at :532, host/handler/apimetrics.go:94), optional access-log
analytics (:563), then certificate requests, Hack settlement, event cleanup
and content delivery, deleted-site purge, idle cleanup, saved-data sweep,
submission emails, notification delivery, address-family checks, network usage,
image scanning and optional paper metrics (:598). Conditions/settings can
leave workers inactive; setup mode returns before normal worker wiring (:155).
Migrations are forward-only: there is no down command. New files must be
NNNN-name.sql, next free number, plain idempotent SQL, additive and safe on a
live DB. The runner uses the frozen legacy order then numbered files, skips
historical baseline files, and commits each file with its schema_migrations row
under a per-database Postgres advisory lock (host/db/migrations/migrations.go:4,
host/db/migrations/migrations.go:302). Init uses that same lock; manual SQL does not.
An older binary is intended to work on the newer additive schema, but startup
does not prove full backwards compatibility. VerifySchema checks only the
presence of its listed tables/columns; hosted Hack also checks its listed
columns and the existence of event_teams_name_idx. It does not compare schema
versions, reject extra columns/newer migration rows, or check column types or
index definitions. Missing requirements abort startup; extra schema is accepted
(cmd/server/main.go:131, host/db/schemacheck.go:170,
host/db/schemacheck.go:196). /healthz means HTTP is answering; /readyz
also pings Postgres (host/handler/health.go:19). The version command needs
no database and prints release/commit plus embedded migration information
(cmd/server/migrate.go:148).
| Choice | Hosted systemd | Compose small box | Kubernetes |
|---|---|---|---|
| Server | Two services, one program per product | One app; standalone bundles Caddy | One pod, Recreate |
| Settings | Separate env files | .env substitution, explicit environment | ConfigMap + Secret from values |
| Database | Separate DB per instance | Bundled Postgres 16 | Operator’s Postgres 16 |
| Files | Separate /srv site trees | Named sites or data volume | /data persistent volume |
| Migrations | Operator before restart | Installer/release before app | Server on start by default |
| Empty DB | Matching program: migrate -init -record-product | Postgres init or standalone release | Server migrate -init path |
| Rollback | Paired program backups + restart | Previous image/package | Helm rollback/previous image |
| Restore | Paired DB + site tree + keys | Paired DB + files volume + keys | Paired DB + /data + Secret |
Password sign-in by profile
Hosted systemd: leave PASSWORD_SIGNIN=off (binary default); existing email and provider sign-ins continue.
Docker Compose small box, standalone Hack and Coolify: PASSWORD_SIGNIN and PASSWORD_SELF_SIGNUP default to on and are passed through. No mail or identity provider is required for password sign-in.
Kubernetes: signIn.password.enabled: true and signIn.password.selfSignup: true render both settings as on; setting either false renders off. Password sign-in satisfies the chart’s sign-in requirement without OIDC or Resend.
An operator may set PASSWORD_SELF_SIGNUP=off and create/reset accounts through Admin Users. People must change temporary passwords before completing sign-in. Existing email accounts can receive passwords by admin reset; existing keys and sessions continue to work.