Every place
a feature lives.

A response-shape change ripples further than the handler. There is no compile-time link between a Go struct and the JavaScript that reads it, so a renamed field fails by rendering zero, not by throwing. Before changing a shape, read §02 and open every consumer listed. The analytics split is the worked example: two pages, one updated, one silently blank.

The two *_daily analytics tables must never be dropped. Nothing writes to them any more, which makes them look like debris. They are the only surviving record of 2026-07-11 → 2026-08-08 — the raw logs behind that month have rotated away and no rebuild can recover it. The API reads them for every day before classified_from and reports them as unknown. Dropping them silently deletes twenty-nine sites' first month, seventeen of which have no other history at all.

The ingester's inode-and-offset tracking constrains the logrotate config. copytruncate keeps the inode and loses whatever was written between copy and truncate; the ingester needs the inode change to know it should drain the old file. It also cannot read gzip, so delaycompress is what gives it a full cycle to finish .log.1. Those two directives are code dependencies wearing a config's clothes.

Some features are half in nginx. The branded 404, the analytics log and the live-captions WebSocket are each part Go and part edge config. Shipping the Go half and calling it done produces a feature that works on your laptop and not in production. A new custom-domain vhost that omits the shanalytics access-log line yields a site whose analytics are permanently empty, with nothing anywhere reporting a problem.

A migration is not done until the grants are. Migrations once shipped without GRANTs for the service role, so the tables existed and the feature 500ed while everything around it looked healthy. A migration that creates a table must also grant it to the application role, and grants must be verified against the live database after any migration — not just the SQL file.

Static pages are embedded in the binary. Editing anything under internal/handler/static/ changes nothing until the binary is rebuilt and the service restarted. "Deployed" and "visible" are different claims — verify from the client, never from the file you just saved.

Two different builders are both called "Create a site". One calls the model server-side; the other asks you to paste JSON from your own AI. They live on different pages and share no endpoint. Any instruction about "the AI builder" that does not name the page is ambiguous.

The docs-sync script catches less than it appears to. scripts/check-docs-sync.sh hard-fails when a registered /v1 route is missing from openapi.yaml or vice versa, and when an owner route is not auth-wrapped. Both are valuable. But it compares paths, not methods, so adding a verb to a documented path is invisible; it never checks whether prose descriptions still match behaviour; and it has no capability rule for analytics, custom domains, AI create or transcription. It would not have caught anything on this page.

No execution path exists. The server has no interpreter, no SSR runtime, no plugin loader, no per-site processes. Uploaded files are written to disk and later returned as bytes with a content type — a hostile upload has no more power than an email attachment sitting in a folder.

Archives are validated in memory, before anything touches disk. Extraction produces a map of paths to bytes; every guard runs on that map, and only then is a version written. Path traversal is blocked twice over — at extract and again at write — along with absolute paths, control characters, depth over 32 and paths over 1024 bytes. Symlink, hardlink and device entries are dropped rather than followed. Caps: 100 MB per file, 500 MB uncompressed total, 50,000 entries, and a 100 MB request body (MAX_ARCHIVE_MB). Zip bombs are handled by counting bytes actually read, never the declared size in the header.

The extension check is a denylist, and it is a courtesy — not the safety control. Being honest about this matters: only source-script types are hard-rejected (.sh .bash .zsh .fish .bat .cmd .ps1 .py .pyc .rb .pl .go .php). Everything else is accepted, binaries included. Secret-shaped files (.env, .htpasswd, .npmrc, .netrc, id_rsa, anything under .git/ or .ssh/) are silently skipped, not rejected — the deploy still succeeds, minus the secret. The real guarantee is 4.1: nothing on disk can run.

Serving is rooted per site, by nginx, off disk. Static bytes never pass through the Go process. nginx maps /<handle>/<site>/… straight to that site's current/ directory, with the handle and site captured by regexes limited to [a-z0-9-] — traversal is not expressible in them. Directory listings are off (nginx defaults to autoindex off, and nothing turns it on); a directory with no index serves nothing. The Go path checks are real but they are write-time controls: they decide where bytes land, not what gets served.

Versions are per-upload, owned, timestamped and revertible — but "atomic symlink" would be a lie. Each upload writes a new vN/ and a versions row carrying the owner, a timestamp and a SHA-256 of the content. Going live copies that tree to current/ via remove-then-rename: current is a real directory, not a symlink, and there is a brief window during the swap where it is absent. Rollback re-points it the same way. Small, real, and worth knowing before you promise zero-downtime deploys.

Per-site JSON state. One shared document per site (GET/PUT/PATCH /v1/sites/{site}/state, mirrored at /v1/u/{handle}/sites/{site}/state), with atomic ops — set, inc, append, remove, remove-where — applied under a row lock, and ETag / If-Match for cheap polling and optimistic concurrency. Counters, votes, saved app state, guestbooks.

Append-only collections. Growing lists (/collections/{name}) for signups, RSVPs and form submissions — cheap appends, paginated reads, and an owner-only CSV export.

Visitor sign-in on your own domain. A hosted auth.js helper gives a page Google or emailed-code sign-in, so visitors can write to 6.1 and 6.2. It works only on a site's own custom domain: on the shared host every site shares one origin, so no visitor sign-in is issued there — pages there save without one (anyone can change that data), and agents write with an API key anywhere.

