Repo side of spec-v4-deploy-infra: deploy-infra.yml (paths-filtered nginx redeploy, test-before-touch, health probe); compose.yaml rename + secrets/site_config entrypoint override; site identity externalized - SITE_URL/SITE_NAME read from env (site.ts, vite site-identity plugin, index.html tokens, generated robots.txt); nginx.conf/vite dev proxy read GITEA_CONTENTS_API; .env.example; AGENTS.md + specs updated. Rev.7: site identity delivered as Gitea Actions variables (vars. context, public values) instead of secrets; upload-artifact unified to v7 across jobs.
25 KiB
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.
1. Current state
deploy.ymlshipsdist/by rsync to/opt/stacks/dong-site/dist/on the VPS. The live containerdong-site(compose at/opt/stacks/dong-site/compose.yaml) mounts./dist,./nginx.confas an envsubst template, and./deploy/htpasswd.- On the VPS the stack is managed by Dockge (upstream — confirmed by the owner 2026-10-23, so D8 applies exactly as written): the stack file is
/opt/stacks/dong-site/compose.yaml—DOCKGE_STACKS_DIR=/opt/stacksconfirmed — and day-to-day operations (start/stop/logs/deploy button) happen in the Dockge UI. Dockge reads the compose file from disk every time a stack is opened and its deploy action runsdocker composein the same directory — so a pipeline that writes those files and runs the same commands is exactly what Dockge itself would do. There is no hidden Dockge state to keep in sync. nginx.conf,compose.yaml,deploy/htpasswdare committed but never deployed: row 11 made them a one-time manual server step. Three editing surfaces exist (repo, manual SSH, Dockge UI) — drift is therefore possible.GITEA_TOKENlives only in/opt/stacks/dong-site/.envon the VPS;NGINX_ENVSUBST_FILTER=GITEA_TOKENrestricts the template substitution to that variable.
2. Why the pipeline is Dockge-safe
Dockge is a UI over compose files on disk: it reads the stack's compose.yaml from the stack directory every time the stack is opened, and its deploy action runs docker compose in that same directory. A pipeline that writes exactly those files and runs exactly those commands is doing what the Dockge UI itself does — there is no hidden Dockge state to keep in sync.
rsyncwrites the stack's own files in Dockge's stack directory — the same files the Dockge UI opens.docker compose up -d --force-recreatein the stack directory is the same command the Dockge deploy button runs.- The test container (step 3) touches nothing in the stack directory.
- Verification after a pipeline run: open the stack in the Dockge UI — it shows the deployed file content and live container state. No extra tooling.
3. Decisions
| # | Decision | Rationale |
|---|---|---|
| D1 | A separate workflow deploy-infra.yml, triggered by push: master + paths: [nginx.conf, compose.yaml, deploy/htpasswd], plus workflow_dispatch for manual redeploy (the token rotation runbook needs this). concurrency.group: deploy-infra, independent of group: deploy — the dist rsync and a container restart do not collide. |
An infra step inside deploy.yml would restart nginx on every content commit, and edit mode saves to master ARE content commits. The paths filter is the whole point. |
| D2 | Remote commands run through appleboy/ssh-action (pinned), reusing the existing secrets DEPLOY_HOST / DEPLOY_SSH_PORT / DEPLOY_USER / DEPLOY_SSH_PRIVATE_KEY. No new secrets. |
Chosen by the owner over raw ssh steps; the action handles the key file and host-key checking. |
| D3 | Test-before-touch: validate the new template in a throwaway docker run --rm nginx:alpine … nginx -t on the VPS BEFORE restarting the live container; then docker compose up -d --force-recreate; then a health probe. |
nginx -t against the live container only discovers a bad config after production already took it. A failed test fails the job and production keeps serving the old config. |
| D4 | Apply with up -d --force-recreate, never nginx -s reload, never plain up -d. |
The config is mounted as a template: envsubst runs at container start. A reload would keep the previously rendered default.conf. Plain up -d does not recreate on bind-mount content changes (no config-hash change); --force-recreate also covers the case where the trigger was compose.yaml or the stack's config file itself. |
| D5 | Token-safety rules (§5). The infra workflow never sees GITEA_TOKEN; it is not added to Gitea Actions secrets. |
The token's home stays server-side only — the stack's single config file (D13) — and the workflow never touches its value. |
| D6 | The rsync ships exactly the three triggered files, no --delete, never secrets/. |
The stack's config file is server-side config (rev.6 removed the stack .env entirely); --delete in a partial rsync would risk wiping stack files. |
| D7 | Single source of truth for the three infra files is the repository. Production compose/config changes are made in the repo and land through the pipeline; the Dockge UI is used for observation and container operations, not for editing the stack files. | Dockge adds a third editing surface on top of repo and manual SSH. Without this rule the copies drift silently. If a change is ever made in the Dockge UI anyway, the pipeline's next run overwrites it from the repo — so commit it back to the repo first. |
| 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. |
| 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. |
Env surface (the whole contract): SITE_URL + SITE_NAME = Gitea Actions variables (vars. context) on the build/generate-resume jobs — revised 2026-10-23: these are public values, so Gitea's variables mechanism is the correct channel (secrets are for sensitive values; masked secrets also made a missing/empty SITE_URL undiagnosable in logs); GITEA_TOKEN + GITEA_CONTENTS_API = the stack's single config file secrets/site_config (D13; never in .env, never in the repository, never in CI, never in the bundle). Local development: an uncommitted local .env (vite's standard channel) carries the runtime values; .env.example is committed with all four names (SITE_URL, SITE_NAME, GITEA_TOKEN, GITEA_CONTENTS_API) and no values.
4. Workflow contract (design, not yet the final YAML)
name: Redeploy Nginx
on:
push: { branches: [master], paths: [nginx.conf, compose.yaml, deploy/htpasswd] }
workflow_dispatch:
concurrency: { group: deploy-infra, cancel-in-progress: false }
jobs:
redeploy:
steps:
1 actions/checkout
2 burnett01/rsync-deployments — switches: -avzR (no --delete; -R keeps deploy/htpasswd under deploy/)
paths: nginx.conf,compose.yaml,deploy/htpasswd (comma-separated input)
remote_path: <dockge stack dir>/dong-site/ (existing DEPLOY_* secrets)
3 appleboy/ssh-action — script:
cd <stack dir>/dong-site
docker run --rm \
-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 \
nginx:alpine nginx -t
4 appleboy/ssh-action — script:
cd <stack dir>/dong-site
docker compose up -d --force-recreate dong-site
sleep 2
docker exec dong-site wget -q -O /dev/null http://127.0.0.1/ # alpine nginx has no curl
docker exec dong-site nginx -t
On failure: docker logs --tail 50 dong-site (and fail the job)
Notes:
- The test container renders the template with pure placeholders on the command line —
nginx -tvalidates syntax only, andproxy_pass http://placeholder/…is valid syntax (a literal host needs no resolver check at-t). It mounts the template and the htpasswd file (nginx -topensauth_basic_user_file); it reads no config file and no secrets: the real values never enter the test container or the job. [INFERENCE: the rsync action's comma-separatedpathinput — verify on the first real run; fallback = three single-path steps.] - The health probe uses
wget(busybox) becausenginx:alpinecarries 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.pathsis evaluated by the act runner — assumed supported on this Gitea [INFERENCE: verify on the first real run]. 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.
4.1 Target compose.yaml — the complete final file (design contract, not yet applied)
The repo copy == the stack-directory copy (D7, D9). Diff vs today's file: delete GITEA_TOKEN: ${GITEA_TOKEN} from environment: (that line is the only compose interpolation today, and it is what makes the value visible in docker inspect and the Dockge env tab); add the entrypoint override and the secrets block.
# Repo-as-source-of-truth copy (deploy-infra spec D7/D9): rsynced to the stack
# directory and run there by the pipeline or Dockge. Runtime values live in
# secrets/site_config, which is NOT in the repository — the repo carries no
# site identity (D10-D13).
services:
dong-site:
image: nginx:alpine
container_name: dong-site
restart: unless-stopped
# Source the config file, then hand over to the image's official entrypoint.
# "$$@" is compose's escape: the rendered command sees "$@", forwarding the
# image's default CMD (nginx -g 'daemon off;') — without it nginx
# 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
volumes:
- ./dist:/usr/share/nginx/html:ro
# Mounted as a template: the image's envsubst step renders it to
# /etc/nginx/conf.d/default.conf with the variables sourced above.
- ./nginx.conf:/etc/nginx/templates/default.conf.template:ro
- ./deploy/htpasswd:/etc/nginx/htpasswd:ro
secrets:
- site_config
networks:
- docker-network
secrets:
site_config:
file: ./secrets/site_config
secrets/site_config (stack directory, chmod 600, gitignored via .gitignore += secrets/), exactly two lines:
GITEA_TOKEN=<restricted write token>
GITEA_CONTENTS_API=https://<gitea-host>/api/v1/repos/<owner>/<repo>/contents/
- Same file path and format on the VPS and locally: local
docker compose upfor the nginx test needs the samesecrets/site_configcreated locally (gitignored); vite keeps reading the local.env(D11) — both local files hold the same two values, neither is committed. - No top-level
name:key: the stack directory already defines the compose project name (matches today's live behavior — do not add one). - Validation before the first run:
docker compose config --quiet(run by hand, never inside the infra job — it interpolates).
5. Token security (answers "how to secure the Gitea token?")
- Single home.
GITEA_TOKENlives only in the stack's config filesecrets/site_config(chmod 600, deploy-user owned; D13), mounted by compose as/run/secrets/site_configand sourced at container start by the entrypoint override. Never in the repository, never in any.env, never in Gitea Actions secrets, never in the SPA bundle, never in workflow logs. - Least scope. A dedicated Gitea restricted access token (not the owner's personal token): repository
dong.nguyen/cvonly, Contents write only, namedsite-contents-write, with an expiry (6 months) so rotation is scheduled, not optional. - Transport. Browser → nginx
/api/content/(HTTP Basic,deploy/htpasswd— SHA-512 crypt hashes, committed; hashes not plaintext) → nginx addsAuthorization: token ${GITEA_TOKEN}server-side (nginx.conf:53) → Gitea over HTTPS. The browser never sees the token; the rendereddefault.confcontains it but the file never leaves the container. - No-leak rules for the infra workflow: never rsync
secrets/; pass env via placeholders or--env-file, never-e GITEA_TOKEN=$GITEA_TOKEN; nevercat/source the config file, rundocker compose config, ordocker exec … envinside the job (all print interpolated values); noset -xaround lines that touch the stack config. - Rotation runbook: create the new restricted token in Gitea → overwrite the
GITEA_TOKEN=line in the stack'ssecrets/site_configon the VPS → rundeploy-infraviaworkflow_dispatch(it recreates the container cleanly and health-checks it) → revoke the old token. This is whyworkflow_dispatchis part of D1. The config file is intentionally NOT in the workflow's paths filter: config edits must not auto-trigger a redeploy by themselves; the dispatch IS the deploy step.
6. Risks
- Stack drift (blocks the first run): row 11 applied the config manually on the server, and the Dockge UI is a third editing surface (D7). Before enabling the workflow, diff the stack directory's
nginx.conf/compose.yaml/htpasswdagainst the repo copies; the first run overwrites the server with the repo versions. Note the VPS stack file is already namedcompose.yaml(D9) — the repo rename lands on the same name, no server-side rename is needed. (Owner-side check; no repo access from CI to the VPS.) - Paths filter support on the act runner [INFERENCE] — fallback in §4.
- A bad
compose.yamlpushed to master recreates the container with the bad definition; the health probe catches it, and rollback = revert the commit + dispatch again. - Missing config file: if
secrets/site_configdoes not exist in the stack directory,docker compose upfails with a "secret … not found" error — caught at step 4, live container untouched. Mitigation: §8 row 3 creates the file before the first run; D6 never rsyncssecrets/, so the pipeline can never delete it.
7. Acceptance criteria
- A change to
nginx.confon master triggers ONLYdeploy-infra(no site rebuild, no resume job). - A content-only commit triggers
deploy.ymlonly — no nginx restart. - First real run: test container passes, container recreates, health probe 200,
?editprobe authenticates through the proxy. - After a pipeline run, opening the stack in the Dockge UI shows the synced file content and a healthy container (no split-brain between pipeline state and Dockge view).
- A deliberately broken
nginx.conffails the job at the test step; the live site keeps serving the previous config. workflow_dispatchre-runs the pipeline end-to-end (token rotation runbook).- No workflow log contains the token or any env-interpolated output.
- No runtime source file (
src/,scripts/,index.html,nginx.conf,vite.config.ts,public/) containsvugadoor the repo path — grep-clean exceptdist/output and historical docs. pnpm buildwithoutSITE_URLfails with the explicit error naming the variable; with it,index.html,dist/robots.txt,dist/sitemap.xml, and both resume PDFs carry the injected origin/name — all from one value.pnpm devwithout any env still boots (localhost fallback meta, no/api/content/proxy → edit mode offline); with.envfilled, edit mode works exactly as today.- The rendered production
default.confequals today's hand-written block byte-for-byte given the sameGITEA_CONTENTS_APIvalue (assert withdocker exec dong-site cat /etc/nginx/conf.d/default.confon the first run). - The stack directory contains no
.env(rev.6);docker inspect dong-siteand the Dockge env tab show noGITEA_TOKEN/GITEA_CONTENTS_APIvalues (D13); the only plaintext token is inside the container's rendereddefault.conf.
8. Progress Tracking
| # | Task | Status |
|---|---|---|
| 0 | Design agreed (D1–D9, rev.3 owner facts confirmed) | ✅ Done 2026-10-23 |
| 1 | Owner-side confirmations: stack path /opt/stacks ✅, upstream Dockge ✅, stack-file name compose.yaml ✅ (all confirmed 2026-10-23); remaining: stack-vs-repo drift diff (§6) |
🟡 TODO — drift diff blocks the first run |
| 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 → rsync (-avzR, three files) → test container (placeholders + htpasswd mount) → recreate + wget/nginx -t probe; appleboy/ssh-action pinned v1.2.0 |
| 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 | ⬜ TODO |
| 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 |
| 7 | Owner-side: Gitea Actions variables SITE_URL, SITE_NAME (rev.: switched from secrets 2026-10-23 — public values belong in the vars. context); local .env from .env.example |
🟡 Local .env created 2026-10-23 (values known; GITEA_TOKEN left as shell env as before); Gitea variables TODO — owner-side |