mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
GitHub becomes the primary repository host; the site keeps its VPS + nginx + Dockge host, the three-job pipeline and the same concurrency, so what moves is the CI host and the write-path target. .github/workflows/{deploy,deploy-infra}.yml are ports of the Gitea files with permissions: contents: read on every job. .gitea/workflows/ stays until the first green GitHub run (D9); its infra test step carries the new template variable names because the template it validates is the one this repository now ships.
The write-path values are renamed GITEA_TOKEN / GITEA_CONTENTS_API -> CONTENT_API_TOKEN / CONTENT_API_BASE and the upstream header becomes Bearer — in nginx.conf, in the compose envsubst filter and in the dev proxy, so dev and production send the identical header (D4). draft.ts learns GitHub's answer to a stale blob sha (409) while keeping the 422 "does not match" and 412 legs; smoke-draft.ts check 14 drives a stubbed proxy that answers 409 with GitHub's body and asserts the conflict refreshes the base, keeps the draft and never stops the save sequence.
Both workflows read the stack directory and the compose service / container name from the STACK_DIR and CONTAINER_NAME repository variables instead of hard-coding them, and each job refuses a missing, relative, trailing-slash or compose-disagreeing value in its first step, before any artifact download or rsync reaches the VPS (D15).
Verified: tsc -b and oxlint pass with no new warnings; validate:content, smoke-draft (14 checks) and smoke-generated-ids (7 checks) pass; both workflows parse, every run/script block passes bash -n with the variables substituted, and the guard refuses every bad value against the real compose.yaml. Owner-side variables, secrets, the write token and the VPS config rewrite stay open in spec-v6 §6.
158 lines
9.5 KiB
Markdown
158 lines
9.5 KiB
Markdown
# 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`](docs/design/spec.md) and [`docs/design/specs/`](docs/design/).
|
|
|
|
## 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
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
### 2. Environment
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
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 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 (GitHub Actions)
|
|
|
|
### Pipelines
|
|
|
|
| Workflow | Trigger | What it does |
|
|
|---|---|---|
|
|
| [`.github/workflows/deploy.yml`](.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`](.github/workflows/deploy-infra.yml) | push to `master` touching `nginx.conf` / `compose.yaml` / `deploy/htpasswd`, or manual dispatch | rsyncs exactly those three files to the stack directory, 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 three infra files.
|
|
|
|
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):
|
|
|
|
```powershell
|
|
ssh-keygen -t ed25519 -C "gitea-deploy" -f "$HOME\.ssh\gitea_deploy_key"
|
|
```
|
|
|
|
On the VPS:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```powershell
|
|
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 |
|
|
|
|
**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` + `deploy/htpasswd`, committed as hashes). The browser prompts once per session.
|
|
|
|
### 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.
|