Pi deployment mega-session: 136+ containers deployed
Massive deployment session deploying entire BlackRoad/Lucidia infrastructure to Raspberry Pi 4B: - Cleaned /tmp space: 595MB → 5.2GB free - Total containers: 136+ running simultaneously - Ports: 3067-3200+ - Disk: 25G/29G (92% usage) - Memory: 3.6Gi/7.9Gi Deployment scripts created: - /tmp/continue-deploy.sh (v2-* deployments) - /tmp/absolute-final-deploy.sh (final-* deployments) - /tmp/deployment-status.sh (monitoring) Infrastructure maximized on single Pi 4B (8GB RAM, 32GB SD). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Alexa Louise
10
.github/workflows/security.yml
vendored
10
.github/workflows/security.yml
vendored
@@ -181,11 +181,11 @@ jobs:
|
|||||||
echo "" >> $GITHUB_STEP_SUMMARY
|
echo "" >> $GITHUB_STEP_SUMMARY
|
||||||
echo "### Top Issues" >> $GITHUB_STEP_SUMMARY
|
echo "### Top Issues" >> $GITHUB_STEP_SUMMARY
|
||||||
cat bandit-report.json | python3 -c "
|
cat bandit-report.json | python3 -c "
|
||||||
import json, sys
|
import json, sys
|
||||||
d = json.load(sys.stdin)
|
d = json.load(sys.stdin)
|
||||||
for r in d.get('results', [])[:10]:
|
for r in d.get('results', [])[:10]:
|
||||||
print(f\"- **{r['issue_severity']}**: {r['issue_text']} ({r['filename']}:{r['line_number']})\")
|
print(f\"- **{r['issue_severity']}**: {r['issue_text']} ({r['filename']}:{r['line_number']})\")
|
||||||
" >> $GITHUB_STEP_SUMMARY
|
" >> $GITHUB_STEP_SUMMARY
|
||||||
fi
|
fi
|
||||||
fi
|
fi
|
||||||
continue-on-error: true
|
continue-on-error: true
|
||||||
|
|||||||
1714
MESH-30K.md
Normal file
1714
MESH-30K.md
Normal file
File diff suppressed because it is too large
Load Diff
507
docs/LAUNCH-SEQUENCE.md
Normal file
507
docs/LAUNCH-SEQUENCE.md
Normal file
@@ -0,0 +1,507 @@
|
|||||||
|
# BlackRoad OS — Launch Sequence
|
||||||
|
|
||||||
|
> **Generated:** 2025-12-01
|
||||||
|
> **Status:** READY FOR APPROVAL
|
||||||
|
> **Governor:** cece.governor.v1
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. RECONSTRUCTED VISION (Baseline Spec)
|
||||||
|
|
||||||
|
### Product Blueprint
|
||||||
|
|
||||||
|
BlackRoad OS is a **distributed AI orchestration platform** with six portals:
|
||||||
|
|
||||||
|
| Portal | Domain | MVP Status |
|
||||||
|
|--------|--------|------------|
|
||||||
|
| **Lucidia** | Personal AI with persistent memory | Phase 0 |
|
||||||
|
| **RoadWork** | Education/homework help | Phase 1 |
|
||||||
|
| **RoadView** | Media creation (video/image gen) | Phase 2 |
|
||||||
|
| **RoadGlitch** | Gaming (procedural content) | Phase 2 |
|
||||||
|
| **RoadWorld** | Navigation + context | Phase 3 |
|
||||||
|
| **BackRoad** | Privacy infrastructure | Phase 3 |
|
||||||
|
|
||||||
|
### Technical Scope Map
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ PORTAL LAYER │
|
||||||
|
│ Lucidia │ RoadWork │ RoadView │ RoadGlitch │ RoadWorld │
|
||||||
|
├─────────────────────────────────────────────────────────────────┤
|
||||||
|
│ GOVERNANCE LAYER │
|
||||||
|
│ Policies │ Ledger │ Intents │ Claims │ Delegations │
|
||||||
|
├─────────────────────────────────────────────────────────────────┤
|
||||||
|
│ INTEGRATION LAYER │
|
||||||
|
│ MCP Servers │ Tools │ GitHub │ Cloudflare │ Railway │
|
||||||
|
├─────────────────────────────────────────────────────────────────┤
|
||||||
|
│ INFRASTRUCTURE LAYER │
|
||||||
|
│ Cloudflare Pages │ Railway (API) │ Postgres │ Self-hosted LLM │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### MVP Definition
|
||||||
|
|
||||||
|
#### Phase 0 (NOW — Week 1-2)
|
||||||
|
- [x] Infra Map working with real GitHub data
|
||||||
|
- [ ] All core services deployed and healthy
|
||||||
|
- [ ] DNS routing complete (blackroad.io → all subdomains)
|
||||||
|
- [ ] `/health` and `/version` on every service
|
||||||
|
|
||||||
|
#### Phase 1 (Week 3-4)
|
||||||
|
- [ ] Lucidia basic chat working
|
||||||
|
- [ ] Homework Portal basic functionality
|
||||||
|
- [ ] Creator Portal scaffold
|
||||||
|
- [ ] Agent registry + Cece orchestration
|
||||||
|
|
||||||
|
#### Phase 2 (Week 5-8)
|
||||||
|
- [ ] RoadView media generation
|
||||||
|
- [ ] RoadGlitch game content
|
||||||
|
- [ ] Full governance layer
|
||||||
|
- [ ] Policy evaluation in production
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. MASTER REPOSITORY MAP
|
||||||
|
|
||||||
|
### Active Repos (Keep & Deploy)
|
||||||
|
|
||||||
|
| Repo | Purpose | Deploy To | Status |
|
||||||
|
|------|---------|-----------|--------|
|
||||||
|
| `blackroad-os-web` | Main website + Infra Map | Cloudflare Pages | ✅ READY |
|
||||||
|
| `blackroad-os-core` | API + Database + Integrations | Railway | ✅ READY |
|
||||||
|
| `blackroad-os-api` | Public API Gateway | Railway | 🔧 NEEDS SETUP |
|
||||||
|
| `blackroad-os-api-gateway` | Edge routing | Cloudflare Workers | 🔧 NEEDS SETUP |
|
||||||
|
| `blackroad-os-operator` | Background jobs + scheduling | Railway | 🔧 NEEDS SETUP |
|
||||||
|
| `blackroad-os-prism-console` | Admin dashboard | Cloudflare Pages | 🔧 NEEDS SETUP |
|
||||||
|
| `blackroad-os-docs` | Documentation | Cloudflare Pages | ✅ READY |
|
||||||
|
| `blackroad-os-infra` | IaC, DNS configs, runbooks | N/A (reference) | ✅ READY |
|
||||||
|
| `blackroad-os-agents` | Agent implementations | Railway | 🔧 NEEDS SETUP |
|
||||||
|
| `blackroad-os-brand` | Brand assets | N/A (reference) | ✅ READY |
|
||||||
|
| `lucidia-core` | AI reasoning engines | Railway | 🔧 NEEDS SETUP |
|
||||||
|
| `lucidia-platform` | Lucidia web UI | Cloudflare Pages | 🔧 NEEDS SETUP |
|
||||||
|
|
||||||
|
### Archived Repos (Already Done)
|
||||||
|
|
||||||
|
| Repo | Reason |
|
||||||
|
|------|--------|
|
||||||
|
| `blackroad-os-research` | Merged into docs |
|
||||||
|
| `blackroad-os-ideas` | Merged into docs |
|
||||||
|
| `blackroad-os-helper` | Superseded by agents |
|
||||||
|
| `blackroad-os-home` | Merged into docs |
|
||||||
|
| `blackroad-os-demo` | Sample only |
|
||||||
|
| `blackroad-agents` | Superseded by blackroad-os-agents |
|
||||||
|
| `blackroad-agent-os` | Superseded by operator |
|
||||||
|
|
||||||
|
### Pack Repos (Future — Not Phase 0)
|
||||||
|
|
||||||
|
| Repo | Phase |
|
||||||
|
|------|-------|
|
||||||
|
| `blackroad-os-pack-creator-studio` | Phase 2 |
|
||||||
|
| `blackroad-os-pack-education` | Phase 1 |
|
||||||
|
| `blackroad-os-pack-finance` | Phase 2 |
|
||||||
|
| `blackroad-os-pack-infra-devops` | Phase 1 |
|
||||||
|
| `blackroad-os-pack-legal` | Phase 3 |
|
||||||
|
| `blackroad-os-pack-research-lab` | Phase 3 |
|
||||||
|
|
||||||
|
### Pi/Edge Repos (Later)
|
||||||
|
|
||||||
|
| Repo | Phase |
|
||||||
|
|------|-------|
|
||||||
|
| `blackroad-pi-ops` | Phase 2 |
|
||||||
|
| `blackroad-pi-holo` | Phase 3 |
|
||||||
|
| `blackroad-os-mesh` | Phase 2 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. LIVE PLATFORM DEPLOYMENT PLAN
|
||||||
|
|
||||||
|
### DNS Mapping Table
|
||||||
|
|
||||||
|
| Subdomain | Target | Type | Provider |
|
||||||
|
|-----------|--------|------|----------|
|
||||||
|
| `blackroad.io` | Cloudflare Pages (web) | CNAME | Cloudflare |
|
||||||
|
| `www.blackroad.io` | → blackroad.io | CNAME | Cloudflare |
|
||||||
|
| `api.blackroad.io` | Railway (blackroad-os-api) | CNAME | Railway |
|
||||||
|
| `app.blackroad.io` | Cloudflare Pages (prism) | CNAME | Cloudflare |
|
||||||
|
| `docs.blackroad.io` | Cloudflare Pages (docs) | CNAME | Cloudflare |
|
||||||
|
| `lucidia.blackroad.io` | Cloudflare Pages (lucidia-platform) | CNAME | Cloudflare |
|
||||||
|
| `status.blackroad.io` | Cloudflare Pages (beacon) | CNAME | Cloudflare |
|
||||||
|
|
||||||
|
### Service Registry
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"services": [
|
||||||
|
{
|
||||||
|
"name": "blackroad-os-web",
|
||||||
|
"type": "frontend",
|
||||||
|
"provider": "cloudflare-pages",
|
||||||
|
"domain": "blackroad.io",
|
||||||
|
"health": "/health",
|
||||||
|
"version": "/version",
|
||||||
|
"repo": "BlackRoad-OS/blackroad-os-web"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "blackroad-os-core",
|
||||||
|
"type": "api",
|
||||||
|
"provider": "railway",
|
||||||
|
"domain": "internal",
|
||||||
|
"port": 4000,
|
||||||
|
"health": "/health",
|
||||||
|
"version": "/api/version",
|
||||||
|
"repo": "BlackRoad-OS/blackroad-os-core"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "blackroad-os-api",
|
||||||
|
"type": "gateway",
|
||||||
|
"provider": "railway",
|
||||||
|
"domain": "api.blackroad.io",
|
||||||
|
"health": "/health",
|
||||||
|
"version": "/version",
|
||||||
|
"repo": "BlackRoad-OS/blackroad-os-api"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "blackroad-os-docs",
|
||||||
|
"type": "frontend",
|
||||||
|
"provider": "cloudflare-pages",
|
||||||
|
"domain": "docs.blackroad.io",
|
||||||
|
"health": "/health",
|
||||||
|
"version": "/version",
|
||||||
|
"repo": "BlackRoad-OS/blackroad-os-docs"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "blackroad-os-prism-console",
|
||||||
|
"type": "frontend",
|
||||||
|
"provider": "cloudflare-pages",
|
||||||
|
"domain": "app.blackroad.io",
|
||||||
|
"health": "/health",
|
||||||
|
"version": "/version",
|
||||||
|
"repo": "BlackRoad-OS/blackroad-os-prism-console"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deployment Order
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Database (Railway Postgres) ────────────────────── ✅ DONE
|
||||||
|
│
|
||||||
|
2. blackroad-os-core (API server) ─────────────────── ✅ RUNNING LOCALLY
|
||||||
|
│
|
||||||
|
3. blackroad-os-web (Main site + Infra Map) ───────── 🔧 DEPLOY TO CF PAGES
|
||||||
|
│
|
||||||
|
4. blackroad-os-docs ──────────────────────────────── 🔧 DEPLOY TO CF PAGES
|
||||||
|
│
|
||||||
|
5. blackroad-os-api (Public gateway) ──────────────── 🔧 DEPLOY TO RAILWAY
|
||||||
|
│
|
||||||
|
6. blackroad-os-prism-console ─────────────────────── 🔧 DEPLOY TO CF PAGES
|
||||||
|
│
|
||||||
|
7. blackroad-os-operator (Background jobs) ────────── 🔧 DEPLOY TO RAILWAY
|
||||||
|
│
|
||||||
|
8. lucidia-core + lucidia-platform ────────────────── 🔧 PHASE 1
|
||||||
|
```
|
||||||
|
|
||||||
|
### Required Environment Variables
|
||||||
|
|
||||||
|
#### blackroad-os-core (Railway)
|
||||||
|
```bash
|
||||||
|
DATABASE_URL=postgresql://...
|
||||||
|
GITHUB_TOKEN=ghp_...
|
||||||
|
CLOUDFLARE_API_TOKEN=...
|
||||||
|
CLOUDFLARE_ACCOUNT_ID=848cf0b18d51e0170e0d1537aec3505a
|
||||||
|
RAILWAY_TOKEN=...
|
||||||
|
PORT=4000
|
||||||
|
```
|
||||||
|
|
||||||
|
#### blackroad-os-web (Cloudflare Pages)
|
||||||
|
```bash
|
||||||
|
NEXT_PUBLIC_API_URL=https://api.blackroad.io
|
||||||
|
SITE_URL=https://blackroad.io
|
||||||
|
```
|
||||||
|
|
||||||
|
#### blackroad-os-api (Railway)
|
||||||
|
```bash
|
||||||
|
DATABASE_URL=postgresql://...
|
||||||
|
CORE_API_URL=http://blackroad-os-core.railway.internal:4000
|
||||||
|
PORT=8080
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. MAKE IT LIVE CHECKLIST
|
||||||
|
|
||||||
|
### Phase 0: Core Infrastructure (THIS WEEK)
|
||||||
|
|
||||||
|
```
|
||||||
|
[ ] 1. Deploy blackroad-os-core to Railway
|
||||||
|
- Link to existing Postgres database
|
||||||
|
- Set environment variables
|
||||||
|
- Verify /health returns {"status":"ok"}
|
||||||
|
|
||||||
|
[ ] 2. Deploy blackroad-os-web to Cloudflare Pages
|
||||||
|
- Connect to GitHub repo
|
||||||
|
- Set NEXT_PUBLIC_API_URL to Railway URL
|
||||||
|
- Verify builds and deploys
|
||||||
|
|
||||||
|
[ ] 3. Configure DNS in Cloudflare
|
||||||
|
- blackroad.io → CF Pages (web)
|
||||||
|
- api.blackroad.io → Railway (core for now)
|
||||||
|
- docs.blackroad.io → CF Pages (docs)
|
||||||
|
|
||||||
|
[ ] 4. Verify all services healthy
|
||||||
|
- curl https://blackroad.io/health
|
||||||
|
- curl https://api.blackroad.io/health
|
||||||
|
- curl https://docs.blackroad.io/health
|
||||||
|
|
||||||
|
[ ] 5. Run infra:sync in production
|
||||||
|
- All repos visible on /infra
|
||||||
|
- GitHub integration green
|
||||||
|
- Last synced timestamp updating
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 0.5: Full API Layer (Next Week)
|
||||||
|
|
||||||
|
```
|
||||||
|
[ ] 6. Deploy blackroad-os-api to Railway
|
||||||
|
- Public API gateway
|
||||||
|
- Rate limiting
|
||||||
|
- Auth middleware
|
||||||
|
|
||||||
|
[ ] 7. Deploy blackroad-os-prism-console to CF Pages
|
||||||
|
- Admin dashboard at app.blackroad.io
|
||||||
|
- Connect to API
|
||||||
|
|
||||||
|
[ ] 8. Deploy blackroad-os-operator to Railway
|
||||||
|
- Background job runner
|
||||||
|
- Scheduled sync
|
||||||
|
- Health monitoring
|
||||||
|
|
||||||
|
[ ] 9. Set up Cloudflare tunnels for secure internal traffic
|
||||||
|
- Core API not publicly exposed
|
||||||
|
- Gateway handles all external requests
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 1: Portals (Week 3-4)
|
||||||
|
|
||||||
|
```
|
||||||
|
[ ] 10. Deploy lucidia-core to Railway
|
||||||
|
- AI reasoning engine
|
||||||
|
- Connect to LLM providers
|
||||||
|
|
||||||
|
[ ] 11. Deploy lucidia-platform to CF Pages
|
||||||
|
- Chat interface at lucidia.blackroad.io
|
||||||
|
- Connected to lucidia-core
|
||||||
|
|
||||||
|
[ ] 12. Implement Homework Portal
|
||||||
|
- Basic question/answer flow
|
||||||
|
- Subject detection
|
||||||
|
- Response storage
|
||||||
|
|
||||||
|
[ ] 13. Implement Creator Portal scaffold
|
||||||
|
- Project management
|
||||||
|
- Template selection
|
||||||
|
- Draft storage
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. MISSING FILES TO GENERATE
|
||||||
|
|
||||||
|
### SERVICE_REGISTRY.json (for blackroad-os-infra)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"$schema": "./schemas/service-registry.schema.json",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"updated": "2025-12-01",
|
||||||
|
"services": [
|
||||||
|
{
|
||||||
|
"id": "web",
|
||||||
|
"name": "blackroad-os-web",
|
||||||
|
"repo": "BlackRoad-OS/blackroad-os-web",
|
||||||
|
"provider": "cloudflare-pages",
|
||||||
|
"domain": "blackroad.io",
|
||||||
|
"endpoints": {
|
||||||
|
"health": "/health",
|
||||||
|
"version": "/version"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "core",
|
||||||
|
"name": "blackroad-os-core",
|
||||||
|
"repo": "BlackRoad-OS/blackroad-os-core",
|
||||||
|
"provider": "railway",
|
||||||
|
"internal": true,
|
||||||
|
"port": 4000,
|
||||||
|
"endpoints": {
|
||||||
|
"health": "/health",
|
||||||
|
"infra": "/api/infra"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "api",
|
||||||
|
"name": "blackroad-os-api",
|
||||||
|
"repo": "BlackRoad-OS/blackroad-os-api",
|
||||||
|
"provider": "railway",
|
||||||
|
"domain": "api.blackroad.io",
|
||||||
|
"port": 8080,
|
||||||
|
"endpoints": {
|
||||||
|
"health": "/health",
|
||||||
|
"version": "/version"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "docs",
|
||||||
|
"name": "blackroad-os-docs",
|
||||||
|
"repo": "BlackRoad-OS/blackroad-os-docs",
|
||||||
|
"provider": "cloudflare-pages",
|
||||||
|
"domain": "docs.blackroad.io",
|
||||||
|
"endpoints": {
|
||||||
|
"health": "/health"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "prism",
|
||||||
|
"name": "blackroad-os-prism-console",
|
||||||
|
"repo": "BlackRoad-OS/blackroad-os-prism-console",
|
||||||
|
"provider": "cloudflare-pages",
|
||||||
|
"domain": "app.blackroad.io",
|
||||||
|
"endpoints": {
|
||||||
|
"health": "/health"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Operator Manifest (for blackroad-os-operator)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# operator.manifest.yaml
|
||||||
|
name: blackroad-os-operator
|
||||||
|
version: 0.1.0
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
- name: infra-sync
|
||||||
|
schedule: "0 * * * *" # Every hour
|
||||||
|
command: pnpm infra:sync
|
||||||
|
timeout: 300s
|
||||||
|
|
||||||
|
- name: health-check
|
||||||
|
schedule: "*/5 * * * *" # Every 5 minutes
|
||||||
|
command: pnpm health:check
|
||||||
|
timeout: 60s
|
||||||
|
|
||||||
|
workers:
|
||||||
|
- name: agent-runner
|
||||||
|
concurrency: 5
|
||||||
|
queue: agent-tasks
|
||||||
|
|
||||||
|
- name: notification-sender
|
||||||
|
concurrency: 2
|
||||||
|
queue: notifications
|
||||||
|
|
||||||
|
integrations:
|
||||||
|
- github
|
||||||
|
- cloudflare
|
||||||
|
- railway
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deploy Script (for CI/CD)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
# deploy.sh - BlackRoad OS deployment script
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
SERVICE=$1
|
||||||
|
ENV=${2:-production}
|
||||||
|
|
||||||
|
case $SERVICE in
|
||||||
|
web)
|
||||||
|
echo "Deploying blackroad-os-web to Cloudflare Pages..."
|
||||||
|
cd /path/to/blackroad-os-web
|
||||||
|
pnpm build
|
||||||
|
wrangler pages deploy .out --project-name=blackroad-os-web
|
||||||
|
;;
|
||||||
|
|
||||||
|
core)
|
||||||
|
echo "Deploying blackroad-os-core to Railway..."
|
||||||
|
cd /path/to/blackroad-os-core
|
||||||
|
railway up
|
||||||
|
;;
|
||||||
|
|
||||||
|
api)
|
||||||
|
echo "Deploying blackroad-os-api to Railway..."
|
||||||
|
cd /path/to/blackroad-os-api
|
||||||
|
railway up
|
||||||
|
;;
|
||||||
|
|
||||||
|
docs)
|
||||||
|
echo "Deploying blackroad-os-docs to Cloudflare Pages..."
|
||||||
|
cd /path/to/blackroad-os-docs
|
||||||
|
pnpm build
|
||||||
|
wrangler pages deploy out --project-name=blackroad-os-docs
|
||||||
|
;;
|
||||||
|
|
||||||
|
all)
|
||||||
|
$0 core $ENV
|
||||||
|
$0 api $ENV
|
||||||
|
$0 web $ENV
|
||||||
|
$0 docs $ENV
|
||||||
|
;;
|
||||||
|
|
||||||
|
*)
|
||||||
|
echo "Usage: deploy.sh [web|core|api|docs|all] [production|staging]"
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
|
||||||
|
echo "✓ Deployment complete"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. IMMEDIATE NEXT ACTIONS
|
||||||
|
|
||||||
|
### Right Now (Copy-Paste Ready)
|
||||||
|
|
||||||
|
**Step 1: Deploy Core to Railway**
|
||||||
|
```bash
|
||||||
|
cd /Users/alexa/blackroad-os-core
|
||||||
|
railway link # Select: blackroad-os-core project
|
||||||
|
railway up
|
||||||
|
```
|
||||||
|
|
||||||
|
**Step 2: Deploy Web to Cloudflare Pages**
|
||||||
|
```bash
|
||||||
|
cd /Users/alexa/blackroad-os-web
|
||||||
|
pnpm build
|
||||||
|
wrangler pages project create blackroad-os-web --production-branch main
|
||||||
|
wrangler pages deploy .out --project-name=blackroad-os-web
|
||||||
|
```
|
||||||
|
|
||||||
|
**Step 3: Configure DNS**
|
||||||
|
```bash
|
||||||
|
# In Cloudflare dashboard, add CNAME:
|
||||||
|
# blackroad.io → blackroad-os-web.pages.dev
|
||||||
|
# api.blackroad.io → [railway-public-url]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Step 4: Verify**
|
||||||
|
```bash
|
||||||
|
curl https://blackroad.io/health
|
||||||
|
curl https://blackroad.io/infra
|
||||||
|
curl https://api.blackroad.io/health
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ready for confirmation. Say 'approve' to execute Phase 1.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Generated by cece.governor.v1*
|
||||||
|
*BlackRoad OS Launch Sequence v1.0*
|
||||||
305
docs/getting-started/SETUP.md
Normal file
305
docs/getting-started/SETUP.md
Normal file
@@ -0,0 +1,305 @@
|
|||||||
|
# BlackRoad OS Infra Map - Complete Setup Guide
|
||||||
|
|
||||||
|
This is the **zero-braincell** guide to getting Infra Map running with real data.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Node.js 18+
|
||||||
|
- pnpm 8+
|
||||||
|
- PostgreSQL (local or Railway)
|
||||||
|
- API tokens for GitHub, Cloudflare, Railway
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 1: Create a PostgreSQL Database
|
||||||
|
|
||||||
|
### Option A: Railway (Recommended - 2 clicks)
|
||||||
|
|
||||||
|
1. Go to [railway.app/new](https://railway.app/new)
|
||||||
|
2. Click "Provision PostgreSQL"
|
||||||
|
3. Once created, click the database → "Variables" tab
|
||||||
|
4. Copy `DATABASE_URL` (looks like `postgresql://postgres:xxx@xxx.railway.app:5432/railway`)
|
||||||
|
|
||||||
|
### Option B: Local PostgreSQL
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# macOS with Homebrew
|
||||||
|
brew install postgresql@15
|
||||||
|
brew services start postgresql@15
|
||||||
|
createdb blackroad_os
|
||||||
|
|
||||||
|
# Your DATABASE_URL will be:
|
||||||
|
# postgresql://localhost:5432/blackroad_os
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 2: Set Environment Variables
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd blackroad-os-core
|
||||||
|
|
||||||
|
# Copy example env file
|
||||||
|
cp .env.example .env
|
||||||
|
```
|
||||||
|
|
||||||
|
Edit `.env` with your values:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Database (from Step 1)
|
||||||
|
DATABASE_URL="postgresql://postgres:xxx@xxx.railway.app:5432/railway"
|
||||||
|
|
||||||
|
# GitHub - get from https://github.com/settings/tokens
|
||||||
|
# Scopes needed: repo, read:org
|
||||||
|
GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
|
||||||
|
|
||||||
|
# Cloudflare - get from https://dash.cloudflare.com/profile/api-tokens
|
||||||
|
# Permissions: Zone:Read, DNS:Read
|
||||||
|
CLOUDFLARE_API_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||||
|
CLOUDFLARE_ACCOUNT_ID="your-account-id" # From dashboard URL
|
||||||
|
|
||||||
|
# Railway - get from https://railway.app/account/tokens
|
||||||
|
RAILWAY_TOKEN="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 3: Install Dependencies & Migrate Database
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# In blackroad-os-core
|
||||||
|
cd /path/to/blackroad-os-core
|
||||||
|
|
||||||
|
# Install dependencies
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# Generate Prisma client
|
||||||
|
pnpm db:generate
|
||||||
|
|
||||||
|
# Push schema to database (creates all tables)
|
||||||
|
pnpm db:push
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected output:**
|
||||||
|
```
|
||||||
|
Your database is now in sync with your Prisma schema.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 4: Run Infra Sync
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# In blackroad-os-core
|
||||||
|
pnpm infra:sync
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected output:**
|
||||||
|
```
|
||||||
|
╔════════════════════════════════════════╗
|
||||||
|
║ BlackRoad OS Infra Sync ║
|
||||||
|
╚════════════════════════════════════════╝
|
||||||
|
|
||||||
|
--- Syncing GitHub ---
|
||||||
|
Authenticated as: your-username
|
||||||
|
Found 15 repositories
|
||||||
|
Syncing 8 BlackRoad-OS repos
|
||||||
|
✓ BlackRoad-OS/blackroad-os-web
|
||||||
|
✓ BlackRoad-OS/blackroad-os-core
|
||||||
|
...
|
||||||
|
|
||||||
|
--- Syncing Cloudflare ---
|
||||||
|
Cloudflare token verified
|
||||||
|
Found 2 zones
|
||||||
|
Zone blackroad.io: 12 records
|
||||||
|
✓ Synced 12 DNS records
|
||||||
|
|
||||||
|
--- Syncing Railway ---
|
||||||
|
Authenticated as: your@email.com
|
||||||
|
Found 3 Railway projects
|
||||||
|
✓ blackroad-web/blackroad-os-web (healthy)
|
||||||
|
✓ blackroad-api/api (healthy)
|
||||||
|
...
|
||||||
|
|
||||||
|
════════════════════════════════════════
|
||||||
|
✓ Sync Complete!
|
||||||
|
Repositories: 8
|
||||||
|
Domains: 12
|
||||||
|
Services: 5
|
||||||
|
════════════════════════════════════════
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 5: Start the Core API Server
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# In blackroad-os-core
|
||||||
|
pnpm dev:api
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected output:**
|
||||||
|
```
|
||||||
|
🖤 BlackRoad OS Core API
|
||||||
|
Server running on http://localhost:4000
|
||||||
|
Endpoints:
|
||||||
|
GET /health - Health check
|
||||||
|
GET /api/infra - Full infra snapshot
|
||||||
|
GET /api/projects - List projects
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
**Verify it works:**
|
||||||
|
```bash
|
||||||
|
curl http://localhost:4000/api/infra | jq
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 6: Start the Web App
|
||||||
|
|
||||||
|
**Open a new terminal:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# In blackroad-os-web
|
||||||
|
cd /path/to/blackroad-os-web
|
||||||
|
|
||||||
|
# Install dependencies (if not done)
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# Start dev server
|
||||||
|
pnpm dev
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected output:**
|
||||||
|
```
|
||||||
|
▲ Next.js 14.x
|
||||||
|
- Local: http://localhost:3000
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 7: See Real Data
|
||||||
|
|
||||||
|
1. Open [http://localhost:3000/infra](http://localhost:3000/infra)
|
||||||
|
2. You should see:
|
||||||
|
- Your actual repositories from GitHub
|
||||||
|
- Your DNS records from Cloudflare
|
||||||
|
- Your services from Railway
|
||||||
|
- Real health status for each service
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference Commands
|
||||||
|
|
||||||
|
| Command | Directory | What it does |
|
||||||
|
|---------|-----------|--------------|
|
||||||
|
| `pnpm db:push` | blackroad-os-core | Create/update database tables |
|
||||||
|
| `pnpm db:studio` | blackroad-os-core | Open Prisma Studio (visual DB browser) |
|
||||||
|
| `pnpm infra:sync` | blackroad-os-core | Pull data from GitHub/Cloudflare/Railway |
|
||||||
|
| `pnpm dev:api` | blackroad-os-core | Start API server on :4000 |
|
||||||
|
| `pnpm dev` | blackroad-os-web | Start web app on :3000 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### "Failed to load infrastructure data" on /infra
|
||||||
|
|
||||||
|
The web app can't reach the API server.
|
||||||
|
|
||||||
|
1. Make sure `pnpm dev:api` is running in blackroad-os-core
|
||||||
|
2. Check it responds: `curl http://localhost:4000/health`
|
||||||
|
|
||||||
|
### "GITHUB_TOKEN environment variable is required"
|
||||||
|
|
||||||
|
Your `.env` file is missing or not being read.
|
||||||
|
|
||||||
|
1. Make sure `.env` exists in blackroad-os-core root
|
||||||
|
2. Check it has `GITHUB_TOKEN=ghp_...`
|
||||||
|
|
||||||
|
### "Cloudflare API error: 403 Forbidden"
|
||||||
|
|
||||||
|
Your Cloudflare token doesn't have the right permissions.
|
||||||
|
|
||||||
|
1. Go to [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens)
|
||||||
|
2. Create a new token with: Zone:Read, DNS:Read
|
||||||
|
|
||||||
|
### "Railway API error: Unauthorized"
|
||||||
|
|
||||||
|
Your Railway token may have expired.
|
||||||
|
|
||||||
|
1. Go to [Railway Account Tokens](https://railway.app/account/tokens)
|
||||||
|
2. Generate a new token and update `.env`
|
||||||
|
|
||||||
|
### Empty data on /infra (shows "No projects yet")
|
||||||
|
|
||||||
|
The sync hasn't been run or didn't find any data.
|
||||||
|
|
||||||
|
1. Run `pnpm infra:sync` and check for errors
|
||||||
|
2. Verify your GitHub org is `BlackRoad-OS` or update the sync script filter
|
||||||
|
|
||||||
|
### Database connection errors
|
||||||
|
|
||||||
|
1. Check your `DATABASE_URL` is correct
|
||||||
|
2. For Railway: make sure the database is running
|
||||||
|
3. For local: make sure PostgreSQL is running (`brew services start postgresql@15`)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ Browser: http://localhost:3000/infra │
|
||||||
|
│ │
|
||||||
|
│ blackroad-os-web (Next.js) │
|
||||||
|
│ └── app/infra/page.tsx │
|
||||||
|
│ └── fetch('http://localhost:4000/api/infra') │
|
||||||
|
└──────────────────────────┬──────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ http://localhost:4000 │
|
||||||
|
│ │
|
||||||
|
│ blackroad-os-core (Hono API) │
|
||||||
|
│ └── src/api/server.ts │
|
||||||
|
│ └── GET /api/infra │
|
||||||
|
│ └── prisma.project.findFirst(...) │
|
||||||
|
└──────────────────────────┬──────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ PostgreSQL │
|
||||||
|
│ │
|
||||||
|
│ Tables: accounts, projects, services, domains, │
|
||||||
|
│ repositories, environments, audit_logs │
|
||||||
|
│ │
|
||||||
|
│ (populated by: pnpm infra:sync) │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
▲
|
||||||
|
│
|
||||||
|
┌──────────────────────────┴──────────────────────────────────┐
|
||||||
|
│ pnpm infra:sync │
|
||||||
|
│ │
|
||||||
|
│ src/scripts/infra-sync.ts │
|
||||||
|
│ └── src/integrations/ │
|
||||||
|
│ ├── github.ts → api.github.com │
|
||||||
|
│ ├── cloudflare.ts → api.cloudflare.com │
|
||||||
|
│ └── railway.ts → backboard.railway.app/graphql │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
Once you see real data on `/infra`:
|
||||||
|
|
||||||
|
1. **Creator Portal** - `/creator` for landing pages and content
|
||||||
|
2. **Homework Portal** - `/homework` for student help
|
||||||
|
3. **Agent Swarm** - "Summarize my infra" button
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Questions?** Open an issue at [github.com/BlackRoad-OS/blackroad-os-docs](https://github.com/BlackRoad-OS/blackroad-os-docs/issues)
|
||||||
263
docs/getting-started/infra-map-quickstart.md
Normal file
263
docs/getting-started/infra-map-quickstart.md
Normal file
@@ -0,0 +1,263 @@
|
|||||||
|
# Infra Map v1 Quickstart
|
||||||
|
|
||||||
|
The Infra Map is BlackRoad OS's central dashboard for viewing all your infrastructure in one place: services, domains, and repositories across GitHub, Cloudflare, and Railway.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Infra Map v1 is **read-only**. It discovers and displays:
|
||||||
|
|
||||||
|
- **Projects** - Logical groupings of related services
|
||||||
|
- **Services** - Running deployments on Railway, Cloudflare Pages, etc.
|
||||||
|
- **Domains** - DNS records from Cloudflare
|
||||||
|
- **Repositories** - GitHub repos linked to services
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Node.js 18+
|
||||||
|
- pnpm 8+
|
||||||
|
- PostgreSQL 14+ (for blackroad-os-core)
|
||||||
|
- API tokens for:
|
||||||
|
- GitHub (Personal Access Token or GitHub App)
|
||||||
|
- Cloudflare (API Token with Zone:Read, DNS:Read)
|
||||||
|
- Railway (API Token)
|
||||||
|
|
||||||
|
## Environment Variables
|
||||||
|
|
||||||
|
### blackroad-os-core
|
||||||
|
|
||||||
|
Create a `.env` file in `blackroad-os-core/`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Database
|
||||||
|
DATABASE_URL="postgresql://user:password@localhost:5432/blackroad_os"
|
||||||
|
|
||||||
|
# GitHub Integration
|
||||||
|
GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
|
||||||
|
GITHUB_API_URL="" # Optional: For GitHub Enterprise
|
||||||
|
|
||||||
|
# Cloudflare Integration
|
||||||
|
CLOUDFLARE_API_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||||||
|
CLOUDFLARE_ACCOUNT_ID="your-account-id" # Required for Tunnels/Pages
|
||||||
|
|
||||||
|
# Railway Integration
|
||||||
|
RAILWAY_TOKEN="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
|
||||||
|
```
|
||||||
|
|
||||||
|
### blackroad-os-web
|
||||||
|
|
||||||
|
Create a `.env.local` file in `blackroad-os-web/`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Site Configuration
|
||||||
|
SITE_URL="https://blackroad.io"
|
||||||
|
|
||||||
|
# API Backend (when not using static export)
|
||||||
|
BLACKROAD_API_URL="http://localhost:4000"
|
||||||
|
|
||||||
|
# Analytics (optional)
|
||||||
|
PLAUSIBLE_DOMAIN="analytics.blackroad.io"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Getting API Tokens
|
||||||
|
|
||||||
|
### GitHub Personal Access Token
|
||||||
|
|
||||||
|
1. Go to [GitHub Settings → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens)
|
||||||
|
2. Click "Generate new token (classic)"
|
||||||
|
3. Select scopes:
|
||||||
|
- `repo` (for private repos)
|
||||||
|
- `read:org` (to list org repos)
|
||||||
|
4. Copy the token to `GITHUB_TOKEN`
|
||||||
|
|
||||||
|
### Cloudflare API Token
|
||||||
|
|
||||||
|
1. Go to [Cloudflare Dashboard → API Tokens](https://dash.cloudflare.com/profile/api-tokens)
|
||||||
|
2. Click "Create Token"
|
||||||
|
3. Use the "Read all resources" template, or create custom with:
|
||||||
|
- Zone: Read
|
||||||
|
- DNS: Read
|
||||||
|
- (Optional) Account: Cloudflare Pages: Read
|
||||||
|
4. Copy the token to `CLOUDFLARE_API_TOKEN`
|
||||||
|
5. Copy your Account ID from the dashboard URL or overview page
|
||||||
|
|
||||||
|
### Railway API Token
|
||||||
|
|
||||||
|
1. Go to [Railway Dashboard → Account Settings](https://railway.app/account/tokens)
|
||||||
|
2. Click "Create Token"
|
||||||
|
3. Give it a name like "blackroad-infra-read"
|
||||||
|
4. Copy the token to `RAILWAY_TOKEN`
|
||||||
|
|
||||||
|
## Setup
|
||||||
|
|
||||||
|
### 1. Clone and Install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Clone the repos
|
||||||
|
git clone https://github.com/BlackRoad-OS/blackroad-os-core.git
|
||||||
|
git clone https://github.com/BlackRoad-OS/blackroad-os-web.git
|
||||||
|
|
||||||
|
# Install dependencies
|
||||||
|
cd blackroad-os-core && pnpm install
|
||||||
|
cd ../blackroad-os-web && pnpm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Database Setup
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd blackroad-os-core
|
||||||
|
|
||||||
|
# Generate Prisma client
|
||||||
|
pnpm prisma generate
|
||||||
|
|
||||||
|
# Run migrations (creates tables)
|
||||||
|
pnpm prisma migrate dev
|
||||||
|
|
||||||
|
# (Optional) Seed with sample data
|
||||||
|
pnpm prisma db seed
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Start Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Terminal 1: Start core (API server)
|
||||||
|
cd blackroad-os-core
|
||||||
|
pnpm dev
|
||||||
|
|
||||||
|
# Terminal 2: Start web (Next.js)
|
||||||
|
cd blackroad-os-web
|
||||||
|
pnpm dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Access Infra Map
|
||||||
|
|
||||||
|
Open [http://localhost:3000/infra](http://localhost:3000/infra)
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ blackroad-os-web │
|
||||||
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
|
||||||
|
│ │ /infra │ │ /dashboard │ │ /settings │ │
|
||||||
|
│ │ (UI) │ │ │ │ /integrations │ │
|
||||||
|
│ └──────┬──────┘ └─────────────┘ └─────────────────────┘ │
|
||||||
|
│ │ │
|
||||||
|
│ │ fetch /api/infra │
|
||||||
|
│ ▼ │
|
||||||
|
│ ┌─────────────────────────────────────────────────────────┐│
|
||||||
|
│ │ API Routes (Next.js) ││
|
||||||
|
│ └──────────────────────┬──────────────────────────────────┘│
|
||||||
|
└─────────────────────────┼───────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ blackroad-os-core │
|
||||||
|
│ ┌─────────────────────────────────────────────────────────┐│
|
||||||
|
│ │ src/integrations/ ││
|
||||||
|
│ │ ┌──────────┐ ┌─────────────┐ ┌──────────────┐ ││
|
||||||
|
│ │ │ github │ │ cloudflare │ │ railway │ ││
|
||||||
|
│ │ │ .ts │ │ .ts │ │ .ts │ ││
|
||||||
|
│ │ └────┬─────┘ └──────┬──────┘ └──────┬───────┘ ││
|
||||||
|
│ │ │ │ │ ││
|
||||||
|
│ │ └───────────────┼────────────────┘ ││
|
||||||
|
│ │ ▼ ││
|
||||||
|
│ │ ┌─────────────────┐ ││
|
||||||
|
│ │ │ sync.ts │ ││
|
||||||
|
│ │ │ InfraSyncService│ ││
|
||||||
|
│ │ └────────┬────────┘ ││
|
||||||
|
│ └───────────────────────┼─────────────────────────────────┘│
|
||||||
|
│ │ │
|
||||||
|
│ ▼ │
|
||||||
|
│ ┌─────────────────────────────────────────────────────────┐│
|
||||||
|
│ │ Prisma / PostgreSQL ││
|
||||||
|
│ │ Projects, Services, Domains, Repositories, Environments ││
|
||||||
|
│ └─────────────────────────────────────────────────────────┘│
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────┐
|
||||||
|
│ External APIs │
|
||||||
|
│ GitHub │ Cloudflare │ Railway │
|
||||||
|
└─────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Database Schema
|
||||||
|
|
||||||
|
The Prisma schema includes these main models for Infra Map:
|
||||||
|
|
||||||
|
| Model | Purpose |
|
||||||
|
|-------|---------|
|
||||||
|
| `Project` | Container for related services (type: infra, creator, etc.) |
|
||||||
|
| `Service` | A deployed service (Railway, Cloudflare Pages, etc.) |
|
||||||
|
| `Domain` | DNS record from Cloudflare |
|
||||||
|
| `Repository` | GitHub repository |
|
||||||
|
| `Environment` | Deployment environment (dev, staging, production) |
|
||||||
|
|
||||||
|
See full schema: `blackroad-os-core/prisma/schema.prisma`
|
||||||
|
|
||||||
|
## API Reference
|
||||||
|
|
||||||
|
### GET /api/infra
|
||||||
|
|
||||||
|
Returns the complete infrastructure snapshot.
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"projects": [
|
||||||
|
{
|
||||||
|
"id": "proj-1",
|
||||||
|
"name": "BlackRoad OS",
|
||||||
|
"slug": "blackroad-os",
|
||||||
|
"type": "infra",
|
||||||
|
"services": [...],
|
||||||
|
"repos": [...]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"stats": {
|
||||||
|
"totalServices": 4,
|
||||||
|
"totalDomains": 6,
|
||||||
|
"totalRepos": 5,
|
||||||
|
"healthyServices": 4,
|
||||||
|
"degradedServices": 0,
|
||||||
|
"downServices": 0
|
||||||
|
},
|
||||||
|
"integrations": {
|
||||||
|
"github": true,
|
||||||
|
"cloudflare": true,
|
||||||
|
"railway": true
|
||||||
|
},
|
||||||
|
"lastSynced": "2024-01-15T12:00:00.000Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### "GITHUB_TOKEN environment variable is required"
|
||||||
|
|
||||||
|
Ensure your `.env` file is in the correct location and contains `GITHUB_TOKEN`.
|
||||||
|
|
||||||
|
### "Cloudflare API error: 403"
|
||||||
|
|
||||||
|
Your API token may not have the required permissions. Create a new token with Zone:Read and DNS:Read.
|
||||||
|
|
||||||
|
### "Railway API error: Unauthorized"
|
||||||
|
|
||||||
|
Railway tokens expire. Generate a new one from the Railway dashboard.
|
||||||
|
|
||||||
|
### Services showing "unknown" status
|
||||||
|
|
||||||
|
The sync may not have run yet. Click "Sync Now" on the Infra Map page.
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
- **M1 Complete**: Read-only Infra Map is ready
|
||||||
|
- **Future**: Write operations, auto-sync schedules, alerting
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
See also:
|
||||||
|
- [API Design Reference](/docs/reference/api-design)
|
||||||
|
- [KV Schema Reference](/docs/reference/kv-schema)
|
||||||
|
- [Architecture Overview](/docs/meta/vision/architecture)
|
||||||
@@ -3,7 +3,7 @@
|
|||||||
"service": "docs",
|
"service": "docs",
|
||||||
"ts": "2025-11-21T02:26:02.384Z",
|
"ts": "2025-11-21T02:26:02.384Z",
|
||||||
"baseUrl": "https://docs.blackroad.systems",
|
"baseUrl": "https://docs.blackroad.systems",
|
||||||
"osRoot": "https://blackroad.systems"
|
"osRoot": "https://blackroad.systems",
|
||||||
"status": "ok",
|
"status": "ok",
|
||||||
"timestamp": "2025-11-19T21:43:46.169Z",
|
"timestamp": "2025-11-19T21:43:46.169Z",
|
||||||
"environment": "development"
|
"environment": "development"
|
||||||
|
|||||||
@@ -2,6 +2,4 @@
|
|||||||
"status": "ok",
|
"status": "ok",
|
||||||
"timestamp": "2025-11-20T18:35:36.292Z",
|
"timestamp": "2025-11-20T18:35:36.292Z",
|
||||||
"environment": "production"
|
"environment": "production"
|
||||||
"timestamp": "2025-11-19T21:43:46.169Z",
|
|
||||||
"environment": "development"
|
|
||||||
}
|
}
|
||||||
Reference in New Issue
Block a user