Marcos Paulo
48c31dc1b3
Ten git worktrees each carried their own 225 MB node_modules (1.1 GB across five) and paid 11s per `npm ci`. pnpm hardlinks from a shared store: the same five worktrees cost ~250 MB total, and a fresh install is 4s. What changed beyond the mechanical rename: - `overrides` moved to `pnpm-workspace.yaml`. pnpm 11 does not read the `pnpm` field in package.json *or* npm's top-level `overrides`, and it fails silently — the vite/defu/language-server pins would have quietly stopped applying. - Build scripts are blocked by default in pnpm; esbuild and sharp are allowed explicitly via `allowBuilds` (renamed from `onlyBuiltDependencies` in 11). - `packageManager` + `engines` pin the toolchain. - gate.sh rejects a package-lock.json/yarn.lock/bun.lock outright, so an agent running `npm install` out of habit fails loudly instead of building a second, divergent dependency tree. - CI bootstraps pnpm with `npm install --global pnpm@11.25.0` rather than corepack (unbundled as of Node 25) or pnpm/action-setup (this self-hosted act-runner has never run a job; fetching a third-party action is not something to discover on the first one). Two pre-existing CI bugs fixed while in the file: - the gate installed with `npm install --package-lock=false`, which discarded the lockfile the previous session had just fixed. - the visual-regression step imported `playwright`, which is not a dependency, and `visual-regression.mjs` has no compare mode anyway — in CI it overwrote its own baselines and passed unconditionally. Removed with a comment; it comes back when it can diff. The `publish` job is now manual (`workflow_dispatch`). During the migration dist/ holds three HTML files against the live pages branch's ten, so publishing on every push to main would take the site down to a stub. Restore at task 20. HANDOVER.md's incident log still says npm where it describes what happened at the time; that is history, not a missed rename. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
56 lines
3.6 KiB
Markdown
56 lines
3.6 KiB
Markdown
# Context: publishing, and what a build step changes
|
|
|
|
## How it works today
|
|
|
|
The Gitea Pages Server serves the **`pages` branch tree directly**. There is no
|
|
build. `main` and `pages` end up with byte-identical trees; `pages` exists only
|
|
because the Pages Server publishes a branch, not a directory.
|
|
|
|
Live at `https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/`.
|
|
|
|
Full procedure, including the fact that `merge --ff-only main` fails (the
|
|
histories diverged), is in
|
|
[`../../docs/operations-guide.md`](../../docs/operations-guide.md).
|
|
|
|
## What Astro changes
|
|
|
|
Astro emits `dist/`. The Pages Server cannot run a build, so **something has to
|
|
put built output on `pages`**. Pick one, deliberately, in task 01:
|
|
|
|
| Option | How | Cost |
|
|
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| **A. Build locally, commit `dist/` to `pages`** | `pnpm run build`, copy `dist/*` into the `pages` worktree, commit | `pages` stops being "the exact source". Diffs become unreadable. Publishing depends on one workstation. Simple, no new infra. |
|
|
| **B. Gitea Actions builds and pushes `pages`** | workflow on `main` → `pnpm install --frozen-lockfile && pnpm run build` → force-push `dist/` to `pages` | `pages` becomes a machine-owned branch (force-push is fine _because_ nothing else writes it). Needs the act-runner to be healthy. **Recommended.** |
|
|
| **C. Serve from a container instead** | drop Pages Server for an nginx pod behind the existing ingress | most control, most infra, changes the URL story |
|
|
|
|
**Recommended: B**, with A as the documented manual fallback for when the runner
|
|
is down. Note the known failure mode: this Gitea's act-runner registration lives
|
|
in an `emptyDir`, so a pod restart silently kills CI until re-registered. The
|
|
runbook must say "if the site stopped updating, check the runner first".
|
|
|
|
Whichever you pick, `docs/operations-guide.md` must be rewritten in the same
|
|
task — it currently promises `pages` is "the exact published source", and that
|
|
stops being true under A and B.
|
|
|
|
## Base path
|
|
|
|
The site is served from a **subdirectory**: `/ai-for-dummies/`. Astro needs
|
|
`base: '/ai-for-dummies'` in `astro.config.mjs`, and every internal link must go
|
|
through `import.meta.env.BASE_URL` or Astro's `<a href={...}>` helpers rather
|
|
than a hand-written absolute `/models/`.
|
|
|
|
This is the single most likely source of "works locally, 404s in production" in
|
|
this migration. Verify it on the real host, not just `pnpm run preview`.
|
|
|
|
## Verification before you call it published
|
|
|
|
```bash
|
|
curl -sS -o /dev/null -w '%{http_code}\n' \
|
|
"https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/?v=$(git rev-parse --short HEAD)"
|
|
```
|
|
|
|
The `?v=` cache-buster matters: the Pages Server caches, and a stale 200 looks
|
|
exactly like a successful deploy. Check one nested route
|
|
(`/ai-for-dummies/skills-review/`) and one static asset too — the base-path bug
|
|
shows up on assets first.
|