diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..0621685 --- /dev/null +++ b/.env.example @@ -0,0 +1,10 @@ +# Site identity (build-time). In CI these are Gitea Actions variables on the +# build and resume jobs; locally they live in .env. A production build without +# them fails with an explicit error (src/data/site.ts, vite site-identity plugin). +SITE_URL= +SITE_NAME= + +# Edit-mode write path (dev only). Production reads both values from the +# stack's secrets/site_config on the VPS, never from a .env. +GITEA_TOKEN= +GITEA_CONTENTS_API= diff --git a/.gitea/workflows/deploy-infra.yml b/.gitea/workflows/deploy-infra.yml new file mode 100644 index 0000000..80075c0 --- /dev/null +++ b/.gitea/workflows/deploy-infra.yml @@ -0,0 +1,78 @@ +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. +on: + push: + branches: + - master + paths: + - nginx.conf + - compose.yaml + - deploy/htpasswd + workflow_dispatch: + +concurrency: + group: deploy-infra + cancel-in-progress: false + +jobs: + redeploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + # Ship exactly the three triggered files; -R keeps deploy/htpasswd under + # deploy/ in the stack directory. Never .env, never secrets/ (D6). + - name: Sync infra files + uses: burnett01/rsync-deployments@v9 + with: + switches: -avzR + path: nginx.conf,compose.yaml,deploy/htpasswd + 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 }} + + # 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. + - name: Test new config + 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 /opt/stacks/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 + + # Apply + verify (D4): recreate is the same command the Dockge deploy + # button runs. 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 + with: + host: ${{ secrets.DEPLOY_HOST }} + port: ${{ secrets.DEPLOY_SSH_PORT }} + username: ${{ secrets.DEPLOY_USER }} + key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }} + script: | + cd /opt/stacks/dong-site + docker compose up -d --force-recreate dong-site + sleep 2 + if ! docker exec dong-site wget -q -O /dev/null http://127.0.0.1/; then + docker logs --tail 50 dong-site + exit 1 + fi + docker exec dong-site nginx -t diff --git a/.gitea/workflows/deploy.yml b/.gitea/workflows/deploy.yml index 936ca29..7814157 100644 --- a/.gitea/workflows/deploy.yml +++ b/.gitea/workflows/deploy.yml @@ -12,6 +12,12 @@ concurrency: jobs: build: runs-on: ubuntu-latest + # Site identity (spec-v4-deploy-infra D10/D12): 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. + env: + SITE_URL: ${{ vars.SITE_URL }} + SITE_NAME: ${{ vars.SITE_NAME }} steps: - uses: actions/checkout@v7 - uses: pnpm/setup@v3 @@ -21,7 +27,7 @@ jobs: runtime: node@24 - run: pnpm tsx scripts/validate-content.ts - run: pnpm build - - uses: actions/upload-artifact@v4 + - uses: actions/upload-artifact@v7 with: name: static-site path: dist/ @@ -30,6 +36,9 @@ jobs: generate-resume: runs-on: ubuntu-latest needs: build + env: + SITE_URL: ${{ vars.SITE_URL }} + SITE_NAME: ${{ vars.SITE_NAME }} steps: - uses: actions/checkout@v7 - uses: pnpm/setup@v3 diff --git a/.gitignore b/.gitignore index 8467113..b99b0c9 100644 --- a/.gitignore +++ b/.gitignore @@ -23,4 +23,9 @@ dist-ssr *.sln *.sw? /.junie/ -*.pdf \ No newline at end of file +*.pdf + +# 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. +.env +/secrets/ \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 2673351..4b9c901 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,12 +22,12 @@ Personal engineering portfolio — multi-page SPA built with React + TypeScript | Command | Description | |---------|-------------| | `pnpm dev` | Start dev server with HMR | -| `pnpm build` | Type-check (`tsc -b`), build for production, then generate `dist/sitemap.xml` | +| `pnpm build` | Type-check (`tsc -b`), build for production (the site-identity plugin fills `%SITE_URL%` / `%SITE_NAME%` in `index.html`), then generate `dist/sitemap.xml` + `dist/robots.txt` | | `pnpm build:resume` | Generate resume PDF (default EN) via Playwright | | `pnpm build:resume-all` | Generate bilingual resume PDFs (EN + VI) | | `pnpm lint` | Run Oxlint | | `pnpm validate:content` | Validate the content dictionaries against the structure documents and the page manifests (also run by the loader at module load) | -| `pnpm sitemap` | Regenerate `dist/sitemap.xml` on its own (also run by `pnpm build`) | +| `pnpm sitemap` | Regenerate `dist/sitemap.xml` + `dist/robots.txt` on its own (also run by `pnpm build`) | | `pnpm preview` | Preview production build locally | ## Routing @@ -81,7 +81,7 @@ Content is split once, at authoring time, into language-neutral **structure docu - `src/data/resume.ts` — resume availability, supported languages, URL generation, and `resumeQr` (the `{id, file, label}` descriptors the resume header renders as QR codes) - `src/data/navigation.ts` — `navPaths` (bar + sheet order: Home, About, Experience, Projects, Contact, Philosophy), `footerPaths` - `src/data/social.ts` — social tiles as `{id, href, external}` (github, linkedin, email, telegram); `email` is a `mailto:` link with `external: false`, so it renders no `target`/`rel` -- `src/data/palettes.ts`, `src/data/site.ts` — code config, not content: `siteUrl` (the canonical origin) and `siteName`; every absolute URL the site publishes — canonical, Open Graph, JSON-LD, `robots.txt`, `sitemap.xml` — derives from it +- `src/data/palettes.ts`, `src/data/site.ts` — code config, not content: `siteUrl` (the canonical origin) and `siteName` are read from the environment (`SITE_URL` / `SITE_NAME` — CI variables in production, the uncommitted local `.env` in development; unset → the build fails with an error naming the variable); every absolute URL the site publishes — canonical, Open Graph, JSON-LD, `robots.txt`, `sitemap.xml` — derives from it ## Live Edit Mode (`?edit`, v4) @@ -92,7 +92,7 @@ Content is split once, at authoring time, into language-neutral **structure docu - `src/components/ui/EditableText.tsx` — the site's own element (`as` = the tag or motion component it renders today) becomes the inline editor only in edit mode; commit on blur only (Vietnamese IME-safe), Esc cancels, Enter commits single-line fields, paste is plain-text, empty required values are rejected at commit; without an `EditContext` provider it renders byte-identical markup to the plain element - `src/components/layout/EditBar.tsx` — fixed save bar: per-path diff with revert and "appears on" page annotations (computed from the page manifests via `manifestsClaiming`, never from component code), conflict resolution (rebase / take-theirs / per-field keep-mine–keep-theirs), per-document save status, partial-save resume, exit confirm - Editable surface: content text inline (pencil-triggered, click never edits) **and** structure — chip-level tag editors (technologies, categories, interests, roles, keywords, tagline emphasis), ghost add/delete/move on every record surface, per-record settings popover (`featured`, project section list + type picker, `variant`, location, logo), ids auto-generated from title slugs, social links handle-only with URLs derived in the loaders. Implemented 2026-10-23 (`spec-v4-inline-editing.md` + `spec-v4-data-organization.md`); the JSON panel is deleted. UI documents stay read-only in v4. Field provenance: hovering any pencil shows `document → pointer` (`describeField()` names the per-entity file automatically); the EditBar diff line and a `validate:content` error for the same field read identically -- Dev parity: `vite.config.ts` proxies `/api/content/` to the Gitea Contents API exactly like production nginx — run `pnpm dev` with `GITEA_TOKEN` set; without it edit mode falls to the offline state (bundled content, save disabled) +- Dev parity: `vite.config.ts` builds the `/api/content/` dev proxy from the same `GITEA_CONTENTS_API` value production nginx renders — run `pnpm dev` with `GITEA_TOKEN` + `GITEA_CONTENTS_API` set (local `.env`); without them edit mode falls to the offline state (bundled content, save disabled) - Spec: `docs/design/specs/v4/spec-v4-live-edit.md` §5–§6 ## Component Structure @@ -129,7 +129,7 @@ src/ - `public/resume-logos/` — official company logo SVGs (Lazada, SAP from Wikimedia Commons), embedded in the resume timeline via `ExperienceEntry.logo` - `public/resume-qr/` — owner-supplied QR images (`telegram.jpg`, `zalo.jpg`) embedded in the resume header via `resumeQr` in `src/data/resume.ts`; committed like the other resume assets, so CI renders the QR block too — a missing file prints a warning and that QR is skipped - `public/profile-photo.webp` — profile photo -- `public/robots.txt` — allow-all crawler rules plus the `Sitemap:` pointer to the canonical origin +- `robots.txt` is generated, not committed: `scripts/generate-sitemap.ts` writes `dist/robots.txt` (allow-all + the `Sitemap:` pointer) from the same `SITE_URL` the sitemap uses — no `public/robots.txt` exists anymore ## Scripts @@ -138,17 +138,19 @@ src/ ## Deployment -- Deployment is triggered automatically by gitea workflow `.gitea/workflows/deploy.yml` +- Site deployment is triggered automatically by gitea workflow `.gitea/workflows/deploy.yml` (push to `master`); infra redeployment by `.gitea/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`) +- Site identity is deployment-time configuration, not a repo literal: `SITE_URL` / `SITE_NAME` are Gitea Actions **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 - 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 `/opt/stacks/dong-site/dist/` -- `nginx.conf` — production Nginx SPA routing + caching config + the `/api/content/` location: auth_basic (`deploy/htpasswd`) in front of a proxied Gitea Contents API whose write token comes from the `GITEA_TOKEN` environment (envsubst at container start; the token never enters the SPA bundle) -- `docker-compose.yaml` — Docker service for local nginx deployment; mounts the nginx template + `deploy/htpasswd`, passes `GITEA_TOKEN` through +- `nginx.conf` — production Nginx SPA routing + caching config + the `/api/content/` location: auth_basic (`deploy/htpasswd`) in front of a proxied Gitea Contents API; the upstream URL and the write token are `${GITEA_CONTENTS_API}` / `${GITEA_TOKEN}` substituted by the image's envsubst step at container start — the token and the Gitea host never enter the SPA bundle or the repository +- `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 `GITEA_TOKEN=` / `GITEA_CONTENTS_API=`, chmod 600), sourced by an entrypoint override 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`. Repo side implemented 2026-10-23; owner-side setup (Gitea Actions variables, stack `secrets/site_config`) and the first verified run are pending ``` .gitea/ └── workflows/ - └── deploy.yml + ├── deploy.yml + └── deploy-infra.yml nginx.conf -docker-compose.yaml +compose.yaml ``` ## CSS Architecture @@ -191,7 +193,7 @@ All specification documents are in `docs/design/`: | `specs/ui/spec-ui-*.md` | UI specs per section (hero, about, expertise, etc.) | | `specs/v2/spec-v2-*.md` | v2 feature specs (resume, seo, blog, analytics, testing, cicd) | | `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 | +| `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 | Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope. diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 0000000..11acc1a --- /dev/null +++ b/compose.yaml @@ -0,0 +1,36 @@ +# Repo-as-source-of-truth copy (spec-v4-deploy-infra 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 + +networks: + docker-network: + external: true diff --git a/deploy/htpasswd b/deploy/htpasswd index 853dfac..10cf298 100644 --- a/deploy/htpasswd +++ b/deploy/htpasswd @@ -1 +1 @@ -editor:$6$ZLNQoSEIIH8uSXd6$mSxe2JJETZV30nt/Gm..mS4h3VAIBuWdfdqmaFmPknyXpwiKEQ0WR8HZihgTDkDp7hmj5oRqLS2Vnn.e9bBsx0 +editor:$6$r8s2CI52cy1CMFfV$QeLOi/VWtifP.05NLZlUdbb5GP.FahiHBKYD4LKgOZGXLmEMWq1ODfTrLfpheCt0Rvwctp43h.SyirYFj23ll0 \ No newline at end of file diff --git a/docker-compose.yaml b/docker-compose.yaml deleted file mode 100644 index 3a5694a..0000000 --- a/docker-compose.yaml +++ /dev/null @@ -1,23 +0,0 @@ -services: - dong-site: - image: nginx:alpine - container_name: dong-site - restart: unless-stopped - environment: - # The write token for the /api/content/ proxy (spec-v4 §6.2). Set it in - # the local .env; NGINX_ENVSUBST_FILTER restricts the template - # substitution to this variable only, so $uri/$host stay nginx runtime - # variables. - GITEA_TOKEN: ${GITEA_TOKEN} - NGINX_ENVSUBST_FILTER: GITEA_TOKEN - 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 GITEA_TOKEN filled in. - - ./nginx.conf:/etc/nginx/templates/default.conf.template:ro - - ./deploy/htpasswd:/etc/nginx/htpasswd:ro - networks: - - docker-network -networks: - docker-network: - external: true \ 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 new file mode 100644 index 0000000..44dbd4c --- /dev/null +++ b/docs/design/specs/v4/spec-v4-deploy-infra.md @@ -0,0 +1,174 @@ +# 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.yml` ships `dist/` by rsync to `/opt/stacks/dong-site/dist/` on the VPS. The live container `dong-site` (compose at `/opt/stacks/dong-site/compose.yaml`) mounts `./dist`, `./nginx.conf` as 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/stacks` confirmed — 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 runs `docker compose` in 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/htpasswd` are 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_TOKEN` lives only in `/opt/stacks/dong-site/.env` on the VPS; `NGINX_ENVSUBST_FILTER=GITEA_TOKEN` restricts 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. + +- `rsync` writes the stack's own files in Dockge's stack directory — the same files the Dockge UI opens. +- `docker compose up -d --force-recreate` in 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 `