automc-tutorials/README.md

automc-tutorials

Public-facing tutorials site for the automc Minecraft platform. Renders markdown from a mounted volume as a localized static-ish web app. No auth, no database, no state — exposed to the open internet behind TLS, hardened for zero-trust.

Stack

• Go + net/http + html/template — single binary
• goldmark — markdown → HTML (GFM + footnotes + auto heading IDs)
• Plain CSS — no framework, dark mode via prefers-color-scheme
• Vanilla JS — ~70-line client-side substring search, no dependency
• Content lives on a mounted volume; reload via SIGHUP

Layout

cmd/automc-tutorials/main.go    — entry: flags, signals, SIGHUP reload
internal/content/               — loader + path-traversal guard for content/<locale>/<category>/<slug>.md
internal/render/                — goldmark wrapper (HTML escaping on)
internal/server/                — mux, handlers, embedded templates + /static/ bundle
content/<locale>/<category>/    — markdown source. _index.md is the category landing page (optional).

Adding or editing a tutorial

The image carries only the binary. Markdown sits on a volume mounted at /content (default in the image; override with CONTENT_DIR). Workflow:

1. Open an admin shell on the host that owns the PVC (or shell into a pod that mounts the same RWX volume).

2. Drop / edit .md files under <volume>/<locale>/<category>/.

3. Add YAML frontmatter:

   ---
   title: Page title
   summary: One-sentence preview shown on category list.
   order: 1
   ---
   

4. Write markdown. GFM tables, fenced code, footnotes, autolinks, task lists all work. Raw HTML in markdown is escaped — don't try to embed <script> or <iframe>, they'll render as text.

5. Reload without restart: kill -HUP $(pidof automc-tutorials) inside the container, or kubectl exec deploy/automc-tutorials -- kill -HUP 1.

No rebuild, no rollout. The atomic library swap means in-flight requests keep serving the old library; new requests see the new one.

Localization

Each top-level directory under the content root is a locale. Pages are independent per locale — translations are not auto-mapped. The header has a locale switcher that just changes /<locale>/ in the URL.

If a page exists in en but not cs, switching to cs lands on the cs home (no automatic redirect, no fallback render).

Search

Client-side substring search over title, summary, and body. Index served at GET /search.json?lang=<locale> — flat array of {path, title, summary, body}. static/search.js does a case-insensitive linear scan with crude scoring (title hit = 100, summary = 10, body = 1) and shows the top 8.

This is fine for a few hundred pages. If the corpus ever balloons, swap the in-browser scan for a real indexer — the endpoint contract is stable.

Configuration

Var	Default	Purpose
ADDR	:8080	HTTP listen address
CONTENT_DIR	/content	Path to content root (volume mount in production, ./content in dev)
DEFAULT_LOCALE	en	Locale used when none in URL (/ → /<locale>/)

Zero-trust posture

The service is intended to sit behind TLS (k8s ingress) on the open internet, with no auth and no WAF. Hardening:

• No HTML in markdown. goldmark.WithUnsafe() is not enabled, so raw HTML in .md is escaped.
• CSP restricts everything to 'self'; 'unsafe-inline' is absent (templates carry no inline styles or scripts). Frame ancestors blocked, base/form-action pinned to self.
• HSTS, COOP, CORP, Permissions-Policy all set conservatively.
• No directory listing on /static/; only GET/HEAD; hidden files (/.foo) blocked.
• Content loader rejects symlinks that escape the content root, hidden files, and .md files larger than 1 MiB.
• HTTP timeouts are set on read header, read body, write, and idle.
• Distroless static, runs as 65532:65532, no shell, no package manager.
• No outbound calls — the service never reaches out to anything.

Build

make build      # binary
make dev        # go run, no build artifact
make test       # go test ./...
make docker     # Docker image

Deployment

Single binary, distroless image, port 8080, no persistent state. Deploy as a normal k8s Deployment + Service + Ingress for tutorials.timemachine.center. Mount the content PVC read-only at /content. No DB, no auth, no secrets.

Repo

Standalone Gitea repo at git.timemachine.center/Timemachine/automc-tutorials. Sibling of the automc orchestration repo.