# Ops & Deploy Runbook — blog.hoelee.com

How this blog is built, deployed, and kept alive. Read when debugging CI/CD, deployment, or hosting.

---

## Pipeline

```
Markdown (src/content/posts) → Astro build (dist/) → Gitea Actions → act_runner on unRaid
  → nginx container → Cloudflare tunnel → Cloudflare CDN → blog.hoelee.com
```

- **Repo:** `git.hoelee.com/hoelee/hoelee-blog` (push here first, then GitHub — standing convention).
- **Runner:** `act_runner` on unRaid (verified working: Gitea 1.27.3 + runner 3.3.2, PAT-secret pipeline).

---

## Write & publish a post

1. Create `src/content/posts/<slug>.md` with frontmatter (see `content-guide.md` §6).
2. Push to `main`.
3. CI builds `dist/` and deploys to the nginx container automatically.
   - **Before pushing a post that adds art**, generate its in-page derivatives:
     `uv run --with pillow python scripts/optimize-images.py <slug>`
     (banner `.webp` + `/og/thumb/<name>-{400,800}.webp`). The PNGs from
     `banner-gen` / `og-gen` remain the `og:image` source of truth — see
     `design-guide.md` §3 for the format policy and measured sizes.
4. Verify live: `curl -I https://blog.hoelee.com/<slug>` → expect 200.

---

## Build pitfalls (from prior Astro work — check these first)

- **Pagefind is an ES module and exposes no window global.** `dist/pagefind/pagefind.js`
  ends with `export { search, debouncedSearch, … }`. Load it with a dynamic `import()`, never
  a classic `<script src>` + `window.Pagefind` — that combination silently made every search
  answer "Search is unavailable." for as long as the overlay existed. The specifier must be a
  **variable** (`const url = '/pagefind/pagefind.js'; await import(/* @vite-ignore */ url)`)
  because Rollup resolves a literal dynamic-import path at build time and fails on a file that
  does not exist until after the search index is generated.

- **No JSX helper components in frontmatter** — inline JSX directly in `.map()` calls, or the build fails with `Expected ">" but found "class"`.
- **Import depth** — `src/pages/*.astro` use `../layouts/…`; subdirs use `../../`. Wrong level = `Could not resolve`.
- **Footer must render AFTER `<main>`** — a shared header+footer component renders footer above content otherwise.
- **`npm install` scripts blocked** can leave esbuild's binary missing → check `npm warn install-scripts` at install time.

---

## Verify before shipping a layout change

Headless-Chrome screenshot + vision check on **both** 390px and 1280px:

```bash
CHROME="/c/Program Files/Google/Chrome/Application/chrome.exe"
"$CHROME" --headless --disable-gpu --window-size=1280,2400 \
  --screenshot="$(cygpath -w $LOCALAPPDATA/Temp/blog.png)" \
  --virtual-time-budget=4000 "http://localhost:4321/"
```

Overflow diagnosis (real numbers, not screenshot guessing): check `scrollWidth > innerWidth` via CDP `Runtime.evaluate`.

---

## nginx layer (unRaid container, Portainer stack 247)

The container `nginx-hoelee-blog` (`nginx:1.29-alpine`, host port 8081) had a **stock
`default.conf`** until 2026-10-16, when the config became a bind mount:

- `/mnt/user/docker/nginx-hoelee-blog/conf.d/default.conf` → `/etc/nginx/conf.d/default.conf:ro`
- Edits take effect after `docker exec nginx-hoelee-blog nginx -t && docker exec nginx-hoelee-blog nginx -s reload`
  (no restart needed). Validate a candidate file first in a throwaway container:
  `docker run --rm -v /mnt/user/docker/nginx-hoelee-blog/conf.d/default.conf:/etc/nginx/conf.d/default.conf:ro nginx:1.29-alpine nginx -t`
- Stack: Portainer **DSM instance** (endpoint 3 = unRaid), stack id **247**. Read/update via
  `GET|PUT /api/stacks/247?endpointId=3`; PUT recreates the service (a few seconds of downtime).

What the conf adds, and why:

| Rule | Why |
|---|---|
| `location = /posts/zh/ { return 301 /zh/posts/; }` | Chinese posts live at `/posts/zh/<slug>/`, so the bare directory had no index and answered **403**. The Chinese archive is `/zh/posts/`. |
| `error_page 404 /404.html;` + internal location | Astro builds `dist/404.html`. Without it, a broken link showed nginx's default page. Served with a 404 status so crawlers do not index it. |
| `location /_astro/` → `max-age=31536000, immutable` | Astro hashes these filenames, so they can never go stale. `/og/*.png` and `/banners/*.png` are **not** hashed and are regenerated in place, so they deliberately keep Cloudflare's default TTL. |
| HTML → `max-age=0, must-revalidate` | A deploy must be visible immediately; edge caching is controlled separately by the Cloudflare Cache Rule + the deploy purge step. |

Header note: the public `Strict-Transport-Security` and the default 16-day asset
`Cache-Control` come from **Cloudflare zone settings**, not from this nginx (the origin
sends no such headers). See `docs/project-state.md` §1 B2 for the open CF items.

## Hosting notes

- Static output = trivial to serve from any nginx/OpenLiteSpeed dir. Cloudflare in front gives CDN + HTTPS + DDoS.
- Cloudflare Pages **git integration supports GitHub/GitLab only — not Gitea**. Current setup (Gitea → self-hosted runner → nginx) sidesteps this entirely and is the reason the pipeline is the way it is.
- Full self-hosting also avoids Cloudflare Pages' 25MB/file, 20k-files limits — a decision already baked into this architecture.

---

## Health checks

- `curl -I https://blog.hoelee.com/` → 200, correct `content-type`.
- `curl https://blog.hoelee.com/sitemap.xml` → lists all published posts.
- `curl https://blog.hoelee.com/rss.xml` → non-empty.
- DNS: `blog.hoelee.com` resolves through Cloudflare (proxy enabled).

## Pitfall: premature poll caches a 16-day 404

The origin serves `Cache-Control: max-age=1382400` (16 days), and Cloudflare caches
negative (404) responses too. If you curl a freshly-deployed URL **before the CI deploy
finishes**, Cloudflare caches that 404 for 16 days — the page itself returns 200 but its
`og`/`banner` PNGs 404 with `cf-cache-status: HIT`.

- **Detect:** the bare URL 404s but `?v=<timestamp>` (cache-buster) returns 200 → origin is
  fine, edge cache is stale.
- **Fix:** purge the Cloudflare zone cache. Zone-level token (`Zone.Cache Purge` perm, lives
  in the cloudflare-pages-deploy skill) → `POST /zones/8c8b2359766ac853602b91dd851c630e/purge_cache`
  with `{"purge_everything":true}`. See that skill for the exact curl.
- **Prevent:** after `git push`, `sleep` ~60–90s before the first bare-URL check, or validate
  with `?cb=$(date +%s)` first so you never register a 404 into edge cache.