Phase 1: lorehallow.com

You are here. This is the phase being built now. Read the walkthrough for how it was built and what it teaches.

Ships

The lorehallow.com website

Lesson

Linux server hardening, DNS, TLS, reverse proxies, static site generation in Go and automated deploys

Depends on

Phase 0 sections 0.2, 0.3 and 0.9 (the rest of Phase 0 can finish in parallel)

• Owner Fill in deploy/HOST.md (or give an agent the facts to write it): OS and version, CPU architecture, RAM and disk, network setup (public IP, or ports 80 and 443 forwarded if it’s at home), and anything else already running on it.
• Owner Point DNS A records (and AAAA if the host has public IPv6) for lorehallow.com, www.lorehallow.com and play.lorehallow.com at the host, and note the DNS provider in deploy/HOST.md.
• Write deploy/bootstrap/host.sh, an idempotent provisioning script: create the deploy and service users, key-only SSH with root login off, firewall allowing only 22, 80 and 443, automatic security updates, fail2ban or equivalent, Caddy, and the /srv/lorehallow and /etc/lorehallow layout.
• Owner Review and run the bootstrap script with sudo (or let an agent run it), and authorize SSH keys for agent sessions and for CI on the deploy user.
• Decision Reverse proxy: Caddy with automatic HTTPS (recommended). Config in deploy/caddy/lorehallow.caddy (a site file on the shared host, ADR 0009), site root /srv/lorehallow/web/current.
• HTTPS works with valid certificates; HTTP redirects to HTTPS and www redirects to the apex.
• Security headers (HSTS, CSP, X-Content-Type-Options, Referrer-Policy, Permissions-Policy), compression, and long cache lifetimes for fingerprinted assets.
• Every host change documented in deploy/HOST.md.

• Decision Website stack: a Go static site generator in web/ (its own module) with no JavaScript on any page (ADR 0011).
• cmd/lorehallow-web with build (writes the site to web/dist/) and serve (local preview that rebuilds on change, drafts included); templates (html/template), CSS and fonts embedded with go:embed.
• Design tokens generated from art/style/palette.hex into CSS custom properties, so the site and the game share one palette.
• Decision Fonts: an open-licensed pixel font for headings and a readable body font, both self-hosted with license files committed.
• Base layout: header with logo and navigation (Home, World, Progress, Devlog, Downloads, About), footer linking GitHub, Codeberg, RSS and the licenses.
• Pixel image component: integer scaling, image-rendering: pixelated, explicit dimensions, lazy loading below the fold.
• Make targets web-dev, web-build, web-test and web-lint (gofmt, go vet, golangci-lint, govulncheck), with the tests and linters included in make check.

• Hero: key art with gentle CSS-only parallax layers, the wordmark, a one-line pitch and calls to action (Follow the build, Read the devlog, View the source).
• “A world that’s already there”: what Lorehallow is and the feeling it’s going for, in plain language.
• Design pillars with pixel icons.
• “What you’ll do” teaser: explore, quest, group up and fight with other people around you, clearly marked as planned.
• Live progress widget: overall progress as an XP bar, the current phase, and a link to /progress.
• Latest three devlog posts.
• Art showcase strip built from processed art.
• “Built in the open” section linking the GitHub and Codeberg repositories and BUILD.md.
• Ambient touches (drifting fireflies, lantern flicker) in CSS only, switched off under prefers-reduced-motion.
• No JavaScript: the page has no scripts at all, and everything above is plain HTML and CSS.

• BUILD.md parser in web/internal/buildmd/ implementing the format contract: phases, metadata, sections, items, tags and checked state.
• Parser unit tests, including malformed input, and a buildmd-lint command in make check that fails on any format violation.
• Overall progress XP bar and per-phase progress bars, computed from the boxes.
• Quest map: one landmark per phase along a winding road; finished landmarks lit, the current one marked “You are here”, future ones dimmed.
• Hand-draw a 21st landmark for Phase 20 (a far road beyond the castle) to join the 20 from Batch 02.
• Phase pages (/progress/phase-N) with goal, lesson, sections, checklists and HUMAN and ADR badges.
• Achievement feed: at build time, walk the git log of BUILD.md to find when each box was checked, and show the most recent as “quest complete” entries with dates and commit links.
• “Waiting on the owner” panel listing unchecked HUMAN items in the current phase.
• Machine-readable /progress.json and a /progress.svg badge, with the badge added to README.md.
• Each phase links to its walkthrough on GitHub once it exists.

