docs: reconcile to as-built (ADR-0008, deploy runbook); clean text hero on detail pages
CI / ci (push) Successful in 1m56s

- ADR-0008: private package, External-Secrets pull over public HTTPS (no k3s restart);
  CI auth via CI_TOKEN PAT; Playwright dropped from CI. Marks ADR-0007 partially superseded.
- gitops-deployment-strategy + deployment.md updated to as-built flow + operate/troubleshoot runbook
- content-deviations: detail-page heroes are text-only (no image)
- service/focus detail pages: clean text hero (drop shared photo/icon)
This commit is contained in:
gitea_admin authored and Brad Rodgers committed 2026-07-20 08:27:35 -04:00
1 parent 99d4a3bea9
commit fc64909f3d
9 files changed
+147 -48

No files matched your search

+35 -22
View File
@@ -30,41 +30,54 @@ docker build -t bluecap-strategies-website:latest .
docker run --rm -p 8080:80 bluecap-strategies-website:latest
```
## k3s
## k3s (as-built — deployed & serving in-cluster since 2026-07-17)
Production deployment should use the pull-based GitOps model documented in
`docs/gitops-deployment-strategy.md`.
The intended flow is:
Live GitOps flow (all working; see `docs/gitops-deployment-strategy.md` + ADR-0001/0007/0008):
```text
local edit -> git push -> GitHub Actions test/build/publish -> Git manifest image tag update -> ArgoCD reconciles k3s
local edit -> git push (Gitea main) -> Gitea Actions: build + seo:lint -> push image (internal
10.66.15.22:3000) -> bump DEPLOY_IMAGE tag + commit back [skip ci] -> ArgoCD reconciles k3s ->
k3s pulls git.7tl-homelab.com/... (private, ES pull secret, public HTTPS) -> pods serve
```
ArgoCD is already running in the homelab k3s cluster, so it is the reconciler (not Flux). GitHub
Actions should not receive kubeconfig or direct access to the homelab cluster.
- ArgoCD is the reconciler (not Flux); the CI runner never gets kubeconfig or cluster access.
- **Not yet public** — the ingress names `bluecapstrategies.com`/`www` but DNS still points at the
old WordPress site. Going public = the DNS Cutover below, a deliberate step. See the
`keep-old-site-live` rule: do nothing that affects the old site until cutover.
Manual `kubectl` use should be limited to bootstrapping the ArgoCD Application, read-only
inspection, and emergency operations. If you intentionally choose to apply the current manifests
by hand during a controlled bootstrap test, the command would be:
### Operate
```bash
kubectl apply -k k8s/
# Review the running site locally (no cluster/DNS impact):
kubectl -n bluecap-strategies port-forward svc/bluecap-website 18080:80 # then http://localhost:18080
# or purely off-cluster from source: npm run dev
# Health / status:
kubectl -n argocd get application bcs-website # Synced / Healthy
kubectl -n bluecap-strategies get pods,deploy # 2/2 Running
kubectl -n bluecap-strategies get externalsecret gitea-registry # SecretSynced
# Rollback: `git revert` the tag-bump commit and push (ArgoCD reconciles), or use ArgoCD history.
```
Do not treat that as the normal production deployment process.
### Troubleshoot (things that actually bit us)
The manifests assume Traefik ingress is available. Read-only research confirmed Traefik and
cert-manager are installed, with a ready `letsencrypt-prod` ClusterIssuer. However, TLS and ingress
hardening should remain documented rather than applied until the Pangolin/Newt edge path is
confirmed.
- **CI job never runs / "no matching runner"** → runner offline or mis-scoped. Must be a **global**
(owner_id=0) runner on `gitea_network` with instance URL `http://gitea:3000`; token must be an
**instance-level** registration token (Site Admin → Actions → Runners).
- **Push: "server gave HTTP response to HTTPS client"** → runner host dockerd missing
`insecure-registries: ["10.66.15.22:3000"]` (gitea Ansible role handles it).
- **Push: `unauthorized`** → `CI_TOKEN` repo secret missing/insufficient (`write:package` + `write:repository`).
- **Pod `ImagePullBackOff`** → ExternalSecret not synced (check OpenBao `cluster/bluecap-registry`
fields) or the `read:package` PAT.
- **`git push` rejected (fetch first)** → CI committed a tag bump to `main`; `git pull --rebase` first
(`git config pull.rebase true`).
Items to confirm before production ingress changes:
Manual `kubectl apply -k k8s/` is for emergency/bootstrap only, not normal deploys.
- Whether Pangolin/Newt terminates TLS, passes TLS through, or proxies HTTPS to Traefik.
- Whether Pangolin/Newt preserves `Host` headers for the BlueCap hostnames.
- Whether cert-manager's Cloudflare DNS-01 token can issue certificates for `bluecapstrategies.com`.
- Whether the canonical production host should be apex or `www`.
Ingress/TLS items to confirm before cutover: whether Pangolin/Newt terminates/passes/proxies TLS
to Traefik and preserves `Host` headers; whether cert-manager's Cloudflare DNS-01 token can issue
for `bluecapstrategies.com`; whether the canonical host is apex or `www`.
## DNS Cutover