mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 07:57:19 -05:00
86 lines
4.7 KiB
Markdown
86 lines
4.7 KiB
Markdown
# Website Deployment Playbook
|
|
|
|
This playbook gives end-to-end steps to push every BlackRoad website live with the correct hosting target and DNS. Follow it when preparing production cutovers or restoring broken sites.
|
|
|
|
## Scope
|
|
- `blackroad.systems` (public marketing site)
|
|
- `docs.blackroad.systems` (developer docs)
|
|
- `console.blackroad.systems` / `prism.blackroad.systems` (Prism Console frontend)
|
|
|
|
## Prerequisites
|
|
- Vercel access for web + console deployments (production projects already created or ability to create them).
|
|
- GitHub access to run Pages workflows for docs.
|
|
- Cloudflare access to manage DNS for `blackroad.systems` and related subdomains.
|
|
- Healthy Railway backends if the frontend relies on API calls (e.g., console pulling status from the core API).
|
|
|
|
## Deployment Summary (TL;DR)
|
|
| Site | Source Repo/Path | Hosting Target | Domains | Health Check |
|
|
| --- | --- | --- | --- | --- |
|
|
| Public web | `apps/web` → `BlackRoad-OS/blackroad-os-web` | Vercel project `blackroad-os-web` (prod) | `blackroad.systems`, `www.blackroad.systems` | `curl -I https://blackroad.systems` should return 200/301 |
|
|
| Docs | `codex-docs` → `BlackRoad-OS/blackroad-os-docs` | GitHub Pages via `gh-pages` branch | `docs.blackroad.systems` | `curl -I https://docs.blackroad.systems` should return 200 |
|
|
| Prism Console | `prism-console` → `BlackRoad-OS/blackroad-os-prism-console` | Vercel project `blackroad-prism-console` (prod) | `console.blackroad.systems`, alias `prism.blackroad.systems` | `curl -I https://console.blackroad.systems` should return 200 |
|
|
|
|
---
|
|
|
|
## 1) Public Web (`blackroad.systems`)
|
|
1. **Sync code**
|
|
- Ensure latest changes are in `apps/web` and mirrored to `BlackRoad-OS/blackroad-os-web` `main`.
|
|
2. **Build locally (sanity check)**
|
|
- If static: `npm ci && npm run build` inside `apps/web`.
|
|
- If Next.js: ensure `NEXT_PUBLIC_API_URL`/`NEXT_PUBLIC_APP_URL` are set in Vercel.
|
|
3. **Deploy to Vercel**
|
|
- Project: `blackroad-os-web`.
|
|
- Framework preset: Next.js or Static depending on the build.
|
|
- Environment: Production.
|
|
4. **Attach domains in Vercel**
|
|
- Add `blackroad.systems` (apex) and `www.blackroad.systems`.
|
|
- Verify Vercel shows them as “Verified”.
|
|
5. **Update Cloudflare (if needed)**
|
|
- `@` → `cname.vercel-dns.com` (proxied ✅).
|
|
- `www` → `blackroad.systems` (proxied ✅).
|
|
6. **Validate**
|
|
- `dig +short blackroad.systems` should resolve to Vercel CNAME target.
|
|
- `curl -I https://blackroad.systems` should return 200/301 and show the live site.
|
|
|
|
## 2) Docs (`docs.blackroad.systems`)
|
|
1. **Build locally**
|
|
- `pip install -r codex-docs/requirements.txt` (or `pip install mkdocs mkdocs-material`).
|
|
- `cd codex-docs && mkdocs build --strict` to ensure no broken links.
|
|
2. **Publish via GitHub Actions**
|
|
- Verify the Pages workflow builds `codex-docs` and publishes `./codex-docs/site` to `gh-pages`.
|
|
- Confirm `gh-pages` branch exists and updates on pushes to `main`.
|
|
3. **Configure Pages**
|
|
- Repository: `BlackRoad-OS/blackroad-os-docs` → Settings → Pages → Source: `gh-pages`.
|
|
- Custom domain: `docs.blackroad.systems`, enforce HTTPS.
|
|
4. **Update Cloudflare (if needed)**
|
|
- `docs` → `blackboxprogramming.github.io` (proxied ✅).
|
|
5. **Validate**
|
|
- `dig +short docs.blackroad.systems` should resolve to GitHub Pages.
|
|
- `curl -I https://docs.blackroad.systems` should return 200 and serve the docs homepage.
|
|
|
|
## 3) Prism Console (`console.blackroad.systems` / `prism.blackroad.systems`)
|
|
1. **Sync code**
|
|
- Ensure latest changes in `prism-console` mirror to `BlackRoad-OS/blackroad-os-prism-console` `main`.
|
|
2. **Deploy to Vercel**
|
|
- Project: `blackroad-prism-console` (production).
|
|
- Static export is sufficient; ensure build produces `index.html`/`static` assets.
|
|
3. **Attach domains in Vercel**
|
|
- Add `console.blackroad.systems` as primary.
|
|
- Add `prism.blackroad.systems` as secondary/alias if you still support the old hostname.
|
|
4. **Update Cloudflare**
|
|
- `console` → `blackroad-prism-console.vercel.app` (proxied ✅).
|
|
- `prism` → `blackroad-prism-console.vercel.app` (proxied ✅) if keeping the alias.
|
|
5. **Validate**
|
|
- `dig +short console.blackroad.systems` should show the Vercel target.
|
|
- `curl -I https://console.blackroad.systems` should return 200 and load the console UI.
|
|
|
|
## Cross-Site Smoke Tests
|
|
- Confirm each hostname serves distinct content (web vs docs vs console) and no redirect loops.
|
|
- Check SSL chain validity using `curl -Iv https://<host>`.
|
|
- For console/web, open DevTools → Network to ensure API calls hit the correct backend (`blackroad.systems` or `api.blackroad.systems`).
|
|
- Set uptime monitors for all three hostnames after cutover.
|
|
|
|
---
|
|
|
|
**Use this playbook anytime you need to bring the sites online or verify their health after infrastructure changes.**
|