Server-side visitor analytics. Per-site views and unique visitors, split into people, bots and monitoring, with an hourly and a daily trend — computed from the edge access log, so no tracking script and nothing to embed. IPs are salted-hashed and never stored raw. Section 07 is the whole pipeline.

nginx writes the ledger. Static pages are served straight off disk and the Go process never sees a page view, so the edge log is the only ground truth. A dedicated log_format shanalytics emits tab-separated ts · host · status · method · uri · remote_addr · user_agent into /var/log/simple-host/analytics.log. The directive is per vhost: a custom-domain server block added without that one line produces a site that silently records nothing.

A Go ingester tails it every 5 minutes. It resumes from a persisted (inode, byte offset), and that offset advances in the same transaction as the counter upserts — so a crash re-reads a batch instead of double-counting one. Each line is attributed to a site by host: content-host path, legacy label, or bound custom domain. Unattributable lines are skipped, never guessed. A run is capped at 200,000 lines and recovers from its own panics, so it can never take the server down.

Rotation is part of the design, not an afterthought. logrotate uses create plus delaycompress, and both are load-bearing. copytruncate would keep the inode and break offset tracking; and because the ingester drains the previous file as plain .log.1 and cannot read gzip, compression must be held back a full cycle. Change the logrotate stanza and you are changing the ingester's contract.

Three classes, and loopback always wins. Every request is labelled person (no automation signature), bot (crawlers, AI scrapers, SEO suites, security scanners, HTTP libraries — plus exploit paths like /wp-login.php regardless of what the User-Agent claims), or infra (loopback probes and hosted uptime checkers). A loopback address is infra whatever it calls itself. person is the default, deliberately: an unrecognised crawler inflates the human number rather than hiding real people, which is the safer direction to be wrong in.

Hourly buckets, split by class. site_view_hourly(site_id, hour, class, views) and site_visitor_hourly(site_id, hour, class, ip_hash) replaced the old date-grained tables. Hourly granularity is what makes "the last 24 hours" answerable at all, and the volume is trivial — a dozen sites × 24 hours × 3 classes is under 900 rows a day, so nothing is rolled up. Aggregates prune at 400 days.

Visitors are a salted hash, and the salt does not rotate. An IP is stored only as sha256(server-secret salt + ip) truncated to 16 bytes; the raw address is never written and the secret never leaves the box. The salt is stable on purpose. A per-day salt makes a returning visitor unlinkable across days, which makes "unique visitors over 30 days" impossible to compute — you are left summing daily uniques, which always overstates the audience. Stable salt is what makes a range total a real number instead of an inflated one.

The first month is kept, and honestly labelled. The pre-classifier *_daily tables are retained rather than dropped: they are the only surviving record of 2026-07-11 → 2026-08-08, whose raw logs have rotated away and cannot be rebuilt. The API reads them for any day before classified_from and reports them as a fourth class, unknown — plainly visible on the chart, never quietly folded into the human number.

One process behind nginx. A single Go binary under systemd, listening on loopback only — deliberately not a cluster. nginx terminates TLS, serves the content host by path straight off disk, proxies /v1/ and /internal/ to the app, and fronts every connected custom domain. There is no Caddy in this deployment; the on-demand-TLS endpoint in the code is a leftover from a design that was not adopted.

Certificates are certbot, and issuing one is a human step. Let's Encrypt certs per domain, renewed by a timer twice daily. Connecting a custom domain through the API only records the binding and creates the symlink, then hands back the DNS record to add — an operator still writes the vhost and issues the cert before that domain serves anything. Any copy promising instant custom-domain HTTPS is describing a system this is not.

Hardened & non-root. Runs as a dedicated simplehost user with NoNewPrivileges, ProtectSystem=strict, ProtectHome, PrivateTmp, MemoryDenyWriteExecute, an empty capability bounding set, a syscall filter, and exactly one writable path — the sites directory. /healthz and /readyz (the latter pings the database) are real endpoints, but nothing is in front of them: on a single box they are observability, not a traffic gate.

The service is small; the box is not exclusively its own. The process is one static binary doing static serving and pass-through proxying, with no heavy compute in-process. It shares the host with Postgres, the local speech-to-text service, the model proxy, the directory prober and several unrelated services — which is exactly why the analytics classifier had to learn to tell that neighbourhood apart from real readers.

Releases are hand-swapped, and honestly so. Build, copy the binary in, restart; site data and versioned files are untouched. Timestamped simple-host.bak-* copies accumulate next to the live binary for rollback. There is no deploy script in the repo — the procedure lives in habit and prose, which is worth knowing before anyone describes it as automated.

Local state, and the background loops. Postgres on the same box, loopback-bound (users, sites, versions, per-site state, collections, analytics); the versioned site tree on local disk; no external object store. Inside the process: the analytics ingester every 5 minutes; the API-metrics flush every 20 seconds and its prune every 6 hours; the geo worker; domain re-verification every 2 minutes (releasing unproven bindings after 24 hours); the visitor-auth sweep hourly; and the preview-expiry sweep hourly when enabled. Each recovers from its own panics — none can take the server down.