mirror of
https://github.com/tiennm99/mathmax.git
synced 2026-07-13 23:07:42 +00:00
62 lines
3.2 KiB
Markdown
62 lines
3.2 KiB
Markdown
# Runbook — MathMax
|
||
|
||
## Deployment
|
||
|
||
Production deploys from `main` via GitHub Actions (`.github/workflows/deploy.yml`).
|
||
|
||
- Live URL: `https://tiennm99.github.io/mathmax/`
|
||
- Build: `npm run build` (SvelteKit static, output to `build/`)
|
||
- Deploy mechanism: `actions/upload-pages-artifact@v3` + `actions/deploy-pages@v4`
|
||
- Concurrency: `pages-deploy` group, cancel-in-progress disabled (so a force-pushed retry doesn't abort an in-flight rollback)
|
||
|
||
## Rollback
|
||
|
||
GitHub Pages keeps the last successful deployment. To roll back:
|
||
|
||
1. Find the offending commit on `main`: `git log --oneline main`
|
||
2. Revert it: `git revert <sha>` and push to `main`
|
||
3. The next workflow run rebuilds and re-deploys the prior good state
|
||
4. Verify the live site
|
||
|
||
If the workflow itself is broken (e.g., bad `deploy.yml` change), use the GitHub UI to re-run a previous successful deployment from the **Deployments** tab.
|
||
|
||
## CI
|
||
|
||
- `.github/workflows/ci.yml` runs build on every PR and push to `main`. Build failure on `main` blocks the deploy job.
|
||
- Local equivalent: `npm install && npm run build`
|
||
|
||
## Domain migration trigger
|
||
|
||
Per plan, buy a `.vn` / `.com.vn` domain only when ANY of:
|
||
|
||
1. **500 unique sessions** in any rolling 30-day window post-launch, OR
|
||
2. **1 organic teacher share** (Facebook group, Zalo, or school chat — verified, not founder-initiated), OR
|
||
3. **≥5 modules shipped** (signals content sustainability and amortizes the domain cost)
|
||
|
||
If none hit within 90 days of soft launch, stay on `tiennm99.github.io/mathmax/`.
|
||
|
||
When the trigger fires:
|
||
|
||
1. Register the domain (VN registration: passport scan + address proof + MIC filing, 7–14 days)
|
||
2. Add `CNAME` file at repo root with the new domain (e.g. `mathmax.vn`)
|
||
3. Configure custom domain in GitHub Pages settings (Settings → Pages → Custom domain)
|
||
4. Update `svelte.config.js`: change `paths.base` from `/mathmax` to `/`, update any hardcoded references. Or update the workflow `env:` block.
|
||
5. Update OpenGraph + canonical URLs (handled automatically once `svelte.config.js` reflects the new domain)
|
||
6. Wait 24h, then update sitemap submission in Google Search Console
|
||
7. Set up 301 redirects (GitHub Pages handles this automatically once the custom domain is the primary)
|
||
|
||
## Things to NOT do
|
||
|
||
- Never `git push --force` to `main`.
|
||
- Never edit `VERSION` or `package.json.version` independently — they must agree.
|
||
- Never change `svelte.config.js` `paths.base` without simultaneously updating the deploy workflow `env:` and any hardcoded internal links.
|
||
- Never run `npm install` in CI without committing the resulting `package-lock.json` locally first.
|
||
|
||
## Initial CI note
|
||
|
||
Initial CI uses `npm install` (no lockfile committed yet). After first successful run, user commits `package-lock.json` locally and we switch CI to `npm ci` in a follow-up PR.
|
||
|
||
## Bundle notes
|
||
|
||
- **KaTeX** (`katex@^0.16`) is loaded site-wide via `import 'katex/dist/katex.min.css'` in `+layout.svelte`. CSS + woff2 fonts add ~280KB total to the static asset payload. Math is server-rendered via `katex.renderToString` (in `src/lib/components/tex.svelte`), so KaTeX **JavaScript runs only at build time** — the runtime cost is the CSS + fonts, not the JS module. If Lighthouse perf drops below 90 after content growth, consider scoping CSS imports per-route.
|