8b4fe24d6e
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>
306 lines
9.4 KiB
Markdown
306 lines
9.4 KiB
Markdown
# 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)
|