dong.nguyen e02fe19bbe video: point explanations at the diagram, extend scenes for readable dwell
Explanations become Callout chips (kit.tsx): a leader line draws from the
target element, the chip fades in only after the line completes, timed to
the scene beat. The fixed bottom bullet row in SceneChrome is deleted.
Leaders stop at element outer edges; chips sit fully outside each visual
group (Pipeline push callout narrowed clear of the group box).

Timeline 62s -> 81s (2425 frames): every callout holds >=150 frames after
it appears; scene beats unchanged, hold time added at each scene end.
.vtt cue times, EN+VI chapter times, README take minimums (24s/17s) and
spec-v7 scene table, no-overlap and dwell rules follow the new boundaries.
Re-rendered public/media/how-it-works.mp4.
2026-10-29 00:38:07 +07:00
2026-10-04 09:34:55 +07:00
2026-10-26 21:46:13 +07:00
2026-10-04 09:34:55 +07:00

Portfolio

Personal engineering portfolio — a bilingual (EN/VI) single-page app built with React 19, TypeScript and Vite. All content is data-driven: language-neutral structure documents in src/data/*.json, per-language text dictionaries in src/i18n/locales/, joined at load. An authenticated edit mode (?edit) edits the live site in place and writes the documents back to the git repository through a Contents API proxy; pushing to master deploys through GitHub Actions CI.

Product and feature specifications: docs/design/spec.md and docs/design/specs/.

Requirements

Tool Version Needed for
Node.js 24 everything (CI runs Node 24)
pnpm 12 everything (corepack enable or npm i -g pnpm)
Playwright Chromium — resume PDF generation only (npx playwright install chromium)
Docker — optional: run the production nginx stack locally

Local setup

1. Install

pnpm install

2. Environment

cp .env.example .env

.env is gitignored; fill it in:

Variable Required Purpose
SITE_URL for pnpm build canonical origin — every published absolute URL (meta tags, sitemap, robots, resume links) derives from it. pnpm dev falls back to http://localhost:5173 without it
SITE_NAME for pnpm build page <title> and Open Graph / Twitter meta. Dev fallback: Portfolio (dev)
CONTENT_API_BASE optional full Contents-API base URL (https://api.github.com/repos/<owner>/<repo>/contents/). Enables the dev /api/content/ proxy — the exact mirror of the production nginx location
CONTENT_API_TOKEN optional access token the dev proxy attaches to write requests (Authorization: Bearer …, the same form the production proxy sends)

Without the two CONTENT_API_* values everything still runs; edit mode is offline (bundled content, save disabled).

3. Run

pnpm dev        # http://localhost:5173 with HMR

Edit mode: open any route with ?edit (or ?edit=<branch> to read and write a specific branch; bare ?edit resumes the last branch, default master). In dev the proxy uses CONTENT_API_TOKEN directly — no login prompt.

4. Commands

Command Description
pnpm dev dev server with HMR
pnpm build tsc -b + production build (injects SITE_URL / SITE_NAME into index.html), then generates dist/sitemap.xml + dist/robots.txt
pnpm preview preview the production build locally
pnpm lint Oxlint
pnpm validate:content validate the content dictionaries against the structure documents and page manifests (also runs at module load in the browser)
pnpm build:resume generate the resume PDF (EN)
pnpm build:resume-all generate both resume PDFs (EN + VI)
pnpm build:resume-preview render the resume HTML preview without writing a PDF
pnpm sitemap regenerate dist/sitemap.xml + dist/robots.txt on its own
pnpm generate:ids regenerate src/types/content-ids.ts from src/data/*.json (also runs as predev / prebuild / prepare)

Content validation is a hard gate: a malformed document fails pnpm build, CI, and the browser load — never a silent half-render.

Content ids are generated the same way: src/types/content-ids.ts is written from the structure documents and is gitignored, so adding or deleting a content record touches JSON only — never a TypeScript file. A fresh checkout gets it from pnpm install; pnpm generate:ids regenerates it on its own.

Gotcha: while a generated dist/resume*.pdf is open in a viewer, pnpm build:resume-all fails with EBUSY and pnpm build fails too (vite emptyDir → EPERM). Close the viewer first.

5. Run the production stack locally (optional)

To exercise the real serving path — nginx SPA routing, caching, the authenticated /api/content/ proxy:

pnpm build
mkdir -p secrets
# secrets/site_config — exactly two lines, chmod 600, never committed:
#   CONTENT_API_TOKEN=<token>
#   CONTENT_API_BASE=https://api.github.com/repos/<owner>/<repo>/contents/
chmod 600 secrets/site_config
# deploy/htpasswd — the Basic-auth file is not committed (spec-v6 D16), but the
# compose mount needs it locally. Generate one line with any htpasswd tool
# (e.g. `docker run --rm httpd:2 htpasswd -nbB editor '<pass>'`) and save it:
mkdir -p deploy
docker run --rm httpd:2 htpasswd -nbB editor '<pass>' > deploy/htpasswd
docker network create docker-network   # once; compose.yaml joins it
docker compose up -d

compose.yaml defines no published port (the VPS container is reached through its own fronting); compose.override.yaml — auto-merged by docker compose, never shipped by the pipeline — publishes the container on the local loopback. Open http://127.0.0.1:8081/ in a browser; ?edit there asks for HTTP Basic credentials against the local deploy/htpasswd you just created (the production copy is written by the infra pipeline from the HTPASSWD_CONTENT secret). If 8081 is taken on your machine, change the host port in compose.override.yaml. Stop the stack with docker compose stop.

Production deployment (GitHub Actions)

Pipelines

Workflow Trigger What it does
.github/workflows/deploy.yml push to master build (validate content → pnpm build) → generate-resume (EN + VI PDFs) → deploy rsyncs dist/ (PDFs included) to ${STACK_DIR}/dist/ on the VPS
.github/workflows/deploy-infra.yml push to master touching nginx.conf / compose.yaml, or manual dispatch rsyncs exactly those two files to the stack directory, writes deploy/htpasswd there from the HTPASSWD_CONTENT repository secret, tests the new config in a throwaway container (nginx -t), then docker compose up -d --force-recreate + health probe

Only master deploys. A content commit never restarts nginx; an infra commit never rebuilds the site. The VPS stack is managed by Dockge (/opt/stacks/dong-site); the repository is the single source of truth for the two infra files — the Basic-auth file is the exception: it lives only on the server, written from the HTPASSWD_CONTENT secret (spec-v6 D16).

The repository is GitHub-primary and public; the pipelines run on GitHub-hosted runners (free for public repositories). master carries no branch protection on purpose: edit mode writes straight to it, and the validation step in build is what keeps a malformed content commit from deploying. .gitea/workflows/ is kept only until the first green GitHub run is verified, then deleted (spec-v6 D9).

One-time setup

1. GitHub repository variables — Settings → Secrets and variables → Actions → Variables (repository level):

Name Value
SITE_URL the canonical origin, e.g. https://cv.example.com (no trailing slash)
SITE_NAME the page title string
STACK_DIR the absolute stack directory on the VPS, e.g. /opt/stacks/dong-site — no trailing slash
CONTAINER_NAME the compose service / container name, e.g. dong-site — it must match compose.yaml, and the infra job checks that it does

These are public values, so they live in the vars. context, not secrets (spec-v4-deploy-infra D10/D12, spec-v6 D3 and D15). A production build without SITE_URL / SITE_NAME fails with an error naming the variable; both deploy jobs refuse a missing, relative or trailing-slash STACK_DIR, and the infra job refuses a CONTAINER_NAME that is not the service compose.yaml declares. Every check runs as the job's first step, before anything reaches the VPS.

2. Deployment SSH access — a deploy user on the VPS plus an SSH key.

On Windows (PowerShell):

ssh-keygen -t ed25519 -C "gitea-deploy" -f "$HOME\.ssh\gitea_deploy_key"

On the VPS:

sudo adduser gitea-deployer
sudo usermod -aG docker gitea-deployer
sudo -u gitea-deployer docker ps          # verify docker access
sudo install -d -m 700 -o gitea-deployer -g gitea-deployer /home/gitea-deployer/.ssh

No ssh-copy-id on Windows, so copy the public key manually:

type $HOME\.ssh\gitea_deploy_key.pub | ssh gitea-deployer@vps.example.com -p 2222 "cat >> ~/.ssh/authorized_keys"
ssh gitea-deployer@vps.example.com -p 2222 -i "$HOME\.ssh\gitea_deploy_key" -o IdentitiesOnly=yes   # test
Get-Content -Raw "$HOME\.ssh\gitea_deploy_key"   # this content becomes DEPLOY_SSH_PRIVATE_KEY

Then create GitHub Actions secrets — Settings → Secrets and variables → Actions → Secrets:

Secret Value
DEPLOY_HOST VPS hostname / IP
DEPLOY_SSH_PORT SSH port
DEPLOY_USER gitea-deployer
DEPLOY_SSH_PRIVATE_KEY the private key content
HTPASSWD_CONTENT the one htpasswd line — output of htpasswd -nbB <user> '<pass>' (user + bcrypt hash). The infra job writes it to ${STACK_DIR}/deploy/htpasswd (chmod 644 — the nginx worker, uid 101, opens the file per request; see spec-v6 D16 §7.1 follow-up); the credential never appears in the repository

3. VPS stack config — in the stack directory /opt/stacks/dong-site/, create secrets/site_config (chmod 600, exactly the two KEY=value lines shown in step 5 above). The token should be a dedicated GitHub fine-grained PAT (site-contents-write: this repository only, Contents: Read and write, with an expiry). The pipeline never rsyncs secrets/, so it can never touch this file; it never appears in docker inspect or the Dockge env tab.

4. Edit-mode login — production /api/content/ sits behind HTTP Basic (auth_basic + the htpasswd file the infra pipeline writes from the HTPASSWD_CONTENT secret — the hash is no longer in the public repository). The browser prompts once per session. Rotating the editor password: regenerate the line (htpasswd -nbB <user> '<new-pass>'), overwrite the secret, run deploy-infra via workflow_dispatch — no commit involved.

Editing content in production

Open https://<SITE_URL>/any-route?edit (append =<branch> to target another branch — it must already exist; the edit UI never creates branches). Edits preview live; saving writes each touched document as its own commit through the proxy, and merging that branch into master deploys it via deploy.yml.

Spec status

Implemented: locale dictionaries + page manifests (spec-v4-data-organization.md), inline editing on every record surface (spec-v4-inline-editing.md), live edit + save pipeline (spec-v4-live-edit.md), CI pipelines + env-driven site identity (spec-v4-deploy-infra.md, rev.7), GitHub Actions CI with the GitHub-backed write path (spec-v6-github-actions.md). Remaining owner-side steps are tracked in each spec's Progress Tracking section.

S
Description
No description provided
Readme
14 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 81.8%
CSS 15.3%
HTML 2.9%