From cf216e5962c861d50462cf8bb98a26ea40267310 Mon Sep 17 00:00:00 2001 From: "dong.nguyen" Date: Sat, 24 Oct 2026 00:44:20 +0700 Subject: [PATCH] fix(infra): working container entrypoint; add local-only ports override MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - compose.yaml: set -a before sourcing (sourced assignments were shell-only, envsubst saw nothing) + inline nginx command (a compose entrypoint override drops the image CMD; empty $@ exit-0 restart-looped locally and on the VPS) - compose.override.yaml: local-only auto-merged override publishing 127.0.0.1:8081 (8080 taken on the dev machine); never shipped by the pipeline - verified locally end-to-end: stack Up, probe 200, rendered default.conf carries real values, nginx -t OK; built site + 401-protected /api/content/ served through the published port - docs: spec D13/§4.1 entrypoint corrected, §6 port-exposure open question + docker inspect check, rows 4/9; README local-stack section; AGENTS.md inventory --- AGENTS.md | 4 +++- README.md | 2 +- compose.override.yaml | 9 +++++++++ compose.yaml | 11 +++++++---- docs/design/specs/v4/spec-v4-deploy-infra.md | 16 +++++++++------- 5 files changed, 29 insertions(+), 13 deletions(-) create mode 100644 compose.override.yaml diff --git a/AGENTS.md b/AGENTS.md index 4b9c901..db58565 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -142,7 +142,8 @@ src/ - 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; 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 +- `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 (`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` +- `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 ``` .gitea/ @@ -151,6 +152,7 @@ src/ └── deploy-infra.yml nginx.conf compose.yaml +compose.override.yaml ``` ## CSS Architecture diff --git a/README.md b/README.md index 6ca6109..e691d89 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ docker network create docker-network # once; compose.yaml joins it docker compose up -d ``` -The site serves at `http://127.0.0.1/`; `?edit` there asks for HTTP Basic credentials from `deploy/htpasswd`. +`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`. ## Production deployment (Gitea CI) diff --git a/compose.override.yaml b/compose.override.yaml new file mode 100644 index 0000000..a76a6a9 --- /dev/null +++ b/compose.override.yaml @@ -0,0 +1,9 @@ +# 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 +# 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: + dong-site: + ports: + - "127.0.0.1:8081:80" diff --git a/compose.yaml b/compose.yaml index 2e72aa0..11d517b 100644 --- a/compose.yaml +++ b/compose.yaml @@ -8,10 +8,13 @@ services: 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 \"$$@\""] + # set -a is REQUIRED: a sourced assignment is a shell variable, not an env var — + # without export the entrypoint child (and its envsubst step) sees nothing and + # the template renders unsubstituted (reproduced locally 2026-10-23: unknown + # "gitea_contents_api" variable). The nginx command is inline: a compose + # entrypoint override does NOT keep the image's CMD (CMD=[]) — an empty "$@" + # makes the exec a no-op, exit 0, restart loop. + entrypoint: ["sh", "-c", "set -a; . /run/secrets/site_config; exec /docker-entrypoint.sh nginx -g 'daemon off;'"] environment: # Names the variables the template renderer substitutes. The filter is a # REGEX the official entrypoint matches against each variable name diff --git a/docs/design/specs/v4/spec-v4-deploy-infra.md b/docs/design/specs/v4/spec-v4-deploy-infra.md index eeff489..8f0dc49 100644 --- a/docs/design/specs/v4/spec-v4-deploy-infra.md +++ b/docs/design/specs/v4/spec-v4-deploy-infra.md @@ -34,7 +34,7 @@ Dockge is a UI over compose files on disk: it reads the stack's `compose.yaml` f | 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. [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 ``/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. | +| 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", "set -a; . /run/secrets/site_config; exec /docker-entrypoint.sh nginx -g 'daemon off;'"]` — `set -a` is required (a sourced assignment is a shell variable; without export the entrypoint child and its envsubst step see nothing), and the nginx command is written inline because a compose entrypoint override does not keep the image's CMD (`CMD=[]`; an empty `$@` makes the exec a no-op → exit 0 → restart loop). Both proven by a local run 2026-10-23; the original `$$@` form and its rationale were wrong. 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. @@ -94,10 +94,11 @@ services: 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 \"$$@\""] + # set -a exports the sourced assignments (a sourced `KEY=value` is a shell + # variable only — the entrypoint child and its envsubst step would otherwise + # see nothing); the nginx command is inline because a compose entrypoint + # override drops the image's CMD (CMD=[]) — an empty "$@" exits 0, restart loop. + entrypoint: ["sh", "-c", "set -a; . /run/secrets/site_config; exec /docker-entrypoint.sh nginx -g 'daemon off;'"] environment: # Names the variables the template renderer substitutes, so $uri/$host # stay nginx runtime variables. The filter is a REGEX matched against @@ -144,6 +145,7 @@ GITEA_CONTENTS_API=https://<gitea-host>/api/v1/repos/<owner>/<repo>/contents/ - **Paths filter support** on the act runner [INFERENCE — first run executed after a push touching the three files; confirm the trigger label in the Actions UI] — fallback in §4. - A bad `compose.yaml` pushed 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_config` does not exist in the stack directory, `docker compose up` fails 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 rsyncs `secrets/`, so the pipeline can never delete it. +- **Port exposure (open question, owner-side check):** neither the repo `compose.yaml` (old or new) nor the live manual definition was ever verified to publish a host port — the workflow's health probe runs INSIDE the container (`docker exec … wget 127.0.0.1`), so the spec never pinned how the site reaches the internet. Confirm before the first green run: `docker inspect dong-site --format '{{json .HostConfig.PortBindings}}'` on the VPS. If the live container carries a binding (e.g. `"80/tcp":[{"HostIp":"","HostPort":"80"}]`), the repo-based recreate would drop it and the site goes down externally — the binding then belongs in the stack definition (resolving the D7 nuance: publish ports are host-topology config, like the fronting TLS). If the site is fronted by another proxy container on `docker-network`, nothing changes. Local verification meanwhile: `compose.override.yaml` (auto-merged by `docker compose`, never rsynced by the pipeline) publishes `127.0.0.1:8081` — verified 2026-10-23: built site + the 401-protected `/api/content/` proxy served through the published port. ## 7. Acceptance criteria @@ -169,8 +171,8 @@ 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); 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` | +| 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`); the recreated container then restart-looped (compose entrypoint override drops the image CMD → empty `$@` → exit 0; and a sourced `KEY=value` is not exported → envsubst sees nothing). All causes fixed and **verified locally end-to-end**: the exact test-step container passes `nginx -t`, and a full local `docker compose up` brought the stack Up — probe 200, rendered `default.conf` carries the real values, `nginx -t` in-container OK. Owner-side: clean the stray `workspace/` dir, keep `deploy/htpasswd` a FILE, create `secrets/site_config` if missing — the push of the fixed `compose.yaml` auto-triggers the pipeline | | 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 | +| 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, entrypoint corrected the same day (`set -a` + inline nginx command — the `$$@` form restart-looped, proven locally; full local stack verified Up + probe 200); 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 |