Simple HostOpen source / Delivery architecture

From code change
to running server.

Two triggers. Three artifacts. A server in the organiser’s own cloud account.

01 /

Two triggers, two jobs

GITHUB ACTIONS · GITHUB’S MACHINES git pushAny branch make checkgofmt · vet · tests · architecture-layering gatedocs-sync gate · fresh-schema install Pass / FailPass only git tag v1.2.0A human decides whenBuild & publishRelease GITHUB ACTIONS · GITHUB’S MACHINESgit pushAny branchmake checkgofmt · vet · testsarchitecture-layering gate · docs-sync gatefresh-schema installPass / Failgit tag v1.2.0A human decides whenPass onlyBuild & publishRelease

Free runners for public repositories. Checks and builds run on GitHub’s machines, never on our own server.

02 /

One tag, three artifacts

v1.2.0One build · ~1 minute ONE GITHUB RELEASE · TWO ATTACHED BINARIESsimple-host_linux_amd64UpCloud · DigitalOcean · Hostingersimple-host_linux_arm64Oracle’s free tier ghcr.io/vineetu/simple-host:1.2.0Copies the already-built binary · no compilation32 MBAMD64 + ARM64 v1.2.0One build · ~1 minute ONE GITHUB RELEASEsimple-host_linux_amd64UpCloud · DigitalOcean · Hostingersimple-host_linux_arm64Oracle’s free tier ghcr.io/vineetu/simple-host:1.2.032 MB · AMD64 + ARM64Copies built binary · no compilation

No cgo, no emulation. Both architectures cross-compile on one runner.

03 /

From tag to their server

OrganiserNon-technicalCopy onecloud API token THEIR OWN MACHINEAI coding agentRuns setup skillThe agent opens the terminal.Creates NEW SERVER · THEIR CLOUD ACCOUNTDocker ComposeCaddyObtains certificates automaticallySimple HostPulled from the registry · :1.2.0PostgresApplies the schema on first boot Non-technical organiserCopies one cloud API tokenTHEIR OWN MACHINEAI coding agentRuns setup skillThe agent opens the terminal.Creates a new serverSERVER · THEIR CLOUD ACCOUNTDocker ComposeCaddyObtains certificates automaticallySimple HostPulled from the registry · :1.2.0PostgresApplies the schema on first boot

One manual step: copy the provider’s API token. The organiser never opens a terminal.

Teardown uses the same skill and deletes the server.

04 /

What is inside the box

DOCKER COMPOSE · THREE SERVICESFOUR DOCKER NAMED VOLUMEScaddycaddy:2-alpine · publishes 80 + 443Terminates TLS; obtains & renews certsServes participant files from diskOnly /v1/* and /internal/* → appsimple-hostProject’s own image · internal :8090Dashboard · sign-in · deploy APIWrites site files; never serves themNot in the content pathpostgrespostgres:16-alpine · internal :5432Accounts · metadata · per-site JSON stateApp waits for a passing health checkRead-only schema; auto-applied first boot onlyAPI paths only → :8090Healthy → app startssites · /data/sitesEvery deployed filesimple-host: READ-WRITEcaddy: READ-ONLY → serves files directlyDelete → lose every deployed filedb/var/lib/postgresql/dataEvery account & all site metadatapostgres: READ-WRITEDelete → lose the instancecaddy_data · /dataTLS certificates & ACME accountcaddy: READ-WRITEDelete → re-issue certificates; may hitLet’s Encrypt rate limitscaddy_config · /configCaddy’s autosaved configcaddy: READ-WRITEDelete → harmlessREAD ONLYWRITEHost Caddyfile → caddy: READ-ONLYMounted from the host; not baked into the image.DOCKER COMPOSE · THREE SERVICEScaddycaddy:2-alpine · publishes 80 + 443Terminates TLS; obtains & renews certsServes participant files from diskOnly /v1/* and /internal/* → appsimple-hostProject’s own image · internal :8090Dashboard · sign-in · deploy APIWrites site files; never serves themNot in the content pathpostgrespostgres:16-alpine · internal :5432Accounts · metadata · per-site JSON stateApp waits for a passing health checkRead-only schema; auto-applied first boot onlyAPI paths only → :8090Healthy → app startsHost Caddyfile → caddy: READ-ONLYMounted from host; not baked into image.FOUR DOCKER NAMED VOLUMESsites · /data/sitesEvery deployed filesimple-host: READ-WRITEcaddy: READ-ONLY → serves files directlyDelete → lose every deployed filedb/var/lib/postgresql/dataEvery account & all site metadatapostgres: READ-WRITEDelete → lose the instancecaddy_data · /dataTLS certificates & ACME accountcaddy: READ-WRITEDelete → re-issue certificates; may hitLet’s Encrypt rate limitscaddy_config · /configCaddy’s autosaved configcaddy: READ-WRITEDelete → harmless

One shared mount keeps the app out of the content path. Simple Host writes sites; Caddy reads it directly.

Internal ports stay internal. Only Caddy publishes ports; 8090 and 5432 are never published. These are Docker named volumes; the Kubernetes equivalent is a persistent volume claim.

05 /

Two domains, on purpose

TWO HOSTNAMES · TWO BROWSER ORIGINShack.example.comDashboard · sign-in · APIOrganiser & participants log in heresites.hack.example.comEvery participant’s contentServed by path: /handle/project/ADMIN INTERFACEPARTICIPANT CONTENTOn one origin, participant code could script a viewer’s dashboard.Two origins prevent that in the browser, rather than by policy.DNS A recordDNS A recordSame server · CaddyBoth names point to the serverPort 80 must be reachable from the internetCaddy automatically obtains a certificate for each nameTWO HOSTNAMES · TWO ORIGINShack.example.comDashboard · sign-in · APIOrganiser & participants log in hereSEPARATE BROWSER ORIGINSsites.hack.example.comEvery participant’s contentServed by path: /handle/project/On one origin, participant code could scriptthe dashboard of anyone viewing it.Two origins prevent that in the browser,rather than by policy.Both names: DNS A record → serverSame server · CaddyPort 80 reachable from the internetCaddy automatically obtainsa certificate for each hostname

No domain? An organiser could be given a subdomain of a domain the project controls.