GIRLSERVE(1)

💅 GIRLSERVE(1) — girlpages Manual 💅

okay bestie, so girlserve is literally the moment. it's from the girlpages manual and it's here to serve a published girlpages site, no cap ✨

---

🌸 NAME 🌸

girlserve — serve a published girlpages site 🫶

---

✨ SYNOPSIS ✨

girlserve [options] --archive dir
girlserve [options] --dir site

---

💖 DESCRIPTION 💖

girlserve serves a girlpages site (its website and its repository) exactly how girlrepo publish made it: from an archive, the way girlrepo publish --archive writes it, or from a site directory. it's basically girlrepo serve on its own, but for production — a tiny static program with nothing else in it, because minimal container images are the vibe. 🎀

every file gets sent in the smallest form the client will accept (zstd, brotli, gzip, or just as it is, depending on its Accept-Encoding), with the Cache-Control that matches its kind (immutable for files named after their hash, five minutes for the files that point to them, an hour for the website, and no-cache for its service worker). you also get a strong ETag (from an archive — a directory's files get Last-Modified instead), range requests, and the site's own 404 page. slay. 👑

an archive gets checked for a new version every --reload-interval and on SIGHUP; a new one loads alongside whatever's being served and switches over at once, so no request ever sees half of each. if it can't be loaded, what was already being served keeps being served, and it gets tried again next time. and until the archive has a version (before its first publish), every request gets 503 and /readyz fails. 💀

on SIGTERM or SIGINT, /readyz fails immediately, the site keeps being served for --drain-delay more (so load balancers notice first 🫶), and then requests in flight get --drain to finish.

---

🌈 OPTIONS 🌈

• --archive=dir — serve the archive in dir (or $GIRLSERVE_ARCHIVE). it's totally fine if it's on a network file system: only a few files get opened, and each request is a read of the bytes it sends. 🦋
• --dir=site — serve a site directory instead.
• --listen=addr — serve the site on addr (default :8080, or $GIRLSERVE_LISTEN).
• --admin-listen=addr — serve /healthz (the process is up), /readyz (it has a site to serve, and isn't stopping) and /metrics (Prometheus) on addr (default :9090, or $GIRLSERVE_ADMIN_LISTEN; empty for none).

⚠️ bestie this one shouldn't be public. keep it close. 🙈

• --reload-interval=duration — how often to check the archive for a new version (default 10s; 0 for only on SIGHUP).
• --access-log — write a line of JSON for each request to standard output: its time, method, path, status, size, duration, encoding, address, referrer and user agent, and behind a proxy, its X-Forwarded-For header as it came (forwarded_for: the client's address and any proxies' before this one's, as they say; it's for reading, not trusting 👀).
• --drain-delay=duration — when stopping, keep serving this long first, with /readyz failing (default 5s).
• --drain=duration — then give requests in flight this long to finish (default 30s). packs are hundreds of megabytes, so otherwise there's no limit on how long a response may take. 😭
• --version — print the version. periodt.

---

🎀 METRICS 🎀

• girlpages_http_requests_total{code} — requests, by status.
• girlpages_http_request_duration_seconds — how long they took (a histogram).
• girlpages_http_response_bytes_total — bytes of response bodies.
• girlpages_archive_generated_time_seconds, girlpages_archive_loaded_time_seconds — when the version being served was written, and loaded: alert on either getting old. ⏰
• girlpages_archive_reloads_total, girlpages_archive_reload_failures_total — reloads that changed what's served, and those that failed.
• girlpages_archive_files, girlpages_archive_live_bytes — the size of the version being served.

---

💜 EXAMPLES 💜

girlserve --archive /data/archive --access-log

serve the archive the publishing job writes to, on :8080, with health and metrics on :9090. iconic. ✨

also, dist/hosting/kubernetes.yaml in the source has a CronJob that unpacks packs dropped into a directory, publishes them into an archive, and a Deployment of girlserve serving it. the whole pipeline ate, fr fr. 🔥

---

👑 SEE ALSO 👑

girlrepo(1), girl(1), girlc(1)

---

🌸 AUTHOR 🌸

Naomi Persephone Amethyst <naomi@amethyst.name> 💖

---

okay that's the whole page bestie, go forth and serve 🫶 this was girlpages, dated 2026-10-21, and no cap you're gonna crush it 💅✨