• Devlog posts as Markdown files with front matter in web/content/devlog/, rendered with goldmark and validated at build time (title, date, summary, tags, cover image, draft).
• Posts with draft: true show only in serve and are never written by build.
• Index, tag pages and post pages with pixel-art styling and comfortable reading typography.
• RSS and Atom feeds.
• Move the Phase 0 devlog draft into the collection.
• Owner Edit and publish the first devlog post.

• Platform cards for Windows, macOS and Linux with an honest “Not available yet. Follow the progress.” state.
• Page driven by web/data/releases.json (version, date, channel, platform, URL, size, SHA-256, notes link), with the schema documented for the release automation that writes it later.
• System requirements and “verify your download” sections that appear once releases exist.

• /world: the setting and mood (mossy forests, lantern-lit towns, old stone ruins) with an art gallery, marked as early and subject to change.
• /about: the project’s goals (a small world worth being in, an excellent Go MMO server as the showcase, and learning by building it), building in the open, how it’s made (the owner’s direction, AI agents writing the code and hand-drawing the pixel art, a few large painted images generated and run through the processing pipeline) and the tech stack.
• /faq: is it free, when can I play, which platforms, how many players (the goal of hundreds to thousands, stated as a target, with only measured numbers given as facts), how to follow along.
• Custom 404 page with the hand-drawn 404 art (web/not_found.png: the hero lost at a broken signpost).
• Open Graph and social card meta on every page with generated share images, plus sitemap.xml, robots.txt and canonical URLs.
• No third-party trackers, scripts or fonts on any page.

• Lighthouse audit from Chrome DevTools on the live landing page, /progress and a devlog post: 95 or higher for performance, accessibility, best practices and SEO on mobile, recorded in docs/perf/ (Lighthouse is a Node tool, so it isn’t in CI; ADR 0011).
• Output tests on the built site in make web-test: no <script> tags or inline event handlers on any page, alt text and explicit dimensions on every image, and WCAG AA contrast for every palette pair the CSS uses.
• Accessibility: alt text on all art, full keyboard navigation, visible focus, WCAG AA contrast.
• Responsive from 360 px phones to 4K screens, with art always scaled by whole numbers.
• Internal link checker in make check.
• Landing page transfers under 1 MB, enforced by a test on the built output.

• deploy/web/deploy.sh: build, upload to a new timestamped release directory, switch the current symlink atomically, keep the last five releases.
• make deploy-web and make rollback-web for manual use.
• GitHub Actions workflow that deploys on every push to main touching BUILD.md, web/, art/processed/web/ or docs/walkthroughs/, with full git history checked out for the achievement feed.
• Owner Add the CI deploy key and host details as GitHub Actions secrets.
• Nightly scheduled rebuild so date-based content stays fresh with no pushes.
• Decision Uptime monitoring that alerts the owner (for example ntfy) when the site has been down for five minutes.
• Owner Pick an ntfy topic, subscribe to it on your phone and add it as the NTFY_TOPIC secret (docs/ops/website.md), then send a test alert.

• docs/walkthroughs/phase-01-website.md: DNS, TLS and Caddy, static builds, the deploy pipeline, and how BUILD.md becomes the progress page.
• Devlog draft announcing the website.
• Owner Review the live site on desktop and phone and approve it.

• https://lorehallow.com serves the landing page with a valid certificate, and HTTP and www redirect correctly.
• Checking a box in BUILD.md and pushing to main updates /progress within 10 minutes with no manual steps.
• Every page links to the GitHub and Codeberg repositories.
• The devlog has at least one published post and a valid RSS feed.
• /downloads exists and accurately says no builds are available yet.
• Lighthouse budgets pass and no page ships any JavaScript.
• A deliberately bad deploy was rolled back with one command.