mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
infra: Basic-auth file leaves the repository (spec-v6 D16) — deploy/htpasswd gitignored, written on the VPS from the HTPASSWD_CONTENT secret; Gitea mirrors brought to full parity (permissions, STACK_DIR/CONTAINER_NAME guards)
This commit is contained in:
1 parent
c535e7a295
commit
a5ff55bacf
11 files changed
+199
-63
No files matched your search
@@ -2,7 +2,7 @@
|
||||
|
||||
Status: **Design agreed 2026-10-23 (rev.8); repo side implemented 2026-10-23; owner-side setup + first verified run TODO.** Closes the manual half of `spec-v4-live-edit.md` §12 row 11 (the infra files ship with a dedicated pipeline), and per the owner's direction of 2026-10-23 removes explicit site identity (`cv.vugado.com`, `code.vugado.com`, repo path, site name) from the repository — those values become deployment-time configuration (D10–D12). Rev.2 added the Dockge reality (D7, D8); rev.3 recorded the owner's confirmed facts (`DOCKGE_STACKS_DIR=/opt/stacks`, upstream Dockge, `compose.yaml` naming) and the matching repository rename (D9, done); rev.4 added the site-identity externalization design (D10–D12); rev.5 moved `GITEA_TOKEN` off the stack `.env` to a Docker secret file after the owner verified file-based secrets work on the VPS's `docker compose` (non-swarm); rev.6 removes the stack `.env` entirely (owner: "don't use .env") — both server-side values live in ONE file, `secrets/site_config` (D13); rev.7 switches the site-identity channel from Gitea Actions secrets to Actions variables (`vars.` context — public values; owner direction 2026-10-23, `deploy.yml` job env updated); rev.8 records the first-run fixes proven by the 2026-10-23 runs and a local reproduction of the test step: three single-path rsync steps, `-R` dropped (the action prefixes `$GITHUB_WORKSPACE`), `NGINX_ENVSUBST_FILTER` as a `|`-regex (a comma form matches nothing), and a resolvable test placeholder (`http://127.0.0.1:1`) — the reproduced test step passes. Implementation landed the same day: `deploy-infra.yml`, the §4.1 `compose.yaml`, `site.ts` env read, the vite site-identity plugin + env-driven dev proxy, generated `robots.txt`, `deploy.yml` job env, `.env.example`, AGENTS.md — see §8 for what remains owner-side.
|
||||
|
||||
> **Superseded in part on 2026-10-26 by `specs/v6/spec-v6-github-actions.md`:** the CI host is GitHub Actions, `SITE_URL` / `SITE_NAME` are GitHub repository variables, and the write-path values are `CONTENT_API_TOKEN` / `CONTENT_API_BASE` — the `GITEA_*` names throughout this document are what was in force when it was written (rev.7's channel decision, variables not secrets, carries over unchanged; only the host changes). D1–D4, D6–D9, D11–D13, the token-safety rules of §5 and the Dockge-safety argument stand as written; D14's HTTP/2 upstream was re-verified against `api.github.com` and stands.
|
||||
> **Superseded in part on 2026-10-26 by `specs/v6/spec-v6-github-actions.md`:** the CI host is GitHub Actions, `SITE_URL` / `SITE_NAME` are GitHub repository variables, and the write-path values are `CONTENT_API_TOKEN` / `CONTENT_API_BASE` — the `GITEA_*` names throughout this document are what was in force when it was written (rev.7's channel decision, variables not secrets, carries over unchanged; only the host changes). D1–D4, D6–D9, D11–D13, the token-safety rules of §5 and the Dockge-safety argument stand as written; D14's HTTP/2 upstream was re-verified against `api.github.com` and stands. **Further superseded 2026-10-28 (v6 rev.2 D16):** D1's `paths:` filter no longer includes `deploy/htpasswd` — the file is gitignored and written on the server by the infra job from the `HTPASSWD_CONTENT` repository secret; the rest of D1 (separate workflow, narrow triggers, `workflow_dispatch` as the rotation runbook) stands.
|
||||
|
||||
## 1. Current state
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Spec v6 — GitHub Actions
|
||||
|
||||
> **Parent:** `specs/v4/spec-v4-deploy-infra.md` (the pipeline design this one keeps), `specs/v4/spec-v4-live-edit.md` (the write path this one re-targets)
|
||||
> **Status:** rev.1 — repo side implemented 2026-10-26 (§7), automated checks pass (§8); the owner-side setup and the first verified run are open (§6).
|
||||
> **Status:** rev.1 — repo side implemented 2026-10-26 (§7), automated checks pass (§8); the owner-side setup and the first verified run are open (§6). rev.2 2026-10-28 — D16: the Basic-auth file leaves the repository (§7.1); repo side implemented, owner-side secret creation open (§6).
|
||||
> **Supersedes:** the CI-host legs of `spec-v4-deploy-infra.md` — the `vars.` env surface (§3 "Env surface"), D5's "not added to Gitea Actions secrets", D14's Gitea-only host claim — and the Contents-API status codes recorded in `spec-v4-live-edit.md` §6.1. Everything else in those specs (D1–D4, D6–D9, D11–D13, the token-safety rules, the Dockge-safety argument) stands unchanged.
|
||||
|
||||
---
|
||||
@@ -30,6 +30,7 @@ What does change is one thing the pipeline was never separate from: the reposito
|
||||
| D8 | GitHub-hosted runners, **public** repository. | GitHub Actions usage is free for public repositories on standard runners and free for self-hosted runners; a private repository would bill minutes against a monthly quota for a pipeline that installs pnpm twice and renders two PDFs. Accepted consequence: the content JSON and the commit history are public. |
|
||||
| D9 | `.gitea/workflows/` is kept until the first GitHub run is verified, then deleted. | Owner's call: see the pipelines run green on GitHub before cutting the old ones. This is a scheduled deletion recorded as an open item (§8), not a compatibility shim — nothing reads them once GitHub is the primary. |
|
||||
| D15 | The two server-side layout values the workflows hard-coded — the stack directory (5 call sites) and the service/container name `dong-site` (4 call sites) — become the **repository variables** `STACK_DIR` and `CONTAINER_NAME`; the job that uses each refuses a bad value in its first step. | Both describe the server's deployment layout, not repository content — the same class of value as `SITE_URL`: public, therefore a variable and not a secret. As literals they made a stack rename a multi-file YAML edit plus a docs sweep, and a typo would have rsynced `dist/` into the wrong directory or probed the wrong container. `CONTAINER_NAME` is checked against `compose.yaml` in the same step, because that one string is used twice over — as a compose service argument and as the `docker exec` / `docker logs` target — while the file declaring both lives in this repository. Guarding it first means a bad value fails the way the site-identity check fails: at once, naming the variable and where to set it. Recorded sequence: the owner asked for the path first and the name in the same session, so the name moved too rather than staying a literal. |
|
||||
| D16 | **2026-10-28 (rev.2):** the Basic-auth file leaves the repository. `deploy/htpasswd` is untracked and gitignored; `deploy-infra.yml` writes it into the stack directory (`chmod 600`) from the **repository secret** `HTPASSWD_CONTENT`, before the test step; the file's `paths:` trigger is dropped. Credential rotation is: regenerate the line (`htpasswd -nbB`), overwrite the secret, `workflow_dispatch` — no commit. | The repository is public (D8), and the htpasswd line is a user name plus a bcrypt hash — offline-bruteforceable from any clone, forever. A hash is not the plaintext, but it does not have to live in the public archive either; the file has exactly two consumers (the production container's `auth_basic_user_file` mount and the throwaway test container's mount), both reading it from the stack directory, which the job now guarantees before testing. The containment mirrors the write token's rules (§4): one home, never in the repository, never in the bundle. The value is inlined into a **single-quoted** shell literal in the ssh script: bcrypt's `$2y$…` must not reach the remote shell unquoted, and appleboy's `envs:` mechanism exports values unquoted — so `envs:` is not used; the htpasswd character set (user name + bcrypt base64) carries no single quote, which makes the quoting exact. The empty-secret case fails the step with a named error rather than writing an empty file nginx would accept. |
|
||||
|
||||
## 3. Facts verified during the review (method recorded)
|
||||
|
||||
@@ -52,9 +53,10 @@ What does change is one thing the pipeline was never separate from: the reposito
|
||||
| Value | Home | Consumers |
|
||||
|---|---|---|
|
||||
| `SITE_URL`, `SITE_NAME` | GitHub **repository variables** (`vars.`), passed as job env to `build` and `generate-resume` | the vite site-identity plugin, `src/data/site.ts`, `generate-sitemap.ts`, `generate-resume.ts` |
|
||||
| `STACK_DIR` | GitHub **repository variables** (`vars.`) — the absolute stack directory as the deploy user sees it, **no trailing slash** | the `deploy` job's `remote_path`, the infra job's three `remote_path`s and both `appleboy/ssh-action` scripts; the guard step in each job |
|
||||
| `STACK_DIR` | GitHub **repository variables** (`vars.`) — the absolute stack directory as the deploy user sees it, **no trailing slash** | the `deploy` job's `remote_path`, the infra job's two `remote_path`s and its three `appleboy/ssh-action` scripts; the guard step in each job |
|
||||
| `CONTAINER_NAME` | GitHub **repository variables** (`vars.`) — the compose service name and the container name, which `compose.yaml` declares as one and the same | the infra job's `docker compose up -d --force-recreate`, `docker exec` ×2 and `docker logs`; the guard step, which greps `compose.yaml` for both declarations |
|
||||
| `DEPLOY_HOST`, `DEPLOY_SSH_PORT`, `DEPLOY_USER`, `DEPLOY_SSH_PRIVATE_KEY` | GitHub **secrets** | the rsync step, both `appleboy/ssh-action` steps |
|
||||
| `DEPLOY_HOST`, `DEPLOY_SSH_PORT`, `DEPLOY_USER`, `DEPLOY_SSH_PRIVATE_KEY` | GitHub **secrets** | the rsync steps, the `appleboy/ssh-action` steps |
|
||||
| `HTPASSWD_CONTENT` | GitHub **secret** (D16) — the one htpasswd line, user + bcrypt hash | the infra job's "Write deploy/htpasswd from the secret" step, which writes `${STACK_DIR}/deploy/htpasswd` (chmod 600) before the test container mounts it; the nginx container then serves it as `auth_basic_user_file`. Locally: an untracked `deploy/htpasswd` copy, needed by the compose mount |
|
||||
| `CONTENT_API_TOKEN`, `CONTENT_API_BASE` | the stack's single config file `secrets/site_config` (chmod 600, server-side, never committed, never in CI) | the nginx container's envsubst template step; locally the uncommitted `.env`, read by `vite.config.ts` |
|
||||
| `NGINX_ENVSUBST_FILTER=CONTENT_API_TOKEN\|CONTENT_API_BASE` | `compose.yaml` | the official entrypoint's template renderer (a regex over variable **names**; alternatives separated with `\|`) |
|
||||
|
||||
@@ -62,7 +64,7 @@ The token's rules are unchanged from `spec-v4-deploy-infra.md` §5: single home,
|
||||
|
||||
`CONTENT_API_BASE` is the full Contents-API base including the repository path — for this repository: `https://api.github.com/repos/dong-nz/cv/contents/`.
|
||||
|
||||
`STACK_DIR` carries no trailing slash because the workflows append `/dist/`, `/` and `/deploy/` themselves; the guard rejects a trailing slash so a doubled one cannot reach rsync. `CONTAINER_NAME` is the single string `compose.yaml` declares twice — the service key `dong-site:` and `container_name: dong-site` — and the infra job uses it in both roles (`docker compose up -d --force-recreate <name>`, then `docker exec` / `docker logs <name>`), so the guard greps the checked-out `compose.yaml` and refuses a value matching neither. A stack rename is then: change `compose.yaml` in a commit, change the two variables — and the pipeline names the disagreement if the two are out of step.
|
||||
`STACK_DIR` carries no trailing slash because the workflows append `/dist/` and `/` themselves (D16 removed the third append: the auth file is written by the job, not rsynced); the guard rejects a trailing slash so a doubled one cannot reach rsync. `CONTAINER_NAME` is the single string `compose.yaml` declares twice — the service key `dong-site:` and `container_name: dong-site` — and the infra job uses it in both roles (`docker compose up -d --force-recreate <name>`, then `docker exec` / `docker logs <name>`), so the guard greps the checked-out `compose.yaml` and refuses a value matching neither. A stack rename is then: change `compose.yaml` in a commit, change the two variables — and the pipeline names the disagreement if the two are out of step.
|
||||
|
||||
## 5. Migration runbook — the order is part of the design
|
||||
|
||||
@@ -70,7 +72,7 @@ The token's rules are unchanged from `spec-v4-deploy-infra.md` §5: single home,
|
||||
2. Create the GitHub variables and secrets (§4), and the fine-grained write token.
|
||||
3. **Update `/opt/stacks/dong-site/secrets/site_config` on the VPS first** — both new names with the GitHub values. This must precede step 4: the migration commit touches `nginx.conf` and `compose.yaml`, so the infra workflow runs in the same push, and `--force-recreate` (D4 of the infra spec) restarts the container with the config the file just supplied. A config file still carrying the old names renders `${CONTENT_API_BASE}` unsubstituted, nginx fails to start, the health probe fails, and the site is down until the file is fixed. Nothing else in the sequence has that property.
|
||||
4. Merge the migration commit → `build` + `generate-resume` + `deploy` run on GitHub. The live site is untouched by this step: `deploy.yml` rsyncs `dist/` only.
|
||||
5. `deploy-infra.yml` runs in the same push (or by `workflow_dispatch`): rsync the three infra files → `nginx -t` in a throwaway container with placeholders → recreate → health probe.
|
||||
5. `deploy-infra.yml` runs in the same push (or by `workflow_dispatch`): rsync the two infra files, write `deploy/htpasswd` from the `HTPASSWD_CONTENT` secret (D16) → `nginx -t` in a throwaway container with placeholders → recreate → health probe.
|
||||
6. Smoke the write path: `curl` GET and PUT through `/api/content/` with the Basic credentials, confirm the commit lands on GitHub and the pipeline deploys it; then one real save from `?edit`.
|
||||
7. Verify a conflict once: two saves against the same document, or an out-of-band commit to `master` between a read and a save. The second must report a conflict with a rebase offer, not a failure.
|
||||
8. Delete `.gitea/workflows/` (D9) and archive the Gitea repository.
|
||||
@@ -85,6 +87,7 @@ The token's rules are unchanged from `spec-v4-deploy-infra.md` §5: single home,
|
||||
- [ ] Push the tag: `git push github v0.0.1` — the mirror carried branches but no tags.
|
||||
- [ ] Repository variables `SITE_URL`, `SITE_NAME`; secrets `DEPLOY_HOST`, `DEPLOY_SSH_PORT`, `DEPLOY_USER`, `DEPLOY_SSH_PRIVATE_KEY`. Without the variables `build` fails at the identity check; without the secrets the rsync and recreate steps fail while the infra test-before-touch step still passes.
|
||||
- [ ] Repository variables `STACK_DIR` (absolute stack directory, `/opt/stacks/dong-site`, no trailing slash) and `CONTAINER_NAME` (`dong-site`, matching `compose.yaml`). Both jobs stop at their first step without them.
|
||||
- [ ] GitHub secret `HTPASSWD_CONTENT` (D16, 2026-10-28): the current `deploy/htpasswd` line, verbatim. Without it `deploy-infra.yml` fails at the write step with a named error; the VPS copy written by the 2026-10-23 runs keeps serving until then. While `.gitea/workflows/` still exists (D9), Gitea must carry the same secret **plus the `STACK_DIR` / `CONTAINER_NAME` variables** (§7.1 parity, 2026-10-28): without them the Gitea mirror's guard steps refuse the run. After both hosts have the secret, the public repository no longer carries the bcrypt hash; old clones/commits still do — rotate the editor password if that matters.
|
||||
- [ ] VPS accepts SSH from GitHub-hosted runners (the old runner may have reached the host from the same machine or LAN; GitHub runners come from GitHub's published IP ranges).
|
||||
- [ ] First `deploy.yml` and `deploy-infra.yml` runs observed green; §5 steps 6–7 verified.
|
||||
- [x] Local config renamed (untracked files, done 2026-10-26): `.env` carries `SITE_URL`, `SITE_NAME`, `CONTENT_API_BASE` with the GitHub base, token still supplied as a shell variable; `secrets/site_config` carries the two new names with the token left empty. With the old names in either file the local stack cannot render nginx (`${CONTENT_API_BASE}` stays unsubstituted) and `pnpm dev` builds no `/api/content/` proxy.
|
||||
@@ -105,7 +108,21 @@ The token's rules are unchanged from `spec-v4-deploy-infra.md` §5: single home,
|
||||
| `src/data/site.ts` | doc comment: repository variables, not Gitea Actions variables |
|
||||
| `AGENTS.md`, `README.md` | CI host, env names, GitHub variables/secrets setup |
|
||||
| `specs/v4/spec-v4-deploy-infra.md`, `specs/v4/spec-v4-live-edit.md` | supersession notes pointing here; the v2 and v5 specs are completion records and are left as written |
|
||||
| `.gitea/workflows/*` | kept until the first green GitHub run (D9). `deploy-infra.yml`'s test step now carries the `CONTENT_API_*` names, because the template it validates is the one this repository ships; its stack path stays a literal — no `STACK_DIR` is created on Gitea for files that are scheduled for deletion |
|
||||
| `.gitea/workflows/*` | kept until the first green GitHub run (D9). `deploy-infra.yml`'s test step now carries the `CONTENT_API_*` names, because the template it validates is the one this repository ships. (Rev.1 note "its stack path stays a literal" is superseded by §7.1: the mirrors were brought to full parity with the GitHub workflows on 2026-10-28) |
|
||||
|
||||
### 7.1 rev.2 (2026-10-28) — D16: the Basic-auth file leaves the repository
|
||||
|
||||
| File | Change |
|
||||
|---|---|
|
||||
| `deploy/htpasswd` | `git rm --cached` — untracked, still on disk locally (the local compose mount needs it); its content moves to the `HTPASSWD_CONTENT` secret |
|
||||
| `.gitignore` | `+ /deploy/htpasswd`, in the deployment/runtime-config block beside `.env` and `secrets/` |
|
||||
| `.github/workflows/deploy-infra.yml` | `paths:` drops `deploy/htpasswd`; the "Sync deploy/htpasswd" rsync step is replaced by "Write deploy/htpasswd from the secret" (appleboy/ssh-action: `mkdir -p deploy`, single-quoted secret literal → `printf` → `chmod 600`, empty secret refused with a named error), placed before the test step whose container mounts the file |
|
||||
| `.gitea/workflows/deploy-infra.yml` | same D16 change as the GitHub file |
|
||||
| `.gitea/workflows/deploy.yml` + `.gitea/workflows/deploy-infra.yml` | **full parity with the GitHub workflows (owner decision 2026-10-28):** `permissions: contents: read` on every job; the "Check stack directory" / "Check stack variables" guard steps added; the literals `/opt/stacks/dong-site` (9 call sites) and `dong-site` (4) replaced by `${{ vars.STACK_DIR }}` / `${{ vars.CONTAINER_NAME }}`. The only intentional differences left: the header comments naming the mirror, and the guard error text pointing at Gitea's settings path (Settings → Actions → Secrets and Variables → Variables). Owner-side consequence: Gitea must now carry `STACK_DIR`, `CONTAINER_NAME` (variables) and `HTPASSWD_CONTENT` (secret) exactly like GitHub, or the guard steps refuse the run — that was previously avoided by the literals (§7's rev.1 note, superseded) |
|
||||
| `compose.yaml`, `nginx.conf` | untouched — the mount and `auth_basic_user_file` names are unchanged; only the file's origin moved |
|
||||
| `AGENTS.md`, `README.md`, `compose.override.yaml` (comment) | trigger list, source-of-truth wording, the secrets table row, and the local-stack step that creates `deploy/htpasswd` |
|
||||
|
||||
Repo-side verification 2026-10-28: YAML of both workflows parses; the write step's shell contract was exercised locally (a sample `user:$2y$…` line through the exact single-quoted `printf` form round-trips byte-identical, and a line containing `$` survives the remote shell unexpanded); `git status` shows `deploy/htpasswd` staged as removed while the file stays on disk. Owner-side: create the secret (§6), then the next infra run proves the write → test → recreate chain.
|
||||
|
||||
## 8. Accepted risks
|
||||
|
||||
|
||||
Reference in new issue
Block a user