mirror of
https://github.com/dong-nz/cv.git
synced 2026-11-22 16:10:40 +07:00
docs(readme): local setup + production deploy via Gitea CI; refresh live-edit spec status
README replaces the Vite starter template: requirements, .env variables (SITE_URL/SITE_NAME build identity, GITEA_* edit path), all scripts with validation gate and PDF-lock gotcha, optional local nginx stack, deploy.yml/deploy-infra.yml pipeline table, one-time Gitea setup (Actions variables SITE_URL/SITE_NAME per deploy-infra rev.7, DEPLOY_* SSH secrets with the Windows key procedure, stack secrets/site_config, htpasswd edit login). spec-v4-live-edit.md: status line refreshed (content docs on master, nginx step automated repo-side, remaining owner-side items), date typo 2022->2026, section 6.3 marked superseded by deploy-infra.
This commit is contained in:
1 parent
5e9c76c62b
commit
85f9e3429c
2 files changed
+119
-41
No files matched your search
@@ -1,72 +1,150 @@
|
||||
# React + TypeScript + Vite
|
||||
# Portfolio
|
||||
|
||||
This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
|
||||
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 Gitea Contents API proxy; pushing to `master` deploys through Gitea Actions CI.
|
||||
|
||||
Currently, two official plugins are available:
|
||||
Product and feature specifications: [`docs/design/spec.md`](docs/design/spec.md) and [`docs/design/specs/`](docs/design/).
|
||||
|
||||
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
|
||||
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
|
||||
## Requirements
|
||||
|
||||
## React Compiler
|
||||
| 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 |
|
||||
|
||||
The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
|
||||
## Local setup
|
||||
|
||||
## Expanding the Oxlint configuration
|
||||
### 1. Install
|
||||
|
||||
If you are developing a production application, we recommend enabling type-aware lint rules by installing `oxlint-tsgolint` and editing `.oxlintrc.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "./node_modules/oxlint/configuration_schema.json",
|
||||
"plugins": ["react", "typescript", "oxc"],
|
||||
"options": {
|
||||
"typeAware": true
|
||||
},
|
||||
"rules": {
|
||||
"react/rules-of-hooks": "error",
|
||||
"react/only-export-components": ["warn", { "allowConstantExport": true }]
|
||||
}
|
||||
}
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
See the [Oxlint rules documentation](https://oxc.rs/docs/guide/usage/linter/rules) for the full list of rules and categories.
|
||||
|
||||
## Deployment On Windows
|
||||
### 2. Environment
|
||||
|
||||
Open PowerShell on your Windows computer.
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Create an ssh key for gitea deployment:
|
||||
`.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)` |
|
||||
| `GITEA_CONTENTS_API` | optional | full Gitea Contents-API base URL (`…/api/v1/repos/<owner>/<repo>/contents/`). Enables the dev `/api/content/` proxy — the exact mirror of the production nginx location |
|
||||
| `GITEA_TOKEN` | optional | Gitea access token the dev proxy attaches to write requests |
|
||||
|
||||
Without the two `GITEA_*` 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 `GITEA_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 |
|
||||
|
||||
Content validation is a hard gate: a malformed document fails `pnpm build`, CI, and the browser load — never a silent half-render.
|
||||
|
||||
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:
|
||||
# GITEA_TOKEN=<token>
|
||||
# GITEA_CONTENTS_API=https://<gitea-host>/api/v1/repos/<owner>/<repo>/contents/
|
||||
chmod 600 secrets/site_config
|
||||
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`.
|
||||
|
||||
## Production deployment (Gitea CI)
|
||||
|
||||
### Pipelines
|
||||
|
||||
| Workflow | Trigger | What it does |
|
||||
|---|---|---|
|
||||
| [`.gitea/workflows/deploy.yml`](.gitea/workflows/deploy.yml) | push to `master` | `build` (validate content → `pnpm build`) → `generate-resume` (EN + VI PDFs) → `deploy` rsyncs `dist/` (PDFs included) to `/opt/stacks/dong-site/dist/` on the VPS |
|
||||
| [`.gitea/workflows/deploy-infra.yml`](.gitea/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.
|
||||
|
||||
### One-time setup
|
||||
|
||||
**1. Gitea Actions variables** — Settings → 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 |
|
||||
|
||||
These are public values, so they live in the `vars.` context, not secrets (spec-v4-deploy-infra D10/D12, rev.7). A production build without them fails with an error naming the variable.
|
||||
|
||||
**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"
|
||||
```
|
||||
|
||||
In a VPS server, create the deployment user
|
||||
On the VPS:
|
||||
|
||||
```bash
|
||||
sudo adduser gitea-deployer
|
||||
sudo usermod -aG docker gitea-deployer
|
||||
# test user can run docker
|
||||
sudo -u gitea-deployer docker ps
|
||||
sudo -u gitea-deployer docker ps # verify docker access
|
||||
sudo install -d -m 700 -o gitea-deployer -g gitea-deployer /home/gitea-deployer/.ssh
|
||||
```
|
||||
|
||||
Because no ssh-copy-id is available on Windows, you need to copy the public key to the server manually.
|
||||
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
|
||||
```
|
||||
|
||||
Test ssh connected with a private key
|
||||
Then create Gitea Actions **secrets** — Settings → Actions → Secrets:
|
||||
|
||||
```powershell
|
||||
ssh gitea-deployer@vps.example.com -p 2222 -i "$HOME\.ssh\gitea_deploy_key" -o IdentitiesOnly=yes
|
||||
```
|
||||
| Secret | Value |
|
||||
|---|---|
|
||||
| `DEPLOY_HOST` | VPS hostname / IP |
|
||||
| `DEPLOY_SSH_PORT` | SSH port |
|
||||
| `DEPLOY_USER` | `gitea-deployer` |
|
||||
| `DEPLOY_SSH_PRIVATE_KEY` | the private key content |
|
||||
|
||||
Get content of private key
|
||||
**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 Gitea **restricted access token** (`site-contents-write`: this repository only, Contents 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.
|
||||
|
||||
```powershell
|
||||
Get-Content -Raw "$HOME\.ssh\gitea_deploy_key"
|
||||
```
|
||||
**4. Edit-mode login** — production `/api/content/` sits behind HTTP Basic (`auth_basic` + `deploy/htpasswd`, committed as hashes). The browser prompts once per session.
|
||||
|
||||
In Gitea, create action secrets `DEPLOY_HOST`, `DEPLOY_SSH_PORT`, `DEPLOY_USER`, `DEPLOY_SSH_PRIVATE_KEY` for deployment.
|
||||
### 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 (v4)
|
||||
|
||||
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). Remaining owner-side steps are tracked in each spec's Progress Tracking section.
|
||||
@@ -1,7 +1,7 @@
|
||||
# Specification — v4 Live Edit (i18n Overlay + Git-backed Content Editing)
|
||||
|
||||
> **Parent:** `spec.md` (product vision), `specs/v3/spec-v3-i18n.md` (supersedes its Phase 2)
|
||||
> **Status:** rev.4 — Phases 1–3 implemented 2026-10-22 (see §12 rows 3–15). Remaining: the production nginx step (§6.3), pushing the content documents to the repository, `GITEA_TOKEN`, and the owner's browser walkthrough.
|
||||
> **Status:** rev.4 — Phases 1–3 implemented 2026-10-22 (see §12 rows 3–15). Remaining (2026-10-23): the owner-side infra setup + first verified run per `spec-v4-deploy-infra.md` rev.7 (Gitea Actions variables `SITE_URL`/`SITE_NAME`, stack `secrets/site_config` with the restricted `GITEA_TOKEN`), and the owner's browser walkthrough. Content documents are pushed and on `master` (§12 row 11); the production nginx step (§6.3) is automated repo-side by `deploy-infra.yml`.
|
||||
|
||||
---
|
||||
|
||||
@@ -444,7 +444,7 @@ location /api/content/ {
|
||||
|
||||
### 6.3 Production deployment of the proxy (operational step — was missing in rev.1)
|
||||
|
||||
`deploy.yml` rsyncs `dist/` only — `nginx.conf` is **not** deployed by the pipeline. Phase 2 therefore includes an explicit one-time server step: update the stack's nginx config + `htpasswd`, set `GITEA_TOKEN` in the stack environment, and reload the nginx container on `/opt/stacks/dong-site`. Recorded as Phase 2 step 0 in §7 and §12.
|
||||
`deploy.yml` rsyncs `dist/` only — `nginx.conf` is **not** deployed by the pipeline. Phase 2 therefore includes an explicit one-time server step: update the stack's nginx config + `htpasswd`, set `GITEA_TOKEN` in the stack environment, and reload the nginx container on `/opt/stacks/dong-site`. Recorded as Phase 2 step 0 in §7 and §12. **Superseded 2026-10-23 by `spec-v4-deploy-infra.md`:** `deploy-infra.yml` ships `nginx.conf` / `compose.yaml` / `deploy/htpasswd` and redeploys the container automatically; `GITEA_TOKEN` now lives in the stack's `secrets/site_config` (D13), not the stack environment.
|
||||
|
||||
### 6.4 Authorization tiers (future-ready, no custom RBAC)
|
||||
|
||||
|
||||
Reference in new issue
Block a user