mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-23 00:20:40 +07:00
fix(infra): envsubst filter as |-regex; test placeholder as resolvable IP
Run 3 failed at the test step: nginx's official entrypoint matches NGINX_ENVSUBST_FILTER as a regex against variable names (^filter$), so the comma form GITEA_TOKEN,GITEA_CONTENTS_API matched nothing — ${…} tokens stayed in the rendered config and nginx -t failed with 'unknown "gitea_contents_api" variable'. A literal hostname in proxy_pass is resolved during the config test, so the test placeholder must be a resolvable literal IP. Both reproduced and fixed locally against the repo files: the exact test-step container now passes nginx -t (exit 0). compose.yaml + deploy-infra.yml use GITEA_TOKEN|GITEA_CONTENTS_API (quoted in the shell script) and http://127.0.0.1:1. Spec rev.8: status line, D11, §4 sketch + resolved note, rows 2/4.
This commit is contained in:
1 parent
773000a42a
commit
a5a525ff14
3 files changed
+18
-13
No files matched your search
@@ -77,8 +77,8 @@ jobs:
|
||||
-v "$PWD/nginx.conf:/etc/nginx/templates/default.conf.template:ro" \
|
||||
-v "$PWD/deploy/htpasswd:/etc/nginx/htpasswd:ro" \
|
||||
-e GITEA_TOKEN=placeholder \
|
||||
-e GITEA_CONTENTS_API=http://placeholder \
|
||||
-e NGINX_ENVSUBST_FILTER=GITEA_TOKEN,GITEA_CONTENTS_API \
|
||||
-e GITEA_CONTENTS_API=http://127.0.0.1:1 \
|
||||
-e 'NGINX_ENVSUBST_FILTER=GITEA_TOKEN|GITEA_CONTENTS_API' \
|
||||
nginx:alpine nginx -t
|
||||
|
||||
# Apply + verify (D4): recreate is the same command the Dockge deploy
|
||||
|
||||
+7
-3
@@ -13,9 +13,13 @@ services:
|
||||
# daemonizes and the container exits.
|
||||
entrypoint: ["sh", "-c", ". /run/secrets/site_config && exec /docker-entrypoint.sh \"$$@\""]
|
||||
environment:
|
||||
# Names the variables the template renderer substitutes, so $uri/$host
|
||||
# stay nginx runtime variables. The filter itself is not sensitive.
|
||||
NGINX_ENVSUBST_FILTER: GITEA_TOKEN,GITEA_CONTENTS_API
|
||||
# Names the variables the template renderer substitutes. The filter is a
|
||||
# REGEX the official entrypoint matches against each variable name
|
||||
# (`t ~ /^(filter)$/`) — alternatives MUST be separated with |, a comma
|
||||
# matches nothing and leaves ${…} in the rendered config (nginx -t then
|
||||
# fails: unknown "gitea_contents_api" variable — reproduced 2026-10-23).
|
||||
# $uri/$host stay nginx runtime variables. The filter is not sensitive.
|
||||
NGINX_ENVSUBST_FILTER: GITEA_TOKEN|GITEA_CONTENTS_API
|
||||
volumes:
|
||||
- ./dist:/usr/share/nginx/html:ro
|
||||
# Mounted as a template: the image's envsubst step renders it to
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Specification — v4 Deploy Infra (redeploy the nginx container; externalize site identity from the repo)
|
||||
|
||||
Status: **Design agreed 2026-10-23 (rev.7); repo side implemented 2026-10-23; owner-side setup + first 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). 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.
|
||||
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.
|
||||
|
||||
## 1. Current state
|
||||
|
||||
@@ -32,7 +32,7 @@ Dockge is a UI over compose files on disk: it reads the stack's `compose.yaml` f
|
||||
| D8 | **No Dockge REST API in this design.** Upstream Dockge has no management API yet (louislam/dockge PR #973, an authenticated management API with `X-API-Key`, is an open draft as of 2026-06-21); the `finder39/dockge` fork has one. If the installed Dockge turns out to be that fork — or the PR lands upstream — the restart/health steps can later move to the API as a simplification, replacing only step 4's docker commands. | Designing against an API that does not exist upstream would block implementation on someone else's merge. |
|
||||
| D9 | The repository compose file is named **`compose.yaml`** (repo root), matching Dockge's stack-file convention and the Compose spec standard name. Renamed 2026-10-23 (`git mv`); `docker compose` discovers it automatically, so local usage is unchanged. The rsync maps repo path → stack path 1:1 with no rename step. | Follow the manager's convention: one name across the repo, the stack directory, and the Dockge UI. The old name would have needed an rsync rename or a second copy on the VPS. |
|
||||
| D10 | **`SITE_URL` (canonical origin) becomes a build-time environment value**, not a repo literal. Repository literals removed: `src/data/site.ts` (reads `process.env.SITE_URL` for the tsx scripts, with an `import.meta.env` fallback for any future browser importer; **unset → throw** — a production build never emits a half-configured sitemap/meta, same loud-failure rule as content validation), `index.html` (the 6 absolute-URL literals — canonical, og:url, og:image, twitter:image, JSON-LD url+image — become `%SITE_URL%` tokens filled by a ~8-line inline `transformIndexHtml` plugin in `vite.config.ts`; dev fallback `http://localhost:5173`), `public/robots.txt` (deleted — `scripts/generate-sitemap.ts` writes `dist/robots.txt` together with `dist/sitemap.xml` from the same value; the existing "index.html contains siteUrl" guard stays and now validates the injection). CI: `env: SITE_URL: ${{ vars.SITE_URL }}` on the `build` and `generate-resume` jobs of `deploy.yml` (rev.7: Actions variables — public values, not secrets; the resume template consumes `{{SITE_URL}}`). Local: uncommitted `.env`, committed `.env.example`. | The owner's rule 2026-10-23: the repo stores no explicit website identity. One value in one place (CI variable / local .env); moving the site to a new domain is a settings change, not a code change. |
|
||||
| D11 | **`GITEA_CONTENTS_API` (full Contents-API base URL, incl. repo path) becomes a runtime configuration value** consumed only by the nginx container and the dev proxy — never CI, never the bundle. Repository literals removed: `nginx.conf` (`proxy_pass ${GITEA_CONTENTS_API};`, rev.6; the `proxy_set_header Host code.vugado.com` line is deleted — nginx's default `$proxy_host` for a literal proxy_pass gives the identical Host header) and `vite.config.ts:19-22` (parse `process.env.GITEA_CONTENTS_API` into proxy target + rewrite prefix; unset → no proxy → edit mode offline, identical to today's no-token behavior). `envsubst` renders at container start **before** nginx parses the config, so the rendered `proxy_pass` is a literal string — no `resolver` needed. Server home: the stack's single config file (D13); local home: the uncommitted local `.env` (vite's standard channel; the dev machine has no Dockge UI). `NGINX_ENVSUBST_FILTER=GITEA_TOKEN,GITEA_CONTENTS_API` stays a plain env var in compose — it names variables to substitute, it is not itself sensitive. | The Gitea host + `dong.nguyen/cv` path is infrastructure, not product — today it appears in `nginx.conf:50,52` and `vite.config.ts:19-22`, so the dev proxy drifts from production by hand; after this both read the same value. The URL is public, so its secret-file home is about **placement** (outside the repo, outside the Dockge env tab), not confidentiality. |
|
||||
| D11 | **`GITEA_CONTENTS_API` (full Contents-API base URL, incl. repo path) becomes a runtime configuration value** consumed only by the nginx container and the dev proxy — never CI, never the bundle. Repository literals removed: `nginx.conf` (`proxy_pass ${GITEA_CONTENTS_API};`, rev.6; the `proxy_set_header Host code.vugado.com` line is deleted — nginx's default `$proxy_host` for a literal proxy_pass gives the identical Host header) and `vite.config.ts:19-22` (parse `process.env.GITEA_CONTENTS_API` into proxy target + rewrite prefix; unset → no proxy → edit mode offline, identical to today's no-token behavior). `envsubst` renders at container start **before** nginx parses the config, so the rendered `proxy_pass` is a literal string — no `resolver` needed. Server home: the stack's single config file (D13); local home: the uncommitted local `.env` (vite's standard channel; the dev machine has no Dockge UI). `NGINX_ENVSUBST_FILTER=GITEA_TOKEN|GITEA_CONTENTS_API` stays a plain env var in compose — it names variables to substitute, it is not itself sensitive. [rev.8: the filter is a **regex** the official entrypoint matches against each variable name — alternatives MUST be separated with `|`; the original comma form matched nothing and left the `${…}` tokens in the rendered config.] | The Gitea host + `dong.nguyen/cv` path is infrastructure, not product — today it appears in `nginx.conf:50,52` and `vite.config.ts:19-22`, so the dev proxy drifts from production by hand; after this both read the same value. The URL is public, so its secret-file home is about **placement** (outside the repo, outside the Dockge env tab), not confidentiality. |
|
||||
| D12 | **`SITE_NAME` (the `<title>`/og:title/twitter:title string) also becomes an env value.** The three `index.html` literals become `%SITE_NAME%` tokens filled by the same plugin; `site.ts`'s `siteName` export (currently **dead** — no consumer in the repo) is kept as the config module's typed accessor for the plugin and scripts. Known duplication recorded: the same person string exists in the content dictionaries (`profile.name` + `profile.title`); meta tags are build-time single-language chrome while content is runtime per-language, so v1 accepts the duplication and the env value. A future single-source option (compose the title from the documents at build time) is a follow-up, not part of this change. | Owner chose "Gồm cả siteName" 2026-10-23. Leaving the name in the repo while the URL moves out would half-solve the stated goal. |
|
||||
| D13 | **The stack's runtime config is ONE server-side file, not `.env`, not multiple files** (owner direction 2026-10-23: "don't use .env", "use only one file"). `compose.yaml`: `secrets: [site_config]` with `secrets.site_config.file = ./secrets/site_config` (stack directory, chmod 600, owner-side, gitignored), a dotenv-format file holding exactly `GITEA_TOKEN=…` and `GITEA_CONTENTS_API=…` (shell-safe values: hex token, URL — no spaces/quotes). The entrypoint sources it before the official entrypoint renders: `entrypoint: ["sh", "-c", ". /run/secrets/site_config && exec /docker-entrypoint.sh \"$$@\""]` — `$$` is compose's escape for a literal `$`, so the rendered container command receives `"$@"`, which forwards the image's default CMD (`nginx -g 'daemon off;'`); without it nginx daemonizes and the container exits. The full target file is §4.1. The stack directory has **no `.env` at all**; no sensitive value appears in compose's `environment:`. File-based secrets under plain `docker compose` (non-swarm) were verified on the VPS 2026-10-23. | Env vars appear in plaintext in the Dockge env editor and in `docker inspect`; a sourced secret file appears in neither (only its path is visible). Startup stays unattended: the file is read at container start, no human key (an "encrypted .env + key" scheme would break pipeline/boot recreations, which have no one to type the key). One file = one rotation surface, one rsync exclusion, one drift candidate. The only remaining plaintext is the rendered `default.conf` inside the container's writable layer — never bind-mounted, never on the host. |
|
||||
|
||||
@@ -61,8 +61,8 @@ jobs:
|
||||
-v "$PWD/nginx.conf:/etc/nginx/templates/default.conf.template:ro" \
|
||||
-v "$PWD/deploy/htpasswd:/etc/nginx/htpasswd:ro" \
|
||||
-e GITEA_TOKEN=placeholder \
|
||||
-e GITEA_CONTENTS_API=http://placeholder \
|
||||
-e NGINX_ENVSUBST_FILTER=GITEA_TOKEN,GITEA_CONTENTS_API \
|
||||
-e GITEA_CONTENTS_API=http://127.0.0.1:1 \
|
||||
-e 'NGINX_ENVSUBST_FILTER=GITEA_TOKEN|GITEA_CONTENTS_API' \
|
||||
nginx:alpine nginx -t
|
||||
4 appleboy/ssh-action — script:
|
||||
cd <stack dir>/dong-site
|
||||
@@ -74,7 +74,7 @@ jobs:
|
||||
```
|
||||
|
||||
Notes:
|
||||
- The test container renders the template with **pure placeholders on the command line** — `nginx -t` validates syntax only, and `proxy_pass http://placeholder/…` is valid syntax (a literal host needs no resolver check at `-t`). It mounts the template and the htpasswd file (`-t` opens `auth_basic_user_file`); it reads no config file and no secrets: the real values never enter the test container or the job. [Resolved on the 2026-10-23 runs: (1) the comma-separated `path` input reaches rsync as ONE quoted literal filename (`link_stat "nginx.conf,compose.yaml,deploy/htpasswd"` failed) → three single-path steps; (2) the action prepends `$GITHUB_WORKSPACE` to `path` (`LOCAL_PATH="$GITHUB_WORKSPACE/$INPUT_PATH"`), so `-R` mirrored the absolute workspace path — a `workspace/dong.nguyen/cv/…` tree appeared on the VPS → the workflow uses plain `-avz` with a per-step `remote_path` instead.]
|
||||
- The test container renders the template with **pure placeholders on the command line** — `nginx -t` validates syntax only. It mounts the template and the htpasswd file (`-t` opens `auth_basic_user_file`); it reads no config file and no secrets: the real values never enter the test container or the job. [Resolved on the 2026-10-23 runs + a local reproduction of this exact step: (1) the comma-separated `path` input reaches rsync as ONE quoted literal filename → three single-path steps; (2) the action prepends `$GITHUB_WORKSPACE` to `path`, so `-R` mirrored the absolute workspace path onto the VPS → plain `-avz` + per-step `remote_path`; (3) `NGINX_ENVSUBST_FILTER` is a regex matched against variable names — the comma form substituted nothing and `nginx -t` failed `unknown "gitea_contents_api" variable` → `|`-separated (quoted in the shell script); (4) a literal hostname in `proxy_pass` IS resolved during the config test — the placeholder must be a resolvable literal IP (`http://127.0.0.1:1`), not `http://placeholder`. With all four fixed the reproduced test step passes (`exit 0`).]
|
||||
- The health probe uses `wget` (busybox) because `nginx:alpine` carries no curl.
|
||||
- Restart gap is ~1–2 s (single container). Accepted for a personal site; a two-container swap is explicitly out of scope.
|
||||
- `on.push.paths` is evaluated by the act runner — assumed supported on this Gitea [INFERENCE: verify on the first real run — the first run did execute after the push that touched the three files; confirm the trigger event label in the Actions UI to close this]. Fallback if the filter is ignored: a first step that diffs `$GITHUB_BASE_REF..$GITHUB_SHA` (or the head commit) against the trigger paths and exits early.
|
||||
@@ -100,8 +100,9 @@ services:
|
||||
entrypoint: ["sh", "-c", ". /run/secrets/site_config && exec /docker-entrypoint.sh \"$$@\""]
|
||||
environment:
|
||||
# Names the variables the template renderer substitutes, so $uri/$host
|
||||
# stay nginx runtime variables. The filter itself is not sensitive.
|
||||
NGINX_ENVSUBST_FILTER: GITEA_TOKEN,GITEA_CONTENTS_API
|
||||
# stay nginx runtime variables. The filter is a REGEX matched against
|
||||
# variable names — alternatives separated with | — and not sensitive.
|
||||
NGINX_ENVSUBST_FILTER: GITEA_TOKEN|GITEA_CONTENTS_API
|
||||
volumes:
|
||||
- ./dist:/usr/share/nginx/html:ro
|
||||
# Mounted as a template: the image's envsubst step renders it to
|
||||
@@ -168,7 +169,7 @@ GITEA_CONTENTS_API=https://<gitea-host>/api/v1/repos/<owner>/<repo>/contents/
|
||||
| 1b | Rename `docker-compose.yaml` → `compose.yaml` (D9) + AGENTS.md references | ✅ Done 2026-10-23 — `git mv`; `docker compose config --quiet` validates (only the expected local `GITEA_TOKEN`-unset warning) |
|
||||
| 2 | `.gitea/workflows/deploy-infra.yml` per §4 | ✅ Done 2026-10-23 — checkout → three single-path rsync steps (-avz, per-step remote_path; htpasswd → …/dong-site/deploy/) → test container (placeholders + htpasswd mount) → recreate + wget/nginx -t probe; appleboy/ssh-action pinned v1.2.0. Run fixes 2026-10-23: comma-list `path` failed (single quoted argument) → three steps; `-R` + the action's workspace-prefixed source mirrored `workspace/dong.nguyen/cv/…` onto the VPS → `-R` dropped |
|
||||
| 3 | Restricted Gitea token `site-contents-write` (Contents write, expiry) + create stack `secrets/site_config` (chmod 600, two KEY=value lines) | ⬜ TODO — owner-side |
|
||||
| 4 | First verified run + acceptance §7 | 🟡 Runs 2026-10-23: run 1 failed at rsync (comma-list), nothing shipped; run 2 shipped to the wrong places (workspace mirror; `deploy/htpasswd` landed as a directory). Both causes fixed in the workflow. Owner-side before the next dispatch: delete the stray `workspace/` dir in the stack directory, and make `deploy/` hold the htpasswd as a FILE (rsync cannot overwrite a directory with a file) — then `workflow_dispatch` |
|
||||
| 4 | First verified run + acceptance §7 | 🟡 Runs 2026-10-23: run 1 failed at rsync (comma-list), nothing shipped; run 2 shipped to the wrong places (workspace mirror; `deploy/htpasswd` landed as a directory); run 3 failed at the test step (`NGINX_ENVSUBST_FILTER` comma form → unsubstituted `${…}` → `unknown "gitea_contents_api" variable`). All four causes fixed in the workflow and **verified locally** (the exact test-step container reproduced against the repo files: `nginx -t` exit 0). Owner-side before the next dispatch: delete the stray `workspace/` dir in the stack directory, and make `deploy/` hold the htpasswd as a FILE (rsync cannot overwrite a directory with a file) — then `workflow_dispatch` |
|
||||
| 5 | Docs: AGENTS.md Deployment table + live-edit §12 row 11 status | ✅ Done 2026-10-23 |
|
||||
| 6 | D10–D12 implementation: `site.ts` env read, `index.html` tokens + vite plugin, robots generation, `nginx.conf` variables, `vite.config.ts` env proxy, `deploy.yml` env, `.env.example`, AGENTS.md | ✅ Done 2026-10-23 — verified: `pnpm build` with `.env` filled emits injected meta + `dist/robots.txt`; `SITE_URL=` empty fails with the named-variable error; runtime files grep-clean of `vugado` |
|
||||
| 9 | D13 implementation: `compose.yaml` per §4.1 (secret `site_config` + entrypoint override), `.gitignore` += `secrets/`; VPS: create `secrets/site_config`, delete stack `.env` | 🟡 Repo side Done 2026-10-23 (`compose config --quiet` validates); owner-side file + stack `.env` removal TODO |
|
||||
|
||||
Reference in new issue
Block a user