bcs-website/docs/launch-checklist.md

Launch Checklist — DNS Cutover to the Astro Rebuild

Single source of truth for everything standing between today and pointing bluecapstrategies.com at the homelab k3s deployment.

Verified against the working tree, the cluster, and ArgoCD on 2026-09-18. Supersedes the task lists that were scattered across planning/parity-checklist.md (git-ignored, content-only) and docs/seo-aeo-optimization.md §2/§7 (SEO-only, stale) — those now point here.

Status legend: [ ] open · [x] done · [?] needs verification · 🛑 owner decision

---

0. As-built state (2026-09-18)

Thing	State
ArgoCD app bcs-website	Synced / Healthy
Pods	2/2 Running, ns bluecap-strategies
Deployed image	git.7tl-homelab.com/bmr_bluecap/bcs-website:fc64909f3df1 (built 2026-07-20)
k8s/kustomization.yaml newTag	fc64909f3df1 — same, so ArgoCD is correct; CI never bumped it
HEAD	9f1cbca (2026-08-03), pushed to origin/main, never deployed
Ingress	bluecap-website (traefik), hosts apex + www, port 80 only, no TLS
npm run build	green, 21 pages, 0 errors / 0 warnings
npm run typecheck	green, 28 files, 0/0/0
npm run seo:lint	green, 21 pages clean
npm run test:e2e	42 passed / 4 failed (stale assertions, see §2.1)
CI root cause	found + fixed in-repo 2026-09-22 — see §1.2; needs a green run to confirm
Old WordPress site	untouched and serving — must stay that way until cutover
Gitea host	KVM VM gitea-1 (10.66.15.22), Debian 12, docker compose — not in k3s
Gitea / act_runner	1.27.3 / 3.4.2 — both healthy
CI job image	node:22-bookworm (Debian 12) as of 2026-09-22 — was EOL bullseye; see §1.2

The headline: the public-facing deployment is ~7 weeks behind main. The Aug 3 exact-copy work is not live.

---

1. Cutover blockers

Nothing below is optional. Cutover is unsafe until all of §1 is closed.

1.1 TLS is not configured 🛑 hard blocker

• Uncomment the tls: block and cert-manager.io/cluster-issuer annotation in k8s/ingress.yaml; set secretName: bluecap-website-tls.
• Use the existing letsencrypt-prod ClusterIssuer (present in-cluster, 472d old, Ready).
• Resolve the ordering problem: HTTP-01 validation requires DNS to already point at the cluster, but we don't want to move DNS before a cert exists. Pick one: - DNS-01 issuer (preferred — issues the cert before cutover, zero insecure window), or - accept a short window: cut DNS, then let HTTP-01 solve, serving plain HTTP for ~1–2 min.
• Verify https:// serves a valid chain and HTTP→HTTPS redirects before announcing.

1.2 CI/CD is stalled — no deploy since 2026-07-20 🛑 hard blocker

ROOT CAUSE FOUND AND FIXED IN-REPO 2026-09-22. Not a runner problem — the runner was online and the run did execute.

Evidence (Gitea 1.27.3 on gitea-1, sqlite action_run for repo_id 3):

• Run #6, commit 9f1cbca1b148, created 2026-08-03 13:46:53, status 2 = failure, ran 13m (13:47:02 → 14:00:11) on runner 59.
• No 9f1cbca1b148 entry in package_version → it died at or before the image push.
• Job logs are past retention (/data/gitea/actions_log no longer holds run 205), so the cause was reproduced directly instead.

The cause: the Ensure docker + kustomize are available step ran apt-get install -y docker.io. The job container image is node:18-bullseye (Debian 11), and bullseye went EOL — debian-security no longer serves those package versions. apt-get update still succeeds, so this fails only at install time, with 404s on docker.io, containerd, systemd, libcap2. Reproduced verbatim in a node:18-bullseye container on the runner host. That timing matches exactly: last green run 2026-07-20, first failure 2026-08-03.

The fix (applied to .gitea/workflows/ci.yml): fetch the docker CLI and kustomize as pinned static binaries (download.docker.com / GitHub releases) instead of distro packages. Verified in the real job environment: the static client installs, reports server=28.1.1 through the mounted socket, and docker ps succeeds. kustomize tarball and git are fine.

Everything else on the runner path checked out and needs no change:

