From a5ff55bacfe404bb840962df7f05ce003f08ac45 Mon Sep 17 00:00:00 2001 From: "dong.nguyen" Date: Wed, 28 Oct 2026 11:57:23 +0700 Subject: [PATCH] =?UTF-8?q?infra:=20Basic-auth=20file=20leaves=20the=20rep?= =?UTF-8?q?ository=20(spec-v6=20D16)=20=E2=80=94=20deploy/htpasswd=20gitig?= =?UTF-8?q?nored,=20written=20on=20the=20VPS=20from=20the=20HTPASSWD=5FCON?= =?UTF-8?q?TENT=20secret;=20Gitea=20mirrors=20brought=20to=20full=20parity?= =?UTF-8?q?=20(permissions,=20STACK=5FDIR/CONTAINER=5FNAME=20guards)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/deploy-infra.yml | 110 ++++++++++++++---- .gitea/workflows/deploy.yml | 36 +++++- .github/workflows/deploy-infra.yml | 51 +++++--- .gitignore | 4 + .omp/RULES.md | 2 +- AGENTS.md | 10 +- README.md | 14 ++- compose.override.yaml | 3 +- deploy/htpasswd | 1 - docs/design/specs/v4/spec-v4-deploy-infra.md | 2 +- .../design/specs/v6/spec-v6-github-actions.md | 29 ++++- 11 files changed, 199 insertions(+), 63 deletions(-) delete mode 100644 deploy/htpasswd diff --git a/.gitea/workflows/deploy-infra.yml b/.gitea/workflows/deploy-infra.yml index 79a795c..88c10cb 100644 --- a/.gitea/workflows/deploy-infra.yml +++ b/.gitea/workflows/deploy-infra.yml @@ -1,8 +1,11 @@ name: Redeploy Nginx -# Infra files only (spec-v4-deploy-infra D1): a change to the nginx template, -# the compose definition, or the Basic-auth file redeploys the container — -# content commits never do. workflow_dispatch is the token-rotation runbook. +# Infra files only (spec-v4-deploy-infra D1): a change to the nginx template or +# the compose definition redeploys the container — content commits never do. +# workflow_dispatch is the token-rotation runbook. The Basic-auth file is no +# longer repository content (spec-v6 D16): the HTPASSWD_CONTENT secret carries +# it and the job writes it on the server. Mirror of .github/workflows/ — +# scheduled for deletion (D9); kept behaviour-identical until then. on: push: branches: @@ -10,7 +13,6 @@ on: paths: - nginx.conf - compose.yaml - - deploy/htpasswd workflow_dispatch: concurrency: @@ -20,21 +22,60 @@ concurrency: jobs: redeploy: runs-on: ubuntu-latest + permissions: + contents: read steps: - uses: actions/checkout@v7 + # The stack directory and the container name are the server's deployment layout, + # not repository content: both come from repository variables (spec-v6 D15), and + # STACK_DIR is the same value `deploy.yml` uses. A missing STACK_DIR would rsync + # the two infra files into the remote user's home and then run docker in the + # wrong place; a CONTAINER_NAME that disagrees with the service this repository + # ships would recreate nothing and probe a container that does not exist. Both are + # refused here — before any rsync, before anything reaches the server. + - name: Check stack variables + env: + STACK_DIR: ${{ vars.STACK_DIR }} + CONTAINER_NAME: ${{ vars.CONTAINER_NAME }} + run: | + case "$STACK_DIR" in + /*) ;; + *) + echo "::error::STACK_DIR is not an absolute path — add it as a repository variable (Settings → Actions → Secrets and Variables → Variables), value: the Dockge stack directory, e.g. /opt/stacks/dong-site" + exit 1 + ;; + esac + case "$STACK_DIR" in + */) + echo "::error::STACK_DIR must not end with / — this job appends the slashes it needs" + exit 1 + ;; + esac + # The name is used twice over: as the compose service to recreate, and as the + # docker target of the health probe. compose.yaml — this repository — declares + # both, so the variable is checked against the file it has to agree with. + if ! grep -qE "^ ${CONTAINER_NAME}:" compose.yaml; then + echo "::error::CONTAINER_NAME is not a service in compose.yaml — the recreate step names a compose service, so the two must match" + exit 1 + fi + if ! grep -qF "container_name: ${CONTAINER_NAME}" compose.yaml; then + echo "::error::CONTAINER_NAME does not match container_name in compose.yaml — docker exec and docker logs target that name" + exit 1 + fi + echo "Stack: $STACK_DIR, container: $CONTAINER_NAME" - # Ship exactly the three triggered files. Never .env, never secrets/ (D6). + # Ship exactly the two triggered files. Never .env, never secrets/ (D6). # The action builds the rsync source as "$GITHUB_WORKSPACE/$path" and passes # it as one argument (entrypoint.sh) — so NO --relative: -R mirrors the whole # absolute workspace path onto the server (run 2026-10-23 created # dong-site/workspace/dong.nguyen/cv/… on the VPS). Plain -avz lands each - # file's basename in remote_path; the htpasswd step names deploy/ itself. + # file's basename in remote_path. - name: Sync nginx.conf uses: burnett01/rsync-deployments@v9 with: switches: -avz path: nginx.conf - remote_path: /opt/stacks/dong-site/ + remote_path: ${{ vars.STACK_DIR }}/ remote_host: ${{ secrets.DEPLOY_HOST }} remote_port: ${{ secrets.DEPLOY_SSH_PORT }} remote_user: ${{ secrets.DEPLOY_USER }} @@ -44,26 +85,44 @@ jobs: with: switches: -avz path: compose.yaml - remote_path: /opt/stacks/dong-site/ - remote_host: ${{ secrets.DEPLOY_HOST }} - remote_port: ${{ secrets.DEPLOY_SSH_PORT }} - remote_user: ${{ secrets.DEPLOY_USER }} - remote_key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }} - - name: Sync deploy/htpasswd - uses: burnett01/rsync-deployments@v9 - with: - switches: -avz - path: deploy/htpasswd - remote_path: /opt/stacks/dong-site/deploy/ + remote_path: ${{ vars.STACK_DIR }}/ remote_host: ${{ secrets.DEPLOY_HOST }} remote_port: ${{ secrets.DEPLOY_SSH_PORT }} remote_user: ${{ secrets.DEPLOY_USER }} remote_key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }} + # The Basic-auth file is repository-secret content, not repository content + # (spec-v6 D16): the HTPASSWD_CONTENT secret carries the one htpasswd line + # (user + bcrypt hash), inlined into a single-quoted shell literal — a + # bcrypt hash is riddled with `$` and appleboy's `envs:` mechanism exports + # values unquoted, so the remote shell would expand `$2y…` away. Written + # BEFORE the test step: nginx -t opens auth_basic_user_file, so its mount + # needs a real file. chmod 600 keeps the credential readable only by the + # stack owner. Needs the HTPASSWD_CONTENT secret on Gitea too. + - name: Write deploy/htpasswd from the secret + uses: appleboy/ssh-action@v1.2.0 + with: + host: ${{ secrets.DEPLOY_HOST }} + port: ${{ secrets.DEPLOY_SSH_PORT }} + username: ${{ secrets.DEPLOY_USER }} + key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }} + script: | + cd "${{ vars.STACK_DIR }}" + HTPASSWD='${{ secrets.HTPASSWD_CONTENT }}' + if [ -z "$HTPASSWD" ]; then + echo "HTPASSWD_CONTENT is not set as a repository secret — add the output of: htpasswd -nbB ''" >&2 + exit 1 + fi + mkdir -p deploy + printf '%s\n' "$HTPASSWD" > deploy/htpasswd + chmod 600 deploy/htpasswd + # Test-before-touch (D3): the throwaway container runs the same entrypoint # render pipeline as production, with placeholder values — nginx -t checks # syntax only, so the real token never enters this container or the job. # A failure here fails the job; the live container keeps serving. + # The placeholder must be a resolvable literal IP: a literal hostname in + # proxy_pass IS resolved while the config is parsed (spec-v4-deploy-infra §4). - name: Test new config uses: appleboy/ssh-action@v1.2.0 with: @@ -72,7 +131,7 @@ jobs: username: ${{ secrets.DEPLOY_USER }} key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }} script: | - cd /opt/stacks/dong-site + cd "${{ vars.STACK_DIR }}" docker run --rm \ -v "$PWD/nginx.conf:/etc/nginx/templates/default.conf.template:ro" \ -v "$PWD/deploy/htpasswd:/etc/nginx/htpasswd:ro" \ @@ -82,7 +141,8 @@ jobs: nginx:alpine nginx -t # Apply + verify (D4): recreate is the same command the Dockge deploy - # button runs. The health probe uses wget because nginx:alpine carries no + # button runs, with the service/container names from CONTAINER_NAME — already + # checked against compose.yaml above. The health probe uses wget because nginx:alpine carries no # curl; on failure the job prints the container log and fails. - name: Recreate and probe uses: appleboy/ssh-action@v1.2.0 @@ -92,11 +152,11 @@ jobs: username: ${{ secrets.DEPLOY_USER }} key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }} script: | - cd /opt/stacks/dong-site - docker compose up -d --force-recreate dong-site + cd "${{ vars.STACK_DIR }}" + docker compose up -d --force-recreate "${{ vars.CONTAINER_NAME }}" sleep 2 - if ! docker exec dong-site wget -q -O /dev/null http://127.0.0.1/; then - docker logs --tail 50 dong-site + if ! docker exec "${{ vars.CONTAINER_NAME }}" wget -q -O /dev/null http://127.0.0.1/; then + docker logs --tail 50 "${{ vars.CONTAINER_NAME }}" exit 1 fi - docker exec dong-site nginx -t + docker exec "${{ vars.CONTAINER_NAME }}" nginx -t diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml index e047f54..fb66942 100644 --- a/.gitea/workflows/deploy.yml +++ b/.gitea/workflows/deploy.yml @@ -12,9 +12,12 @@ concurrency: jobs: build: runs-on: ubuntu-latest - # Site identity (spec-v4-deploy-infra D10/D12): the build and the resume + permissions: + contents: read + # Site identity (spec-v4-deploy-infra D10/D12, spec-v6 D3): the build and the resume # generator derive every published URL and the page title from these two - # values; the build fails loudly when either is missing. + # values; the build fails loudly when either is missing. They are repository + # variables — public values, not secrets. env: SITE_URL: ${{ vars.SITE_URL }} SITE_NAME: ${{ vars.SITE_NAME }} @@ -36,6 +39,8 @@ jobs: generate-resume: runs-on: ubuntu-latest needs: build + permissions: + contents: read env: SITE_URL: ${{ vars.SITE_URL }} SITE_NAME: ${{ vars.SITE_NAME }} @@ -82,7 +87,32 @@ jobs: deploy: runs-on: ubuntu-latest needs: [build, generate-resume] + permissions: + contents: read steps: + # The stack directory is the server's deployment layout, not repository + # content: it comes from the STACK_DIR repository variable (spec-v6 D15). An + # empty or malformed value would aim rsync at /dist/ on the remote host, so the + # job refuses it here — before any artifact download, before anything reaches the + # server — exactly like the site-identity check refuses a missing SITE_URL. + - name: Check stack directory + env: + STACK_DIR: ${{ vars.STACK_DIR }} + run: | + case "$STACK_DIR" in + /*) ;; + *) + echo "::error::STACK_DIR is not an absolute path — add it as a repository variable (Settings → Actions → Secrets and Variables → Variables), value: the Dockge stack directory, e.g. /opt/stacks/dong-site" + exit 1 + ;; + esac + case "$STACK_DIR" in + */) + echo "::error::STACK_DIR must not end with / — this job appends /dist/ itself" + exit 1 + ;; + esac + echo "Deploy target: $STACK_DIR/dist/" - uses: actions/download-artifact@v8 with: name: static-site @@ -104,7 +134,7 @@ jobs: debug: true switches: -avzr --delete path: dist/ - remote_path: /opt/stacks/dong-site/dist/ + remote_path: ${{ vars.STACK_DIR }}/dist/ remote_host: ${{ secrets.DEPLOY_HOST }} remote_port: ${{ secrets.DEPLOY_SSH_PORT }} remote_user: ${{ secrets.DEPLOY_USER }} diff --git a/.github/workflows/deploy-infra.yml b/.github/workflows/deploy-infra.yml index aa804ad..ea9b79b 100644 --- a/.github/workflows/deploy-infra.yml +++ b/.github/workflows/deploy-infra.yml @@ -1,8 +1,11 @@ name: Redeploy Nginx -# Infra files only (spec-v4-deploy-infra D1): a change to the nginx template, -# the compose definition, or the Basic-auth file redeploys the container — -# content commits never do. workflow_dispatch is the token-rotation runbook. +# Infra files only (spec-v4-deploy-infra D1): a change to the nginx template or +# the compose definition redeploys the container — content commits never do. +# workflow_dispatch is the token-rotation runbook. The Basic-auth file is no +# longer repository content (spec-v6 D16): the HTPASSWD_CONTENT secret carries +# it and the job writes it on the server, so credential rotation is a secret +# edit + a dispatch, never a commit. on: push: branches: @@ -10,7 +13,6 @@ on: paths: - nginx.conf - compose.yaml - - deploy/htpasswd workflow_dispatch: concurrency: @@ -27,7 +29,7 @@ jobs: # The stack directory and the container name are the server's deployment layout, # not repository content: both come from repository variables (spec-v6 D15), and # STACK_DIR is the same value `deploy.yml` uses. A missing STACK_DIR would rsync - # the three infra files into the remote user's home and then run docker in the + # the two infra files into the remote user's home and then run docker in the # wrong place; a CONTAINER_NAME that disagrees with the service this repository # ships would recreate nothing and probe a container that does not exist. Both are # refused here — before any rsync, before anything reaches the server. @@ -62,12 +64,12 @@ jobs: fi echo "Stack: $STACK_DIR, container: $CONTAINER_NAME" - # Ship exactly the three triggered files. Never .env, never secrets/ (D6). + # Ship exactly the two triggered files. Never .env, never secrets/ (D6). # The action builds the rsync source as "$GITHUB_WORKSPACE/$path" and passes # it as one argument (entrypoint.sh) — so NO --relative: -R mirrors the whole # absolute workspace path onto the server (run 2026-10-23 created # dong-site/workspace/dong.nguyen/cv/… on the VPS). Plain -avz lands each - # file's basename in remote_path; the htpasswd step names deploy/ itself. + # file's basename in remote_path. - name: Sync nginx.conf uses: burnett01/rsync-deployments@v9 with: @@ -88,16 +90,33 @@ jobs: remote_port: ${{ secrets.DEPLOY_SSH_PORT }} remote_user: ${{ secrets.DEPLOY_USER }} remote_key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }} - - name: Sync deploy/htpasswd - uses: burnett01/rsync-deployments@v9 + + # The Basic-auth file is repository-secret content, not repository content + # (spec-v6 D16): the HTPASSWD_CONTENT secret carries the one htpasswd line + # (user + bcrypt hash). The secret is inlined into a single-quoted shell + # literal — a bcrypt hash is riddled with `$` and appleboy's `envs:` + # mechanism exports values unquoted, so the remote shell would expand `$2y…` + # away; the htpasswd character set (user name + bcrypt base64) contains no + # single quote, so this quoting is exact. Written BEFORE the test step: + # nginx -t opens auth_basic_user_file, so its mount needs a real file. + # chmod 600 keeps the credential readable only by the stack owner. + - name: Write deploy/htpasswd from the secret + uses: appleboy/ssh-action@v1.2.0 with: - switches: -avz - path: deploy/htpasswd - remote_path: ${{ vars.STACK_DIR }}/deploy/ - remote_host: ${{ secrets.DEPLOY_HOST }} - remote_port: ${{ secrets.DEPLOY_SSH_PORT }} - remote_user: ${{ secrets.DEPLOY_USER }} - remote_key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }} + host: ${{ secrets.DEPLOY_HOST }} + port: ${{ secrets.DEPLOY_SSH_PORT }} + username: ${{ secrets.DEPLOY_USER }} + key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }} + script: | + cd "${{ vars.STACK_DIR }}" + HTPASSWD='${{ secrets.HTPASSWD_CONTENT }}' + if [ -z "$HTPASSWD" ]; then + echo "HTPASSWD_CONTENT is not set as a repository secret — add the output of: htpasswd -nbB ''" >&2 + exit 1 + fi + mkdir -p deploy + printf '%s\n' "$HTPASSWD" > deploy/htpasswd + chmod 600 deploy/htpasswd # Test-before-touch (D3): the throwaway container runs the same entrypoint # render pipeline as production, with placeholder values — nginx -t checks diff --git a/.gitignore b/.gitignore index ec8d98a..38bf396 100644 --- a/.gitignore +++ b/.gitignore @@ -27,8 +27,12 @@ dist-ssr # Deployment/runtime config (spec-v4-deploy-infra D10/D13): the stack's # secrets/site_config and the local .env carry site identity and the write token. +# spec-v6 D16: the Basic-auth file is not repository content either — the +# pipeline writes it on the VPS from the HTPASSWD_CONTENT secret; the local copy +# exists only so `docker compose` can mount it. .env /secrets/ +/deploy/htpasswd # Generated code (spec-v5): src/types/content-ids.ts is produced by # scripts/generate-content-types.ts from src/data/*.json on predev/prebuild/prepare. diff --git a/.omp/RULES.md b/.omp/RULES.md index 6e562f8..29c2a6b 100644 --- a/.omp/RULES.md +++ b/.omp/RULES.md @@ -32,7 +32,7 @@ Do not start coding based only on the user's description. ## 4. Conversation language -**IMPORTANT:** All responses are in Vietnamese. Source code and docs are in English. +**IMPORTANT:** All responses are in English. ## 5. Don't run the headless browser to verify. diff --git a/AGENTS.md b/AGENTS.md index 8db4d1f..3fa0aac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -144,13 +144,13 @@ src/ ## Deployment -- Site deployment is triggered automatically by the GitHub workflow `.github/workflows/deploy.yml` (push to `master`); infra redeployment by `.github/workflows/deploy-infra.yml` — triggered ONLY by changes to `nginx.conf` / `compose.yaml` / `deploy/htpasswd`, plus `workflow_dispatch` (the token-rotation runbook): test-before-touch (`nginx -t` in a throwaway container with placeholder values), then `docker compose up -d --force-recreate` + health probe (spec: `docs/design/specs/v4/spec-v4-deploy-infra.md` + `docs/design/specs/v6/spec-v6-github-actions.md`) +- Site deployment is triggered automatically by the GitHub workflow `.github/workflows/deploy.yml` (push to `master`); infra redeployment by `.github/workflows/deploy-infra.yml` — triggered ONLY by changes to `nginx.conf` / `compose.yaml`, plus `workflow_dispatch` (the token-rotation runbook: overwrite the `HTPASSWD_CONTENT` repository secret, then dispatch — the Basic-auth file is no longer a commit target, spec-v6 D16): test-before-touch (`nginx -t` in a throwaway container with placeholder values), then `docker compose up -d --force-recreate` + health probe (spec: `docs/design/specs/v4/spec-v4-deploy-infra.md` + `docs/design/specs/v6/spec-v6-github-actions.md`) - The repository is GitHub-primary and **public**; `master` is unprotected on purpose (an edit-mode PUT must not be refused). `.gitea/workflows/` stays in the tree until the first green GitHub run is verified, then it is deleted and the Gitea repository is archived (spec-v6 D9) - Site identity is deployment-time configuration, not a repo literal: `SITE_URL` / `SITE_NAME` are GitHub **repository variables** (`vars.` context — public values, not secrets) passed as job env to `build` and `generate-resume`; locally they live in the uncommitted `.env` (template `.env.example`). A production build without them fails with an error naming the variable -- The stack directory and the container name are deployment-time configuration as well: both workflows read the stack path from the repository variable `STACK_DIR` — absolute, **no trailing slash**, because the jobs append `/dist/`, `/` and `/deploy/` themselves — and the infra job reads the compose service / container name it recreates and probes from `CONTAINER_NAME`. Each job refuses a bad value in its first step, before any artifact download or rsync reaches the VPS, and the infra guard greps `compose.yaml` so `CONTAINER_NAME` cannot disagree with the service and `container_name` this repository declares (spec-v6 D15) +- The stack directory and the container name are deployment-time configuration as well: both workflows read the stack path from the repository variable `STACK_DIR` — absolute, **no trailing slash**, because the jobs append `/dist/` and `/` themselves — and the infra job reads the compose service / container name it recreates and probes from `CONTAINER_NAME`. Each job refuses a bad value in its first step, before any artifact download or rsync reaches the VPS, and the infra guard greps `compose.yaml` so `CONTAINER_NAME` cannot disagree with the service and `container_name` this repository declares (spec-v6 D15) - Three jobs: `build` (`pnpm build` → `dist/` artifact) → `generate-resume` (`pnpm tsx scripts/generate-resume.ts --lang=en`, then `--lang=vi`) → `deploy` rsyncs `dist/`, both PDFs included, to `${{ vars.STACK_DIR }}/dist/` -- `nginx.conf` — production Nginx SPA routing + caching config + the `/api/content/` location: auth_basic (`deploy/htpasswd`) in front of a proxied Contents API, proxied to it over HTTP/2 (`proxy_http_version 2` + a cleared `Connection` header, spec-v4 D14, verified against `api.github.com` 2026-10-26; the stack's nginx 1.31.x already caches upstream connections by default since 1.29.7, so no `upstream` block is declared, and the template carries only `${CONTENT_API_BASE}` and `Bearer ${CONTENT_API_TOKEN}` — the token and the git host never enter the SPA bundle or the repository). The image's envsubst step renders the template **before nginx parses it**, so `proxy_pass` is a literal upstream rather than an nginx variable — the reason the location-prefix → directive-URI mapping works and the reason a placeholder in `proxy_pass` must be a resolvable literal IP (spec-v6 D4a) -- `compose.yaml` — the stack definition for local AND VPS use (repo copy == stack copy): runtime values live in `secrets/site_config` (gitignored file in the stack directory, two lines `CONTENT_API_TOKEN=` / `CONTENT_API_BASE=`, chmod 600), sourced by an entrypoint override (`set -a` + inline `nginx -g 'daemon off;'` — a compose entrypoint override drops the image's CMD) before the official entrypoint renders the template; the stack directory has no `.env`. On the VPS the same stack is managed by **Dockge** (upstream; stacks dir `/opt/stacks`, stack file `/opt/stacks/dong-site/compose.yaml`) — the repository is the single source of truth for `nginx.conf` / `compose.yaml` / `deploy/htpasswd` +- `nginx.conf` — production Nginx SPA routing + caching config + the `/api/content/` location: auth_basic (`/etc/nginx/htpasswd` — the file is **not committed**: `deploy-infra.yml` writes it on the VPS from the `HTPASSWD_CONTENT` repository secret, spec-v6 D16) in front of a proxied Contents API, proxied to it over HTTP/2 (`proxy_http_version 2` + a cleared `Connection` header, spec-v4 D14, verified against `api.github.com` 2026-10-26; the stack's nginx 1.31.x already caches upstream connections by default since 1.29.7, so no `upstream` block is declared, and the template carries only `${CONTENT_API_BASE}` and `Bearer ${CONTENT_API_TOKEN}` — the token and the git host never enter the SPA bundle or the repository). The image's envsubst step renders the template **before nginx parses it**, so `proxy_pass` is a literal upstream rather than an nginx variable — the reason the location-prefix → directive-URI mapping works and the reason a placeholder in `proxy_pass` must be a resolvable literal IP (spec-v6 D4a) +- `compose.yaml` — the stack definition for local AND VPS use (repo copy == stack copy): runtime values live in `secrets/site_config` (gitignored file in the stack directory, two lines `CONTENT_API_TOKEN=` / `CONTENT_API_BASE=`, chmod 600), sourced by an entrypoint override (`set -a` + inline `nginx -g 'daemon off;'` — a compose entrypoint override drops the image's CMD) before the official entrypoint renders the template; the stack directory has no `.env`. On the VPS the same stack is managed by **Dockge** (upstream; stacks dir `/opt/stacks`, stack file `/opt/stacks/dong-site/compose.yaml`) — the repository is the single source of truth for `nginx.conf` / `compose.yaml`; `deploy/htpasswd` is the exception (spec-v6 D16): it is gitignored, lives only on the server (written by the infra job from the `HTPASSWD_CONTENT` secret) and as an untracked local copy for the local compose mount - `compose.override.yaml` — local-only, auto-merged by `docker compose`, never rsynced by the pipeline: publishes the container on `127.0.0.1:8081` so the production stack can be browsed locally; the VPS stack is unaffected ``` @@ -210,7 +210,7 @@ All specification documents are in `docs/design/`: | `specs/v3/spec-v3-*.md` | v3 feature specs (theme colors, theme switch, theme palette switch, palette reference, UI enhancements, mobile navigation, nav & CTA enhancements, nav swatch & hamburger, typography, i18n, resume improvements, resume redesign, review fixes) | | `specs/v4/spec-v4-*.md` | v4 feature specs (i18n locale overlay, git-backed live edit with preview, authenticated Contents-API write path; supersedes v3-i18n Phase 2). `spec-v4-data-organization.md`: per-entity content files, per-page field-level manifests, per-feature-group UI — implemented 2026-10-23 (automated checks pass; browser walkthrough pending). `spec-v4-inline-editing.md`: edit everything on the page (pencil-icon triggers, tag chips, record add/delete/move, settings popover), JSON panel deleted — implemented 2026-10-23; it supersedes live-edit §5.1/§5.4 panel scope. `spec-v4-deploy-infra.md`: pipeline redeploy of the VPS nginx container, Dockge-managed stack (paths-filtered `deploy-infra.yml`, test-before-touch, repo-as-source-of-truth, token-safety rules) + externalizing site identity — `SITE_URL` / `SITE_NAME` as CI Actions variables, `GITEA_TOKEN` + `GITEA_CONTENTS_API` in the stack's single config file `secrets/site_config` — repo side implemented 2026-10-23 (`deploy-infra.yml`, `compose.yaml` secret + entrypoint override, env-driven identity); owner-side variables/config file + first verified run pending | | `specs/v5/spec-v5-*.md` | v5 feature specs. `spec-v5-generated-content-ids.md`: the content id unions and the project category values are generated from the structure documents (`scripts/generate-content-types.ts`, run by `predev` / `prebuild` / `prepare`), edit mode writes JSON only, validator rule 7 requires a label for every used category in both languages — implemented 2026-10-24; it supersedes the id-union legs of `spec-v4-live-edit.md` §3.1 | -| `specs/v6/spec-v6-*.md` | v6 feature specs. `spec-v6-github-actions.md`: both pipelines move to GitHub Actions and the repository becomes GitHub-primary, the write-path values are renamed `CONTENT_API_TOKEN` / `CONTENT_API_BASE` with a `Bearer` upstream header, `draft.ts` learns GitHub's 409 conflict answer, the site keeps its VPS/nginx/Dockge host and its three-job pipeline — repo side implemented 2026-10-26 (owner-side GitHub variables/secrets, the VPS `secrets/site_config` rewrite and the first verified run are open); it supersedes the CI-host legs of `spec-v4-deploy-infra.md` and the Contents-API status codes of `spec-v4-live-edit.md` §6.1 | +|`specs/v6/spec-v6-*.md`|v6 feature specs. `spec-v6-github-actions.md`: both pipelines move to GitHub Actions and the repository becomes GitHub-primary, the write-path values are renamed `CONTENT_API_TOKEN` / `CONTENT_API_BASE` with a `Bearer` upstream header, `draft.ts` learns GitHub's 409 conflict answer, the site keeps its VPS/nginx/Dockge host and its three-job pipeline, and the Basic-auth file leaves the repository — `deploy/htpasswd` is gitignored, the infra job writes it on the VPS from the `HTPASSWD_CONTENT` repository secret (D16, 2026-10-28) — repo side implemented 2026-10-26 (owner-side GitHub variables/secrets, the VPS `secrets/site_config` rewrite and the first verified run are open); it supersedes the CI-host legs of `spec-v4-deploy-infra.md` and the Contents-API status codes of `spec-v4-live-edit.md` §6.1| Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope. diff --git a/README.md b/README.md index 90c4fa1..2a305b4 100644 --- a/README.md +++ b/README.md @@ -78,11 +78,16 @@ mkdir -p secrets # CONTENT_API_TOKEN= # CONTENT_API_BASE=https://api.github.com/repos///contents/ chmod 600 secrets/site_config +# deploy/htpasswd — the Basic-auth file is not committed (spec-v6 D16), but the +# compose mount needs it locally. Generate one line with any htpasswd tool +# (e.g. `docker run --rm httpd:2 htpasswd -nbB editor ''`) and save it: +mkdir -p deploy +docker run --rm httpd:2 htpasswd -nbB editor '' > deploy/htpasswd docker network create docker-network # once; compose.yaml joins it docker compose up -d ``` -`compose.yaml` defines no published port (the VPS container is reached through its own fronting); `compose.override.yaml` — auto-merged by `docker compose`, never shipped by the pipeline — publishes the container on the local loopback. Open **`http://127.0.0.1:8081/`** in a browser; `?edit` there asks for HTTP Basic credentials from `deploy/htpasswd`. If 8081 is taken on your machine, change the host port in `compose.override.yaml`. Stop the stack with `docker compose stop`. +`compose.yaml` defines no published port (the VPS container is reached through its own fronting); `compose.override.yaml` — auto-merged by `docker compose`, never shipped by the pipeline — publishes the container on the local loopback. Open **`http://127.0.0.1:8081/`** in a browser; `?edit` there asks for HTTP Basic credentials against the local `deploy/htpasswd` you just created (the production copy is written by the infra pipeline from the `HTPASSWD_CONTENT` secret). If 8081 is taken on your machine, change the host port in `compose.override.yaml`. Stop the stack with `docker compose stop`. ## Production deployment (GitHub Actions) @@ -91,9 +96,9 @@ docker compose up -d | Workflow | Trigger | What it does | |---|---|---| | [`.github/workflows/deploy.yml`](.github/workflows/deploy.yml) | push to `master` | `build` (validate content → `pnpm build`) → `generate-resume` (EN + VI PDFs) → `deploy` rsyncs `dist/` (PDFs included) to `${STACK_DIR}/dist/` on the VPS | -| [`.github/workflows/deploy-infra.yml`](.github/workflows/deploy-infra.yml) | push to `master` touching `nginx.conf` / `compose.yaml` / `deploy/htpasswd`, or manual dispatch | rsyncs exactly those three files to the stack directory, tests the new config in a throwaway container (`nginx -t`), then `docker compose up -d --force-recreate` + health probe | +| [`.github/workflows/deploy-infra.yml`](.github/workflows/deploy-infra.yml) | push to `master` touching `nginx.conf` / `compose.yaml`, or manual dispatch | rsyncs exactly those two files to the stack directory, writes `deploy/htpasswd` there from the `HTPASSWD_CONTENT` repository secret, tests the new config in a throwaway container (`nginx -t`), then `docker compose up -d --force-recreate` + health probe | -Only `master` deploys. A content commit never restarts nginx; an infra commit never rebuilds the site. The VPS stack is managed by Dockge (`/opt/stacks/dong-site`); the repository is the single source of truth for the three infra files. +Only `master` deploys. A content commit never restarts nginx; an infra commit never rebuilds the site. The VPS stack is managed by Dockge (`/opt/stacks/dong-site`); the repository is the single source of truth for the two infra files — the Basic-auth file is the exception: it lives only on the server, written from the `HTPASSWD_CONTENT` secret (spec-v6 D16). The repository is GitHub-primary and public; the pipelines run on GitHub-hosted runners (free for public repositories). `master` carries no branch protection on purpose: edit mode writes straight to it, and the validation step in `build` is what keeps a malformed content commit from deploying. `.gitea/workflows/` is kept only until the first green GitHub run is verified, then deleted (spec-v6 D9). @@ -143,10 +148,11 @@ Then create GitHub Actions **secrets** — Settings → Secrets and variables | `DEPLOY_SSH_PORT` | SSH port | | `DEPLOY_USER` | `gitea-deployer` | | `DEPLOY_SSH_PRIVATE_KEY` | the private key content | +| `HTPASSWD_CONTENT` | the one htpasswd line — output of `htpasswd -nbB ''` (user + bcrypt hash). The infra job writes it to `${STACK_DIR}/deploy/htpasswd` (chmod 600); the credential never appears in the repository (spec-v6 D16) | **3. VPS stack config** — in the stack directory `/opt/stacks/dong-site/`, create `secrets/site_config` (chmod 600, exactly the two `KEY=value` lines shown in step 5 above). The token should be a dedicated GitHub **fine-grained PAT** (`site-contents-write`: this repository only, `Contents: Read and write`, with an expiry). The pipeline never rsyncs `secrets/`, so it can never touch this file; it never appears in `docker inspect` or the Dockge env tab. -**4. Edit-mode login** — production `/api/content/` sits behind HTTP Basic (`auth_basic` + `deploy/htpasswd`, committed as hashes). The browser prompts once per session. +**4. Edit-mode login** — production `/api/content/` sits behind HTTP Basic (`auth_basic` + the htpasswd file the infra pipeline writes from the `HTPASSWD_CONTENT` secret — the hash is no longer in the public repository). The browser prompts once per session. Rotating the editor password: regenerate the line (`htpasswd -nbB ''`), overwrite the secret, run `deploy-infra` via `workflow_dispatch` — no commit involved. ### Editing content in production diff --git a/compose.override.yaml b/compose.override.yaml index a76a6a9..67cbfd0 100644 --- a/compose.override.yaml +++ b/compose.override.yaml @@ -1,6 +1,7 @@ # Local-only compose override (compose spec: `docker compose` auto-merges this # file on top of compose.yaml). The deploy-infra pipeline rsyncs exactly -# nginx.conf / compose.yaml / deploy/htpasswd — never this file — so the VPS +# nginx.conf / compose.yaml (and writes the Basic-auth file from the +# HTPASSWD_CONTENT secret) — never this file — so the VPS # stack is unaffected. It publishes the container on the local loopback so the # site is reachable from a browser for testing the real serving path. services: diff --git a/deploy/htpasswd b/deploy/htpasswd deleted file mode 100644 index 10cf298..0000000 --- a/deploy/htpasswd +++ /dev/null @@ -1 +0,0 @@ -editor:$6$r8s2CI52cy1CMFfV$QeLOi/VWtifP.05NLZlUdbb5GP.FahiHBKYD4LKgOZGXLmEMWq1ODfTrLfpheCt0Rvwctp43h.SyirYFj23ll0 \ No newline at end of file diff --git a/docs/design/specs/v4/spec-v4-deploy-infra.md b/docs/design/specs/v4/spec-v4-deploy-infra.md index 4f34505..8172e89 100644 --- a/docs/design/specs/v4/spec-v4-deploy-infra.md +++ b/docs/design/specs/v4/spec-v4-deploy-infra.md @@ -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 diff --git a/docs/design/specs/v6/spec-v6-github-actions.md b/docs/design/specs/v6/spec-v6-github-actions.md index e6cc46f..8bb57d0 100644 --- a/docs/design/specs/v6/spec-v6-github-actions.md +++ b/docs/design/specs/v6/spec-v6-github-actions.md @@ -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 `, then `docker exec` / `docker logs `), 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 `, then `docker exec` / `docker logs `), 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