mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
164 lines
11 KiB
Markdown
164 lines
11 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
|
|
# 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`](.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`, 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):
|
|
|
|
```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 |
|
|
| `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.
|