docs: reconcile to as-built (ADR-0008, deploy runbook); clean text hero on detail pages
CI / ci (push) Successful in 1m56s
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:
1 parent
99d4a3bea9
commit
fc64909f3d
9 files changed
+147
-48
No files matched your search
+35
-22
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user