• act_runner container up, v3.4.2, registered and polling (the daily 07:30 "connection refused" entries are the Gitea restart window, harmless).
• Runner scope already fixed — runner id 59 is owner_id=0, repo_id=0 (instance-scoped), so the old user-scoped problem is resolved. 58 stale duplicate runner rows remain; cosmetic, prune with the role's gitea_runner_prune tag when convenient.
• Runner host dockerd trusts 10.66.15.22:3000 as insecure — confirmed in docker info.
• config.yaml pins jobs to gitea_network and passes the docker socket — correct.
• CI_TOKEN repo secret present (repo_id 3).
• paths-ignore did not swallow the push — the commit touched src/**.
• docker build of the current tree succeeds locally, so the Dockerfile and lockfile are fine.

Remaining:

• Re-trigger CI and confirm a green run — the fix is verified at the step level but the full pipeline has not run end-to-end since July. Requires a push touching a non-ignored path.
• Confirm the tag-bump commit lands and ArgoCD syncs the new image.
• Do not cut DNS onto a stale image — confirm the deployed tag matches HEAD.
• CI job image upgraded 2026-09-22. gitea_runner_labels in ~/Homelab/ansible/roles/gitea/defaults/main.yml changed node:18-bullseye → node:22-bookworm; playbook run succeeded (ok=40 changed=8 failed=0). Runner 60 registered and online, owner_id=0 (instance-scoped), label confirmed in /data/.runner. The job image now matches the host VM and k3s nodes (Debian 12) and the Node 22 that workflows install anyway. - Gotcha for next time: --tags gitea_runner_prune restricts the run to only that tag, so it cannot be combined with -e gitea_runner_force_reregister=true. Two separate runs. - Gotcha 2: gitea_admin had must_change_password=1 (set during the 1.27.3 container recreate on 2026-09-14), which made Gitea reject all admin API calls with 403 — not 401, so credentials were fine. Cleared 2026-09-22 with docker exec -u git gitea gitea admin user must-change-password --unset gitea_admin (password unchanged; vault still valid). The admin API works again.
• Optional cleanup: prune the stale duplicate runner rows (59 of them now). Unblocked by the admin-API fix above. ansible-playbook -i inventory/hosts.ini gitea-deploy.yml --tags gitea_runner_prune. Purely cosmetic — deletes only runners the API reports offline.

Note on the two fixes: CI now has two independent reasons to work — the workflow no longer uses apt at all, and the job image is no longer EOL (bookworm still serves docker.io fine). The static-binary approach remains the more durable of the two; keep it regardless.

1.3 Developer-facing copy is visible on the live contact page 🛑

src/pages/contact.astro:37-41 renders, to real visitors:

"The form is static-first and posts to the configured endpoint when PUBLIC_CONTACT_FORM_ENDPOINT is set. Without an endpoint, it opens an email…"

• Delete that .form-note. Replace with visitor-appropriate copy or nothing.

1.4 Contact form has no endpoint 🛑

PUBLIC_CONTACT_FORM_ENDPOINT is "" in k8s/configmap.yaml, so the form falls back to a mailto handoff. Inbound leads will be lost or awkward on day one.

• Choose an endpoint (Formspree / webhook / ntfy / self-hosted) and set it in the ConfigMap.
• Test a real submission end-to-end and confirm /thank-you/ is reached.
• Confirm the delivery address is monitored.

1.5 Placeholder blog post would go live and be indexed 🛑

src/content/insights/example-draft.md has draft: true, but the flag is declared in the Zod schema and never enforced — no filter on getCollection("insights") in src/pages/insights/[slug].astro or the index. Result: /insights/example-draft/ is built and listed in dist/sitemap-0.xml, so "Example draft insight" ships to Google.

• Either filter drafts out of getCollection (both the index and getStaticPaths) — the durable fix — or delete the file.
• Re-run npm run build and confirm the URL is gone from sitemap-0.xml.
• Decide whether /insights/ should ship at all with zero real articles (see §3).

1.6 Canonical host is undecided 🛑 owner

The ingress answers on both apex and www; astro.config.mjs, robots.txt, and the ConfigMap all hardcode https://www.bluecapstrategies.com. Serving identical content on two hosts with no redirect splits SEO signal from day one.

• Owner picks apex or www.
• Configure a 301 from the loser to the winner (traefik middleware or edge).
• Reconcile PUBLIC_SITE_URL, canonical tags, robots.txt Sitemap line, and the ingress.

---

2. Should-fix before cutover

2.1 e2e suite is red — stale assertions, not a regression

4 of 46 tests fail. Both failures assert invented copy that the exact-copy work correctly removed:

• tests/site.spec.ts:67 waits for a link named Explore services; the homepage CTA is now All services (matches live WP).
• tests/site.spec.ts:101 waits for a heading matching /Focused expertise/, which no longer exists on /focus-areas/.

Navigation itself works. The tests are wrong, not the site.

• Update the two tests to assert current copy.
• Get back to 46/46 so the suite is trustworthy at cutover.

2.2 Repo hygiene

Commit 9f1cbca committed ~50 .playwright-mcp/ screenshots and YAML snapshots plus a 2.8 MB home-full.png at the repo root.

• Add .playwright-mcp/ to .gitignore; remove the tracked artifacts and home-full.png.

2.3 Uptime monitoring is not deployed

Per ADR-0004 the plan is to reuse the homelab monylog stack (not Uptime Kuma). Pod metrics and nginx logs already flow via Alloy; the external-availability piece was never added.

• [?] Verify current state on monylog-1 — the items below are from notes, not re-verified today.
• Add blackbox_exporter + web-bluecap.yml alert rules; re-run the monylog ansible role to reload Prometheus.
• Confirm an external HTTPS check fires to Pushover on a simulated outage. Do this before cutover — the first hours on new infrastructure are when you most need paging.

2.4 Analytics is a no-op

src/components/Analytics.astro is wired into BaseLayout but gated on PUBLIC_ env vars that are absent from k8s/configmap.yaml, so nothing is collected.

• Decide whether to launch with analytics or add it after (ADR-0005: PostHog + Umami trial).
• PostHog requires a privacy/consent notice before production use — that gates it, not the code.
• Set the env vars and confirm pageviews plus a consultation/CTA event.

---

3. Owner decisions (Brad)

These are yours, not mine. Several block content that is otherwise ready.

• 🛑 Canonical host — apex vs www (also §1.6).
• 🛑 Contact details — confirm 804-332-6618 / info@bluecapstrategies.com are the production values. (The live WP contact page carries placeholders 123-456-8912 / info@gmail.com, deliberately not reproduced; see docs/content-deviations.md.)
• 🛑 AI training-bot policy — GPTBot and ClaudeBot are currently Allow: / in public/robots.txt, with a ready-to-uncomment Disallow: /. Search and answer crawlers stay allowed either way. Decide before the site is publicly crawlable.
• 🛑 Brad Rodgers bio + credentials + portrait — gates Person schema, the About buildout, and principal-led E-E-A-T/GEO positioning. Core asset, still missing.
• 🛑 Real insights articles — no fabricated or unreviewed AI content. Until one exists, /insights/ is an empty section in the nav (see §1.5).
• 🛑 Social profiles — the live site only has per-page share links and empty # hrefs. Provide real profiles or omit the footer block.
• 🛑 /test/ page — the live site has a staging duplicate of the homepage. Default: omit.
• 🛑 Proof modules / representative engagements — no fabricated client work or dollar figures. Provide real ones or ship without.

---

4. Post-cutover (not blocking)

• Google Search Console + Bing Webmaster verified; sitemap-index.xml submitted.
• Per-page 1200×630 OG images. Every page currently shares one fallback; BaseLayout.astro:49 emits a single og:image.
• robots meta wired to a noindex frontmatter flag. /thank-you/ is excluded from the sitemap but emits no noindex meta tag.
• article:published_time / article:modified_time OG tags on insights posts (absent today).
• lastmod in the sitemap from content dates.
• Lighthouse ≥ 95 on SEO / Perf / Best-Practices / Accessibility; watch CLS from unsized images.
• Trailing-slash audit — trailingSlash: "always"; confirm canonicals and internal links agree.
• Decommission plan for the WordPress/Bluehost instance (keep it live and reachable through cutover + a rollback window; see the "keep old site live" constraint).

---

5. Already done — do not redo

Recorded because the older checklists still list several of these as open.

• Full copy parity: home, about, services, focus areas, all 8 service detail pages, all 4 focus-area detail pages — verbatim live copy in Markdown content collections (ADR-0002).
• Real imagery imported to public/assets/live-site/ (+ /icons); placeholders deleted.
• Zod seoSchema in src/content.config.ts — build fails on title/description/OG violations.
• scripts/seo-lint.mjs + npm run seo:lint — single-h1, heading order, canonical, alt text, JSON-LD parse. Green on 21 pages.
• BreadcrumbList schema (src/utils/schema.ts) applied across detail pages — the SEO doc still lists this as to-do; it is done.
• Per-agent public/robots.txt; @astrojs/sitemap excluding /thank-you/.
• Deviations logged in docs/content-deviations.md.
• GitOps: Gitea Actions CI, Gitea Packages registry, ArgoCD Application, External-Secrets registry pull auth over public HTTPS (ADR-0007, ADR-0008). Proven end-to-end in July — currently stalled, see §1.2.
• Monitoring approach decided: reuse monylog, not Uptime Kuma (ADR-0004). The SEO doc's "Uptime Kuma" line is superseded.