mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 05:57:21 -05:00
Add BlackRoad Master Orchestration Plan and infrastructure blueprints
This commit implements the complete "master orchestration prompt" deliverables: ## New Documentation ### Master Plan - MASTER_ORCHESTRATION_PLAN.md - Complete infrastructure → product → ecosystem blueprint - Full stack architecture (Layer 1-7) - Cloudflare → GoDaddy → Railway → GitHub topology - Agent orchestration model (Atlas → Operator → Prism → Lucidia) - 3-phase execution roadmap - Atlas automation commands ### Infrastructure - infra/cloudflare/CLOUDFLARE_DNS_BLUEPRINT.md - Complete DNS configuration - Migration process (GoDaddy → Cloudflare) - DNS records for all 10+ domains - SSL/TLS configuration - Caching rules and security headers - Automation scripts - Troubleshooting guide ### GitHub Organization - .github/GITHUB_ENTERPRISE_SETUP.md - Repository organization structure - Monorepo vs multi-repo strategy - Branch protection rules - Required status checks - PR/issue templates - Project boards and labels - Recommended workflow additions (CodeQL, Dependabot) - .github/CODEOWNERS - Code ownership definitions - Global owners - Component-specific owners (backend, frontend, infra, docs) ### Next Actions - NEXT_ACTIONS_ALEXA.md - No-overwhelm execution checklist - Immediate priorities (infrastructure setup) - Week 1-2 tasks (product polish) - Week 3-4 tasks (alpha launch) - Success metrics - Tools & resources ## Context These documents synthesize: - The Big Kahuna Vision (complete OS architecture) - 3-phase execution roadmap (18-24 months) - Brand architecture (multi-brand ecosystem) - Current monorepo structure - Infrastructure topology ## Purpose Provide Alexa (Operator) with: 1. Complete infrastructure blueprint 2. Clear execution path 3. No-overwhelm next steps 4. Reference for all future decisions ## Next Steps See NEXT_ACTIONS_ALEXA.md for immediate priorities: 1. Migrate DNS to Cloudflare 2. Verify Railway deployment 3. Update GitHub secrets 4. Polish OS and add real backend data 5. Launch blackroad.systems and docs sites --- Ready for the next command, Operator.
This commit is contained in:
Claude
47
.github/CODEOWNERS
vendored
Normal file
47
.github/CODEOWNERS
vendored
Normal file
@@ -0,0 +1,47 @@
|
|||||||
|
# BlackRoad OS Code Owners
|
||||||
|
# This file defines who is responsible for code in this repository.
|
||||||
|
# Each line is a file pattern followed by one or more owners.
|
||||||
|
|
||||||
|
# Global owners (all files)
|
||||||
|
* @alexa-amundson
|
||||||
|
|
||||||
|
# Backend
|
||||||
|
/backend/ @alexa-amundson
|
||||||
|
/backend/app/ @alexa-amundson
|
||||||
|
/backend/requirements.txt @alexa-amundson
|
||||||
|
/backend/Dockerfile @alexa-amundson
|
||||||
|
|
||||||
|
# Frontend / OS
|
||||||
|
/blackroad-os/ @alexa-amundson
|
||||||
|
/backend/static/ @alexa-amundson
|
||||||
|
|
||||||
|
# Infrastructure & DevOps
|
||||||
|
/.github/ @alexa-amundson
|
||||||
|
/.github/workflows/ @alexa-amundson
|
||||||
|
/scripts/ @alexa-amundson
|
||||||
|
/ops/ @alexa-amundson
|
||||||
|
/infra/ @alexa-amundson
|
||||||
|
railway.toml @alexa-amundson
|
||||||
|
railway.json @alexa-amundson
|
||||||
|
docker-compose.yml @alexa-amundson
|
||||||
|
|
||||||
|
# Documentation
|
||||||
|
/docs/ @alexa-amundson
|
||||||
|
/README.md @alexa-amundson
|
||||||
|
/*.md @alexa-amundson
|
||||||
|
|
||||||
|
# Python SDK
|
||||||
|
/sdk/python/ @alexa-amundson
|
||||||
|
|
||||||
|
# TypeScript SDK
|
||||||
|
/sdk/typescript/ @alexa-amundson
|
||||||
|
|
||||||
|
# Agents & Prompts
|
||||||
|
/agents/ @alexa-amundson
|
||||||
|
/blackroad-universe/prompts/ @alexa-amundson
|
||||||
|
|
||||||
|
# Cognitive & Research
|
||||||
|
/cognitive/ @alexa-amundson
|
||||||
|
|
||||||
|
# BlackRoad Universe (Brand, GTM, Domains)
|
||||||
|
/blackroad-universe/ @alexa-amundson
|
||||||
736
.github/GITHUB_ENTERPRISE_SETUP.md
vendored
Normal file
736
.github/GITHUB_ENTERPRISE_SETUP.md
vendored
Normal file
@@ -0,0 +1,736 @@
|
|||||||
|
# GitHub Enterprise Structure
|
||||||
|
## Repository Organization, Policies, and Workflows
|
||||||
|
|
||||||
|
**Version:** 1.0
|
||||||
|
**Date:** 2025-11-18
|
||||||
|
**Purpose:** Define GitHub organization structure and best practices
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Repository Strategy
|
||||||
|
|
||||||
|
### Current State: Monorepo ✅
|
||||||
|
|
||||||
|
**Repository**: `blackboxprogramming/BlackRoad-Operating-System`
|
||||||
|
|
||||||
|
**Structure**:
|
||||||
|
```
|
||||||
|
BlackRoad-Operating-System/
|
||||||
|
├── backend/ # FastAPI backend
|
||||||
|
├── blackroad-os/ # Win95 OS frontend
|
||||||
|
├── docs/ # Documentation
|
||||||
|
├── sdk/ # Python & TypeScript SDKs
|
||||||
|
│ ├── python/
|
||||||
|
│ └── typescript/
|
||||||
|
├── agents/ # Agent specifications
|
||||||
|
├── cognitive/ # Cognitive architecture
|
||||||
|
├── blackroad-universe/ # Brand, domains, GTM
|
||||||
|
├── ops/ # Operations, domain config
|
||||||
|
├── infra/ # Infrastructure configs
|
||||||
|
└── scripts/ # Automation scripts
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- ✅ Single source of truth
|
||||||
|
- ✅ Atomic commits across frontend/backend
|
||||||
|
- ✅ Simpler for small teams
|
||||||
|
- ✅ Easier local development
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- ❌ Larger repo size
|
||||||
|
- ❌ Harder to scale teams (can't assign granular permissions)
|
||||||
|
- ❌ All CI runs even if only one component changes (can be mitigated with path filters)
|
||||||
|
|
||||||
|
**Recommendation**: **Keep monorepo for Phase 1** (0-12 months), evaluate split in Phase 2 when team grows.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Future State: Multi-Repo (Phase 2+)
|
||||||
|
|
||||||
|
**When to split**:
|
||||||
|
- Team size > 10 engineers
|
||||||
|
- Need granular access control (different teams own different repos)
|
||||||
|
- Want independent release cycles (frontend vs backend)
|
||||||
|
|
||||||
|
**Proposed Repos**:
|
||||||
|
|
||||||
|
1. **blackroad-os-core** - Core OS runtime, identity (PS-SHA∞)
|
||||||
|
- Owner: Core team
|
||||||
|
- Language: Python, JavaScript
|
||||||
|
- Deploy: Railway
|
||||||
|
|
||||||
|
2. **blackroad-os-prism-console** - Admin, observability, Prism UI
|
||||||
|
- Owner: Frontend team
|
||||||
|
- Language: React/TypeScript
|
||||||
|
- Deploy: Vercel / GitHub Pages
|
||||||
|
|
||||||
|
3. **blackroad-os-operator** - Workers, schedulers, agent orchestration
|
||||||
|
- Owner: Backend team
|
||||||
|
- Language: Python (Celery/RQ)
|
||||||
|
- Deploy: Railway
|
||||||
|
|
||||||
|
4. **blackroad-os-api** - Backend API gateway, routing, schemas
|
||||||
|
- Owner: Backend team
|
||||||
|
- Language: Python (FastAPI)
|
||||||
|
- Deploy: Railway
|
||||||
|
|
||||||
|
5. **blackroad-os-web** - Pocket OS web interface (frontend)
|
||||||
|
- Owner: Frontend team
|
||||||
|
- Language: HTML/CSS/JS
|
||||||
|
- Deploy: GitHub Pages
|
||||||
|
|
||||||
|
6. **blackroad-os-docs** - Codex, specs, standards, whitepapers
|
||||||
|
- Owner: Docs team
|
||||||
|
- Language: Markdown
|
||||||
|
- Deploy: GitHub Pages
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## GitHub Organization
|
||||||
|
|
||||||
|
### Organization Settings
|
||||||
|
|
||||||
|
**Name**: `blackroad` (preferred) or keep `blackboxprogramming`
|
||||||
|
|
||||||
|
**Teams**:
|
||||||
|
|
||||||
|
| Team | Role | Members | Repositories |
|
||||||
|
|------|------|---------|--------------|
|
||||||
|
| `@blackroad/core` | Maintain | Alexa + core contributors | All repos (admin) |
|
||||||
|
| `@blackroad/backend` | Write | Backend engineers | backend, api, operator repos |
|
||||||
|
| `@blackroad/frontend` | Write | Frontend engineers | web, prism-console repos |
|
||||||
|
| `@blackroad/docs` | Write | Docs writers, technical writers | docs repo |
|
||||||
|
| `@blackroad/community` | Triage | External contributors | All (read, can create issues/PRs) |
|
||||||
|
|
||||||
|
**Team Sync** (if using external tools):
|
||||||
|
- Sync with Slack: `#blackroad-core`, `#blackroad-backend`, etc.
|
||||||
|
- Sync with Discord: Roles mirror GitHub teams
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Branch Protection Rules
|
||||||
|
|
||||||
|
### `main` Branch (Production)
|
||||||
|
|
||||||
|
**Required Settings**:
|
||||||
|
- ✅ **Require pull request before merging**
|
||||||
|
- Required approvals: **1**
|
||||||
|
- Dismiss stale reviews: ✅
|
||||||
|
- Require review from Code Owners: ✅
|
||||||
|
|
||||||
|
- ✅ **Require status checks to pass**
|
||||||
|
- Required checks:
|
||||||
|
- `CI / lint`
|
||||||
|
- `CI / type-check`
|
||||||
|
- `CI / test-backend`
|
||||||
|
- `CI / build`
|
||||||
|
- Require branches to be up to date: ✅
|
||||||
|
|
||||||
|
- ✅ **Require conversation resolution before merging**
|
||||||
|
|
||||||
|
- ❌ **Do not allow bypassing** (enforce for administrators)
|
||||||
|
|
||||||
|
- ❌ **Do not allow force pushes**
|
||||||
|
|
||||||
|
- ❌ **Do not allow deletions**
|
||||||
|
|
||||||
|
**Linear History**:
|
||||||
|
- ✅ Require linear history (or use squash merging)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `develop` Branch (If Using GitFlow)
|
||||||
|
|
||||||
|
**Optional Settings**:
|
||||||
|
- ✅ Require pull request
|
||||||
|
- ✅ Require status checks
|
||||||
|
- ✅ **Allow force pushes** (for rebasing - use with caution)
|
||||||
|
- Approvals: 0-1 (more flexible than `main`)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `claude/*` Branches (AI Agent Branches)
|
||||||
|
|
||||||
|
**Special Settings**:
|
||||||
|
- ✅ Allow direct commits (AI agents commit directly)
|
||||||
|
- ✅ Require status checks to pass
|
||||||
|
- ❌ No protection rules (temporary branches, auto-deleted after PR merge)
|
||||||
|
|
||||||
|
**Naming Convention**:
|
||||||
|
- `claude/feature-name-{session-id}`
|
||||||
|
- Session ID ensures unique branch names per AI session
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Required Status Checks
|
||||||
|
|
||||||
|
### Current Workflows
|
||||||
|
|
||||||
|
From `.github/workflows/`:
|
||||||
|
|
||||||
|
| Workflow | File | Triggers | Required Checks |
|
||||||
|
|----------|------|----------|----------------|
|
||||||
|
| **CI** | `ci.yml` | Push to `main`, PR | `lint`, `type-check`, `build` |
|
||||||
|
| **Backend Tests** | `backend-tests.yml` | Push to `backend/**`, PR | `test-backend` |
|
||||||
|
| **Railway Deploy** | `railway-deploy.yml` | Push to `main` | (deployment only, not blocking) |
|
||||||
|
| **GitHub Pages Deploy** | `deploy.yml` | Push to `main` | (deployment only) |
|
||||||
|
| **Railway Secrets Audit** | `railway-automation.yml` | Schedule (nightly) | (audit only) |
|
||||||
|
| **Domain Sync** | `sync-domains.yml` | Manual, schedule | (sync only) |
|
||||||
|
| **Domain Health** | `domain-health.yml` | Schedule (hourly) | (monitoring only) |
|
||||||
|
|
||||||
|
### Adding Checks to Branch Protection
|
||||||
|
|
||||||
|
**Via GitHub UI**:
|
||||||
|
1. Go to Settings → Branches → Branch protection rules
|
||||||
|
2. Click `main` (or create new)
|
||||||
|
3. Under "Require status checks to pass before merging":
|
||||||
|
- ✅ Require status checks
|
||||||
|
- Search and add: `CI / lint`, `CI / type-check`, `CI / test-backend`, `CI / build`
|
||||||
|
- ✅ Require branches to be up to date
|
||||||
|
|
||||||
|
**Via GitHub API** (automation):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
gh api \
|
||||||
|
--method PUT \
|
||||||
|
-H "Accept: application/vnd.github+json" \
|
||||||
|
/repos/blackboxprogramming/BlackRoad-Operating-System/branches/main/protection \
|
||||||
|
-f required_status_checks='{"strict":true,"contexts":["CI / lint","CI / type-check","CI / test-backend","CI / build"]}' \
|
||||||
|
-f enforce_admins=false \
|
||||||
|
-f required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}' \
|
||||||
|
-f restrictions=null \
|
||||||
|
-f required_conversation_resolution=true
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CODEOWNERS File
|
||||||
|
|
||||||
|
**Location**: `.github/CODEOWNERS`
|
||||||
|
|
||||||
|
**Already Created**: See `.github/CODEOWNERS` in this repo
|
||||||
|
|
||||||
|
**How it Works**:
|
||||||
|
- When PR changes files, GitHub auto-requests review from owners
|
||||||
|
- PR can't merge until Code Owner approves (if "Require review from Code Owners" is enabled)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pull Request Templates
|
||||||
|
|
||||||
|
**Location**: `.github/PULL_REQUEST_TEMPLATE.md`
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Description
|
||||||
|
<!-- Provide a clear description of the changes in this PR -->
|
||||||
|
|
||||||
|
## Type of Change
|
||||||
|
<!-- Check all that apply -->
|
||||||
|
- [ ] Bug fix (non-breaking change which fixes an issue)
|
||||||
|
- [ ] New feature (non-breaking change which adds functionality)
|
||||||
|
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
|
||||||
|
- [ ] Documentation update
|
||||||
|
- [ ] Infrastructure change
|
||||||
|
|
||||||
|
## Related Issue
|
||||||
|
<!-- Link to related issue: Closes #123 -->
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
<!-- Describe how you tested these changes -->
|
||||||
|
- [ ] Tested locally
|
||||||
|
- [ ] Added/updated unit tests
|
||||||
|
- [ ] Added/updated integration tests
|
||||||
|
- [ ] Tested in staging environment
|
||||||
|
|
||||||
|
## Screenshots (if applicable)
|
||||||
|
<!-- Add screenshots for UI changes -->
|
||||||
|
|
||||||
|
## Checklist
|
||||||
|
- [ ] Code follows the project's style guidelines
|
||||||
|
- [ ] Self-review of code completed
|
||||||
|
- [ ] Comments added for complex logic
|
||||||
|
- [ ] Documentation updated (if needed)
|
||||||
|
- [ ] No new warnings generated
|
||||||
|
- [ ] Tests pass locally
|
||||||
|
- [ ] Related documentation updated
|
||||||
|
|
||||||
|
## Deployment Notes
|
||||||
|
<!-- Any special steps needed for deployment? -->
|
||||||
|
```
|
||||||
|
|
||||||
|
**Create file**: `.github/PULL_REQUEST_TEMPLATE.md` with above content
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Issue Templates
|
||||||
|
|
||||||
|
**Location**: `.github/ISSUE_TEMPLATE/`
|
||||||
|
|
||||||
|
### 1. Bug Report
|
||||||
|
|
||||||
|
**File**: `.github/ISSUE_TEMPLATE/bug_report.md`
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
name: Bug Report
|
||||||
|
about: Report a bug in BlackRoad OS
|
||||||
|
title: "[BUG] "
|
||||||
|
labels: bug
|
||||||
|
assignees: ''
|
||||||
|
---
|
||||||
|
|
||||||
|
## Bug Description
|
||||||
|
<!-- Clear description of the bug -->
|
||||||
|
|
||||||
|
## Steps to Reproduce
|
||||||
|
1. Go to '...'
|
||||||
|
2. Click on '...'
|
||||||
|
3. Scroll down to '...'
|
||||||
|
4. See error
|
||||||
|
|
||||||
|
## Expected Behavior
|
||||||
|
<!-- What should happen -->
|
||||||
|
|
||||||
|
## Actual Behavior
|
||||||
|
<!-- What actually happens -->
|
||||||
|
|
||||||
|
## Environment
|
||||||
|
- **BlackRoad OS Version**: [e.g., v0.1.1]
|
||||||
|
- **Browser**: [e.g., Chrome 120, Safari 17]
|
||||||
|
- **OS**: [e.g., macOS 14, Windows 11, iOS 17]
|
||||||
|
- **Device**: [e.g., Desktop, iPhone 15]
|
||||||
|
|
||||||
|
## Screenshots
|
||||||
|
<!-- If applicable, add screenshots -->
|
||||||
|
|
||||||
|
## Additional Context
|
||||||
|
<!-- Any other context about the problem -->
|
||||||
|
|
||||||
|
## Possible Solution
|
||||||
|
<!-- Optional: suggest a fix if you have ideas -->
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Feature Request
|
||||||
|
|
||||||
|
**File**: `.github/ISSUE_TEMPLATE/feature_request.md`
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
name: Feature Request
|
||||||
|
about: Suggest a new feature for BlackRoad OS
|
||||||
|
title: "[FEATURE] "
|
||||||
|
labels: enhancement
|
||||||
|
assignees: ''
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feature Description
|
||||||
|
<!-- Clear description of the feature you want -->
|
||||||
|
|
||||||
|
## Problem Statement
|
||||||
|
<!-- What problem does this solve? Why is it needed? -->
|
||||||
|
|
||||||
|
## Proposed Solution
|
||||||
|
<!-- How should this feature work? -->
|
||||||
|
|
||||||
|
## Alternatives Considered
|
||||||
|
<!-- What other solutions have you thought about? -->
|
||||||
|
|
||||||
|
## Additional Context
|
||||||
|
<!-- Mockups, examples, links, etc. -->
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
<!-- How will we know this feature is complete? -->
|
||||||
|
- [ ] Criterion 1
|
||||||
|
- [ ] Criterion 2
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Documentation
|
||||||
|
|
||||||
|
**File**: `.github/ISSUE_TEMPLATE/documentation.md`
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
name: Documentation
|
||||||
|
about: Suggest documentation improvements
|
||||||
|
title: "[DOCS] "
|
||||||
|
labels: documentation
|
||||||
|
assignees: ''
|
||||||
|
---
|
||||||
|
|
||||||
|
## Documentation Issue
|
||||||
|
<!-- What's missing, unclear, or incorrect in the docs? -->
|
||||||
|
|
||||||
|
## Affected Pages/Sections
|
||||||
|
<!-- Link to the docs that need updating -->
|
||||||
|
|
||||||
|
## Suggested Changes
|
||||||
|
<!-- What should be added/changed? -->
|
||||||
|
|
||||||
|
## Additional Context
|
||||||
|
<!-- Any examples, screenshots, or references -->
|
||||||
|
```
|
||||||
|
|
||||||
|
**Create these files** in `.github/ISSUE_TEMPLATE/`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project Boards
|
||||||
|
|
||||||
|
### Org-Level Project Board
|
||||||
|
|
||||||
|
**Name**: "BlackRoad OS Roadmap"
|
||||||
|
|
||||||
|
**View Type**: Board
|
||||||
|
|
||||||
|
**Columns**:
|
||||||
|
|
||||||
|
| Column | Description | Automation |
|
||||||
|
|--------|-------------|------------|
|
||||||
|
| 📋 Backlog | All new issues, not yet prioritized | Auto-add: new issues |
|
||||||
|
| 🎯 Phase 1 (Prove the OS) | Q1-Q4 deliverables | Auto-add: label `Phase 1` |
|
||||||
|
| 🚀 Phase 2 (Expand Intelligence) | Q5-Q6 deliverables | Auto-add: label `Phase 2` |
|
||||||
|
| 🌍 Phase 3 (Ecosystem) | Q7-Q8 deliverables | Auto-add: label `Phase 3` |
|
||||||
|
| 🏃 In Progress | Currently being worked on | Auto-add: assigned + status `in progress` |
|
||||||
|
| 👀 In Review | PR submitted, awaiting review | Auto-add: PR opened |
|
||||||
|
| ✅ Done | Completed | Auto-add: PR merged, issue closed |
|
||||||
|
|
||||||
|
**Automation Rules**:
|
||||||
|
- Issue created → add to "Backlog"
|
||||||
|
- Issue labeled `Phase 1` → move to "Phase 1" column
|
||||||
|
- Issue assigned → move to "In Progress"
|
||||||
|
- PR opened → move to "In Review"
|
||||||
|
- PR merged → move to "Done"
|
||||||
|
- Issue closed → move to "Done"
|
||||||
|
|
||||||
|
**Create via GitHub UI**:
|
||||||
|
1. Go to Organization → Projects → New project
|
||||||
|
2. Choose "Board" template
|
||||||
|
3. Add columns above
|
||||||
|
4. Configure automation (Settings → Workflows)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Labels
|
||||||
|
|
||||||
|
**Standard Labels** (auto-created by GitHub):
|
||||||
|
|
||||||
|
| Label | Color | Description |
|
||||||
|
|-------|-------|-------------|
|
||||||
|
| `bug` | Red | Something isn't working |
|
||||||
|
| `documentation` | Blue | Improvements or additions to documentation |
|
||||||
|
| `duplicate` | Gray | This issue or PR already exists |
|
||||||
|
| `enhancement` | Green | New feature or request |
|
||||||
|
| `good first issue` | Purple | Good for newcomers |
|
||||||
|
| `help wanted` | Orange | Extra attention is needed |
|
||||||
|
| `invalid` | Gray | This doesn't seem right |
|
||||||
|
| `question` | Pink | Further information is requested |
|
||||||
|
| `wontfix` | White | This will not be worked on |
|
||||||
|
|
||||||
|
**Custom Labels** (add these):
|
||||||
|
|
||||||
|
| Label | Color | Description |
|
||||||
|
|-------|-------|-------------|
|
||||||
|
| `Phase 1` | `#0E8A16` | Phase 1: Prove the OS (Months 0-12) |
|
||||||
|
| `Phase 2` | `#1D76DB` | Phase 2: Expand Intelligence (Months 12-18) |
|
||||||
|
| `Phase 3` | `#5319E7` | Phase 3: Ecosystem (Months 18-24+) |
|
||||||
|
| `backend` | `#D93F0B` | Backend (FastAPI, Python) |
|
||||||
|
| `frontend` | `#FBCA04` | Frontend (OS, UI, JavaScript) |
|
||||||
|
| `infrastructure` | `#0052CC` | Infrastructure, DevOps, CI/CD |
|
||||||
|
| `agent` | `#C5DEF5` | Agent-related (Prism, Lucidia, Operator) |
|
||||||
|
| `security` | `#B60205` | Security issue or enhancement |
|
||||||
|
| `performance` | `#D4C5F9` | Performance improvement |
|
||||||
|
| `breaking-change` | `#D93F0B` | Breaking change (major version bump) |
|
||||||
|
|
||||||
|
**Create via GitHub UI**: Settings → Labels → New label
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Recommended Workflow Additions
|
||||||
|
|
||||||
|
### 1. PR Labeler
|
||||||
|
|
||||||
|
**File**: `.github/workflows/pr-labeler.yml`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: PR Labeler
|
||||||
|
on:
|
||||||
|
pull_request:
|
||||||
|
types: [opened, synchronize]
|
||||||
|
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
pull-requests: write
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
label:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- uses: actions/labeler@v4
|
||||||
|
with:
|
||||||
|
repo-token: ${{ secrets.GITHUB_TOKEN }}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Config**: `.github/labeler.yml`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
backend:
|
||||||
|
- backend/**/*
|
||||||
|
|
||||||
|
frontend:
|
||||||
|
- blackroad-os/**/*
|
||||||
|
- backend/static/**/*
|
||||||
|
|
||||||
|
infrastructure:
|
||||||
|
- .github/**/*
|
||||||
|
- scripts/**/*
|
||||||
|
- ops/**/*
|
||||||
|
- infra/**/*
|
||||||
|
- railway.*
|
||||||
|
- docker-compose.yml
|
||||||
|
|
||||||
|
documentation:
|
||||||
|
- docs/**/*
|
||||||
|
- '**/*.md'
|
||||||
|
|
||||||
|
agent:
|
||||||
|
- agents/**/*
|
||||||
|
- blackroad-universe/prompts/**/*
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Dependabot
|
||||||
|
|
||||||
|
**File**: `.github/dependabot.yml`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
version: 2
|
||||||
|
updates:
|
||||||
|
# Backend Python dependencies
|
||||||
|
- package-ecosystem: "pip"
|
||||||
|
directory: "/backend"
|
||||||
|
schedule:
|
||||||
|
interval: "weekly"
|
||||||
|
open-pull-requests-limit: 5
|
||||||
|
labels:
|
||||||
|
- "dependencies"
|
||||||
|
- "backend"
|
||||||
|
|
||||||
|
# GitHub Actions
|
||||||
|
- package-ecosystem: "github-actions"
|
||||||
|
directory: "/"
|
||||||
|
schedule:
|
||||||
|
interval: "weekly"
|
||||||
|
labels:
|
||||||
|
- "dependencies"
|
||||||
|
- "infrastructure"
|
||||||
|
|
||||||
|
# Docker
|
||||||
|
- package-ecosystem: "docker"
|
||||||
|
directory: "/backend"
|
||||||
|
schedule:
|
||||||
|
interval: "weekly"
|
||||||
|
labels:
|
||||||
|
- "dependencies"
|
||||||
|
- "infrastructure"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. CodeQL Security Scanning
|
||||||
|
|
||||||
|
**File**: `.github/workflows/codeql.yml`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: CodeQL Security Scan
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches: [main]
|
||||||
|
pull_request:
|
||||||
|
branches: [main]
|
||||||
|
schedule:
|
||||||
|
- cron: '0 6 * * 1' # Monday 6am
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
analyze:
|
||||||
|
name: Analyze
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
permissions:
|
||||||
|
security-events: write
|
||||||
|
contents: read
|
||||||
|
|
||||||
|
strategy:
|
||||||
|
matrix:
|
||||||
|
language: ['python', 'javascript']
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Initialize CodeQL
|
||||||
|
uses: github/codeql-action/init@v2
|
||||||
|
with:
|
||||||
|
languages: ${{ matrix.language }}
|
||||||
|
|
||||||
|
- name: Autobuild
|
||||||
|
uses: github/codeql-action/autobuild@v2
|
||||||
|
|
||||||
|
- name: Perform CodeQL Analysis
|
||||||
|
uses: github/codeql-action/analyze@v2
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Release Automation
|
||||||
|
|
||||||
|
**File**: `.github/workflows/release.yml`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: Create Release
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
tags:
|
||||||
|
- 'v*.*.*'
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
release:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
permissions:
|
||||||
|
contents: write
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v4
|
||||||
|
with:
|
||||||
|
fetch-depth: 0
|
||||||
|
|
||||||
|
- name: Generate Changelog
|
||||||
|
id: changelog
|
||||||
|
run: |
|
||||||
|
CHANGELOG=$(git log --pretty=format:"- %s (%h)" $(git describe --tags --abbrev=0 HEAD^)..HEAD)
|
||||||
|
echo "changelog<<EOF" >> $GITHUB_OUTPUT
|
||||||
|
echo "$CHANGELOG" >> $GITHUB_OUTPUT
|
||||||
|
echo "EOF" >> $GITHUB_OUTPUT
|
||||||
|
|
||||||
|
- name: Create Release
|
||||||
|
uses: actions/create-release@v1
|
||||||
|
env:
|
||||||
|
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||||
|
with:
|
||||||
|
tag_name: ${{ github.ref_name }}
|
||||||
|
release_name: Release ${{ github.ref_name }}
|
||||||
|
body: |
|
||||||
|
## Changes in this Release
|
||||||
|
${{ steps.changelog.outputs.changelog }}
|
||||||
|
draft: false
|
||||||
|
prerelease: false
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Commit Messages
|
||||||
|
|
||||||
|
**Format**: Conventional Commits
|
||||||
|
|
||||||
|
```
|
||||||
|
<type>(<scope>): <subject>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
|
||||||
|
<footer>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Types**:
|
||||||
|
- `feat`: New feature
|
||||||
|
- `fix`: Bug fix
|
||||||
|
- `docs`: Documentation only
|
||||||
|
- `style`: Formatting, missing semicolons, etc.
|
||||||
|
- `refactor`: Code change that neither fixes a bug nor adds a feature
|
||||||
|
- `perf`: Performance improvement
|
||||||
|
- `test`: Adding or updating tests
|
||||||
|
- `chore`: Maintenance tasks
|
||||||
|
|
||||||
|
**Examples**:
|
||||||
|
```
|
||||||
|
feat(backend): add Prism job queue API endpoint
|
||||||
|
|
||||||
|
Implemented /api/prism/jobs endpoint with pagination,
|
||||||
|
filtering, and sorting. Connects to PostgreSQL for
|
||||||
|
persistent storage.
|
||||||
|
|
||||||
|
Closes #123
|
||||||
|
```
|
||||||
|
|
||||||
|
```
|
||||||
|
fix(os): resolve window z-index bug on minimize
|
||||||
|
|
||||||
|
Windows were not maintaining correct z-order after
|
||||||
|
minimize/restore. Fixed by tracking z-index state
|
||||||
|
in window manager.
|
||||||
|
|
||||||
|
Fixes #456
|
||||||
|
```
|
||||||
|
|
||||||
|
### PR Size
|
||||||
|
|
||||||
|
**Recommendations**:
|
||||||
|
- **Small PRs**: < 200 lines changed (ideal)
|
||||||
|
- **Medium PRs**: 200-500 lines (acceptable)
|
||||||
|
- **Large PRs**: > 500 lines (break into smaller PRs if possible)
|
||||||
|
|
||||||
|
**Exceptions**:
|
||||||
|
- Auto-generated code
|
||||||
|
- Third-party library updates
|
||||||
|
- Large refactors (clearly communicate scope)
|
||||||
|
|
||||||
|
### Code Review Process
|
||||||
|
|
||||||
|
1. **Author**: Create PR, self-review, request reviewers
|
||||||
|
2. **Reviewers**: Review within 24 hours (business days)
|
||||||
|
3. **Author**: Address feedback, update PR
|
||||||
|
4. **Reviewers**: Approve or request changes
|
||||||
|
5. **Author**: Merge (or auto-merge if approved + CI passes)
|
||||||
|
|
||||||
|
**Review Checklist**:
|
||||||
|
- [ ] Code follows style guidelines
|
||||||
|
- [ ] Tests added/updated
|
||||||
|
- [ ] Documentation updated
|
||||||
|
- [ ] No obvious bugs or security issues
|
||||||
|
- [ ] Commit messages are clear
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
### Secret Scanning
|
||||||
|
|
||||||
|
GitHub automatically scans for exposed secrets. Ensure:
|
||||||
|
- ✅ Secret scanning enabled (default for public repos)
|
||||||
|
- ✅ Push protection enabled (blocks commits with secrets)
|
||||||
|
|
||||||
|
### Dependency Scanning
|
||||||
|
|
||||||
|
- ✅ Dependabot alerts enabled
|
||||||
|
- ✅ Weekly dependency updates (via Dependabot)
|
||||||
|
|
||||||
|
### Vulnerability Alerts
|
||||||
|
|
||||||
|
GitHub sends alerts for known vulnerabilities. Ensure:
|
||||||
|
- ✅ Alerts enabled (Settings → Security → Vulnerability alerts)
|
||||||
|
- ✅ Team notified via email/Slack
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Maintenance
|
||||||
|
|
||||||
|
**Weekly**:
|
||||||
|
- Review open PRs (ensure < 5 open)
|
||||||
|
- Review open issues (triage, label, prioritize)
|
||||||
|
- Merge Dependabot PRs (if CI passes)
|
||||||
|
|
||||||
|
**Monthly**:
|
||||||
|
- Review project board (move stale items)
|
||||||
|
- Review labels (add/remove as needed)
|
||||||
|
- Audit branch protection rules
|
||||||
|
|
||||||
|
**Quarterly**:
|
||||||
|
- Review team permissions
|
||||||
|
- Audit CODEOWNERS (update as team changes)
|
||||||
|
- Review workflows (optimize, remove unused)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**This structure ensures a well-organized, scalable GitHub setup for BlackRoad OS.**
|
||||||
1074
MASTER_ORCHESTRATION_PLAN.md
Normal file
1074
MASTER_ORCHESTRATION_PLAN.md
Normal file
File diff suppressed because it is too large
Load Diff
482
NEXT_ACTIONS_ALEXA.md
Normal file
482
NEXT_ACTIONS_ALEXA.md
Normal file
@@ -0,0 +1,482 @@
|
|||||||
|
# 🎯 ALEXA'S NEXT ACTIONS
|
||||||
|
## The No-Overwhelm, Just-Execute Checklist
|
||||||
|
|
||||||
|
**Date:** 2025-11-18
|
||||||
|
**Status:** Ready to Execute
|
||||||
|
**Phase:** Phase 1, Q1 - Foundation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## THE BIG PICTURE IN 3 SENTENCES
|
||||||
|
|
||||||
|
1. You have a **working Windows 95-style OS** with FastAPI backend (it's beautiful!)
|
||||||
|
2. You have **complete vision docs** for the entire BlackRoad ecosystem (The Big Kahuna!)
|
||||||
|
3. Now you need to **solidify infrastructure** and **launch Phase 1** (make it real!)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔥 DO THESE FIRST (Today/This Week)
|
||||||
|
|
||||||
|
### ✅ Infrastructure Foundation
|
||||||
|
|
||||||
|
**Time Estimate**: 2-4 hours total
|
||||||
|
|
||||||
|
#### 1. Migrate blackroad.systems DNS to Cloudflare (1 hour)
|
||||||
|
|
||||||
|
**Why**: Better performance, free SSL, DDoS protection, future-ready
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
```bash
|
||||||
|
# Option A: Manual (easier, recommended for first time)
|
||||||
|
1. Go to cloudflare.com → Log in → "Add a site"
|
||||||
|
2. Enter: blackroad.systems
|
||||||
|
3. Choose Free plan
|
||||||
|
4. Cloudflare scans existing DNS records
|
||||||
|
5. Review/approve records
|
||||||
|
6. Cloudflare shows 2 nameservers (e.g., aaaa.ns.cloudflare.com)
|
||||||
|
7. Go to GoDaddy → My Domains → blackroad.systems → Manage DNS
|
||||||
|
8. Nameservers → Change → Custom
|
||||||
|
9. Enter Cloudflare nameservers
|
||||||
|
10. Save → Wait 5-60 minutes
|
||||||
|
11. Return to Cloudflare → Should say "Active"
|
||||||
|
12. Go to SSL/TLS → Set to "Full (strict)"
|
||||||
|
13. Enable "Always Use HTTPS"
|
||||||
|
Done! ✅
|
||||||
|
|
||||||
|
# Option B: Script (once you're comfortable)
|
||||||
|
export CF_API_TOKEN="your-token"
|
||||||
|
export CF_ZONE_ID="your-zone-id"
|
||||||
|
python scripts/cloudflare/sync_dns.py # (create this from blueprint)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Result**: `blackroad.systems` now served via Cloudflare with free SSL
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 2. Verify Railway Deployment (30 min)
|
||||||
|
|
||||||
|
**Why**: Ensure backend is deployed and healthy
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
```bash
|
||||||
|
# Check current deployment
|
||||||
|
railway status --service backend
|
||||||
|
|
||||||
|
# View logs
|
||||||
|
railway logs --service backend --tail 50
|
||||||
|
|
||||||
|
# Test health endpoint
|
||||||
|
curl https://your-railway-app.up.railway.app/health
|
||||||
|
|
||||||
|
# Expected response:
|
||||||
|
# {"status":"healthy","timestamp":...}
|
||||||
|
|
||||||
|
# Add custom domain (if not already)
|
||||||
|
railway domains add os.blackroad.systems --service backend
|
||||||
|
|
||||||
|
# Test custom domain
|
||||||
|
curl https://os.blackroad.systems/health
|
||||||
|
```
|
||||||
|
|
||||||
|
**Result**: Backend is live, healthy, and accessible via custom domain
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 3. Update GitHub Secrets (15 min)
|
||||||
|
|
||||||
|
**Why**: Enable automated deployments and DNS syncing
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
```bash
|
||||||
|
# Get Railway token
|
||||||
|
railway whoami # Shows current login
|
||||||
|
railway login --browserless # Get new token if needed
|
||||||
|
|
||||||
|
# Get Cloudflare token
|
||||||
|
# Cloudflare dashboard → My Profile → API Tokens → Create Token
|
||||||
|
# Template: "Edit zone DNS" → Select zones: blackroad.systems
|
||||||
|
|
||||||
|
# Add to GitHub
|
||||||
|
gh secret set RAILWAY_TOKEN # Paste Railway token
|
||||||
|
gh secret set CF_API_TOKEN # Paste Cloudflare API token
|
||||||
|
gh secret set CF_ZONE_ID # From Cloudflare dashboard (zone overview)
|
||||||
|
|
||||||
|
# Verify
|
||||||
|
gh secret list
|
||||||
|
```
|
||||||
|
|
||||||
|
**Result**: GitHub Actions can now deploy and manage infrastructure
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 4. Test End-to-End (15 min)
|
||||||
|
|
||||||
|
**Why**: Confirm everything works
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
```bash
|
||||||
|
# 1. Visit OS
|
||||||
|
open https://os.blackroad.systems
|
||||||
|
|
||||||
|
# Should see: Windows 95 desktop, apps load, no errors
|
||||||
|
|
||||||
|
# 2. Test API
|
||||||
|
curl https://os.blackroad.systems/api/docs
|
||||||
|
|
||||||
|
# Should see: FastAPI Swagger docs
|
||||||
|
|
||||||
|
# 3. Check SSL
|
||||||
|
# Browser should show 🔒 (secure)
|
||||||
|
|
||||||
|
# 4. Test deployment
|
||||||
|
git commit --allow-empty -m "test: verify deployment pipeline"
|
||||||
|
git push
|
||||||
|
|
||||||
|
# GitHub Actions should run → deploy to Railway
|
||||||
|
# Check: https://github.com/blackboxprogramming/BlackRoad-Operating-System/actions
|
||||||
|
```
|
||||||
|
|
||||||
|
**Result**: Full stack working (DNS → Cloudflare → Railway → OS)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 DO THESE NEXT (This Week/Next Week)
|
||||||
|
|
||||||
|
### ✅ Product Polish
|
||||||
|
|
||||||
|
**Time Estimate**: 4-8 hours
|
||||||
|
|
||||||
|
#### 5. Fix Any OS Bugs (2-4 hours)
|
||||||
|
|
||||||
|
**Task**: Test all existing apps, fix issues
|
||||||
|
|
||||||
|
**Test Checklist**:
|
||||||
|
- [ ] Desktop icons load
|
||||||
|
- [ ] Windows open/close/minimize/maximize
|
||||||
|
- [ ] Taskbar shows active windows
|
||||||
|
- [ ] Start menu works
|
||||||
|
- [ ] All apps load (Prism, Miners, Finance, etc.)
|
||||||
|
- [ ] Window dragging/resizing works
|
||||||
|
- [ ] Mobile: basic functionality (doesn't have to be perfect)
|
||||||
|
|
||||||
|
**Known Issues** (if any):
|
||||||
|
- Check GitHub issues: `gh issue list`
|
||||||
|
- Create issues for new bugs found
|
||||||
|
|
||||||
|
**Fix Priority**:
|
||||||
|
1. Blocking bugs (app won't load)
|
||||||
|
2. UX bugs (confusing behavior)
|
||||||
|
3. Visual bugs (minor styling)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 6. Add Real Backend Data (2-4 hours)
|
||||||
|
|
||||||
|
**Task**: Connect Prism Console to real API (remove mock data)
|
||||||
|
|
||||||
|
**Current State**: Prism Console uses mock/static data
|
||||||
|
**Target State**: Prism Console fetches from `/api/prism/*`
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
```python
|
||||||
|
# backend/app/routers/prism.py (create if doesn't exist)
|
||||||
|
|
||||||
|
from fastapi import APIRouter, Depends
|
||||||
|
from sqlalchemy.orm import Session
|
||||||
|
from app.database import get_db
|
||||||
|
|
||||||
|
router = APIRouter(prefix="/api/prism", tags=["prism"])
|
||||||
|
|
||||||
|
@router.get("/jobs")
|
||||||
|
async def get_jobs(db: Session = Depends(get_db)):
|
||||||
|
# TODO: Query actual jobs from DB
|
||||||
|
return {
|
||||||
|
"jobs": [
|
||||||
|
{"id": 1, "type": "deploy", "status": "completed"},
|
||||||
|
{"id": 2, "type": "test", "status": "running"},
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
@router.get("/metrics")
|
||||||
|
async def get_metrics():
|
||||||
|
return {
|
||||||
|
"jobs_running": 2,
|
||||||
|
"jobs_completed": 15,
|
||||||
|
"jobs_failed": 1,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Update blackroad-os/js/apps/prism.js
|
||||||
|
// Replace mock data with fetch calls
|
||||||
|
|
||||||
|
async function loadJobs() {
|
||||||
|
const response = await fetch('/api/prism/jobs');
|
||||||
|
const data = await response.json();
|
||||||
|
// Render jobs...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### ✅ Website Launch
|
||||||
|
|
||||||
|
**Time Estimate**: 6-12 hours (can be split over days)
|
||||||
|
|
||||||
|
#### 7. Create blackroad.systems Landing Page (6-8 hours)
|
||||||
|
|
||||||
|
**Task**: MVP corporate site (5 pages)
|
||||||
|
|
||||||
|
**Pages**:
|
||||||
|
1. **Homepage** - Hero, capabilities, CTA
|
||||||
|
2. **Architecture** - System overview, diagrams
|
||||||
|
3. **Solutions** - Financial Services use case
|
||||||
|
4. **Pricing** - 3 tiers (Free, Team, Enterprise)
|
||||||
|
5. **Contact** - Demo request form
|
||||||
|
|
||||||
|
**Option A: Simple HTML** (faster, matches OS aesthetic)
|
||||||
|
- Use Win95 theme (like OS)
|
||||||
|
- Single `index.html` with sections
|
||||||
|
- Deploy to GitHub Pages or Railway
|
||||||
|
|
||||||
|
**Option B: Static Site Generator** (more scalable)
|
||||||
|
- Use Astro, Next.js, or 11ty
|
||||||
|
- Reuse OS components
|
||||||
|
- Deploy to Vercel or GitHub Pages
|
||||||
|
|
||||||
|
**Recommendation**: Start with Option A (faster), upgrade later
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
```bash
|
||||||
|
# 1. Create site directory
|
||||||
|
mkdir -p blackroad-systems-site
|
||||||
|
cd blackroad-systems-site
|
||||||
|
|
||||||
|
# 2. Copy OS theme/styles
|
||||||
|
cp ../blackroad-os/css/os.css ./styles.css
|
||||||
|
|
||||||
|
# 3. Create index.html (use DOMAIN_SPEC.md as guide)
|
||||||
|
|
||||||
|
# 4. Deploy to GitHub Pages
|
||||||
|
gh repo create blackroad-systems-site --public
|
||||||
|
git init && git add . && git commit -m "Initial site"
|
||||||
|
git remote add origin https://github.com/blackboxprogramming/blackroad-systems-site.git
|
||||||
|
git push -u origin main
|
||||||
|
|
||||||
|
# 5. Enable GitHub Pages
|
||||||
|
gh repo edit --enable-pages --pages-branch main
|
||||||
|
|
||||||
|
# 6. Point DNS
|
||||||
|
# Cloudflare: CNAME @ → blackboxprogramming.github.io
|
||||||
|
# GitHub: Add custom domain in repo settings
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 8. Create Developer Docs (4 hours)
|
||||||
|
|
||||||
|
**Task**: Quick start guide for developers
|
||||||
|
|
||||||
|
**Minimum Viable Docs**:
|
||||||
|
1. **README** - What is BlackRoad OS?
|
||||||
|
2. **Quick Start** - Get started in 5 minutes
|
||||||
|
3. **API Reference** - List of endpoints (auto-generated from FastAPI)
|
||||||
|
4. **Examples** - Python & Node code samples
|
||||||
|
|
||||||
|
**Location**: `docs/` directory or separate repo
|
||||||
|
|
||||||
|
**Deploy**: GitHub Pages (blackroad.network)
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
```bash
|
||||||
|
# 1. Use MkDocs or Docusaurus (or just Markdown)
|
||||||
|
cd docs
|
||||||
|
|
||||||
|
# 2. Create pages
|
||||||
|
touch index.md quick-start.md api-reference.md examples.md
|
||||||
|
|
||||||
|
# 3. Deploy to GitHub Pages
|
||||||
|
# (Same as blackroad-systems-site)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📅 DO THESE LATER (Next 2-4 Weeks)
|
||||||
|
|
||||||
|
### ✅ Alpha Launch Prep
|
||||||
|
|
||||||
|
#### 9. Set Up Analytics (1 hour)
|
||||||
|
|
||||||
|
**Task**: Track usage and visitors
|
||||||
|
|
||||||
|
**Tools**:
|
||||||
|
- Google Analytics (easy, free)
|
||||||
|
- PostHog (open-source, privacy-friendly)
|
||||||
|
- Mixpanel (product analytics)
|
||||||
|
|
||||||
|
**Add to**:
|
||||||
|
- blackroad.systems (marketing site)
|
||||||
|
- os.blackroad.systems (OS usage)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 10. Create Discord Community (2 hours)
|
||||||
|
|
||||||
|
**Task**: Launch developer community
|
||||||
|
|
||||||
|
**Steps**:
|
||||||
|
1. Create Discord server
|
||||||
|
2. Set up channels:
|
||||||
|
- #announcements
|
||||||
|
- #general
|
||||||
|
- #help
|
||||||
|
- #showcase
|
||||||
|
- #feedback
|
||||||
|
3. Create roles (Admin, Mod, Alpha Tester, Community)
|
||||||
|
4. Invite first 10-20 alpha testers
|
||||||
|
5. Post welcome message
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 11. Write First Blog Posts (4-6 hours)
|
||||||
|
|
||||||
|
**Task**: Content marketing
|
||||||
|
|
||||||
|
**Topics**:
|
||||||
|
1. "Introducing BlackRoad OS" (launch post)
|
||||||
|
2. "Why Deterministic AI Matters" (thought leadership)
|
||||||
|
3. "Building Auditable AI Systems with RoadChain" (technical deep-dive)
|
||||||
|
|
||||||
|
**Publish on**:
|
||||||
|
- blackroad.systems/blog
|
||||||
|
- Medium
|
||||||
|
- Dev.to
|
||||||
|
- Hacker News (carefully)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### 12. Recruit Alpha Testers (ongoing)
|
||||||
|
|
||||||
|
**Task**: Find first 10-20 users
|
||||||
|
|
||||||
|
**Outreach**:
|
||||||
|
- Personal network
|
||||||
|
- Twitter/X
|
||||||
|
- LinkedIn
|
||||||
|
- Reddit (r/artificial, r/programming - be respectful)
|
||||||
|
- Indie Hackers
|
||||||
|
- Product Hunt (later)
|
||||||
|
|
||||||
|
**Offer**:
|
||||||
|
- Free early access
|
||||||
|
- Direct line to founder (you!)
|
||||||
|
- Influence product direction
|
||||||
|
- Credits/recognition
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 SUCCESS METRICS (How You Know It's Working)
|
||||||
|
|
||||||
|
### Week 1 Success:
|
||||||
|
- ✅ Infrastructure solid (Cloudflare, Railway, GitHub)
|
||||||
|
- ✅ OS accessible at os.blackroad.systems
|
||||||
|
- ✅ No major bugs blocking usage
|
||||||
|
|
||||||
|
### Week 2-3 Success:
|
||||||
|
- ✅ blackroad.systems live (even if simple)
|
||||||
|
- ✅ Developer docs live
|
||||||
|
- ✅ First 5-10 alpha testers signed up
|
||||||
|
|
||||||
|
### Week 4 Success:
|
||||||
|
- ✅ First 3 users actively using OS
|
||||||
|
- ✅ Feedback collected
|
||||||
|
- ✅ First iteration of improvements deployed
|
||||||
|
|
||||||
|
### Month 2-3 Success:
|
||||||
|
- ✅ 20-50 developers signed up
|
||||||
|
- ✅ First design partner conversation started
|
||||||
|
- ✅ Blog posts published, some traction
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 THE MANTRA
|
||||||
|
|
||||||
|
**Focus on**:
|
||||||
|
1. **Infrastructure first** (solid foundation)
|
||||||
|
2. **Product polish** (it has to work)
|
||||||
|
3. **Simple messaging** (clear value prop)
|
||||||
|
4. **Real users** (even if just 5)
|
||||||
|
|
||||||
|
**Avoid**:
|
||||||
|
- Building everything at once
|
||||||
|
- Perfectionism (ship v1, iterate)
|
||||||
|
- Distractions (shiny new features)
|
||||||
|
|
||||||
|
**Remember**:
|
||||||
|
- Phase 1 is about **proving it works**
|
||||||
|
- You need **5 design partners**, not 500
|
||||||
|
- **Traction > polish** in early days
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠️ TOOLS & RESOURCES
|
||||||
|
|
||||||
|
**Bookmarks**:
|
||||||
|
- Cloudflare Dashboard: https://dash.cloudflare.com
|
||||||
|
- Railway Dashboard: https://railway.app/dashboard
|
||||||
|
- GitHub Repo: https://github.com/blackboxprogramming/BlackRoad-Operating-System
|
||||||
|
- GitHub Actions: https://github.com/blackboxprogramming/BlackRoad-Operating-System/actions
|
||||||
|
|
||||||
|
**Docs Created**:
|
||||||
|
- `/MASTER_ORCHESTRATION_PLAN.md` - Complete master plan
|
||||||
|
- `/infra/cloudflare/CLOUDFLARE_DNS_BLUEPRINT.md` - DNS setup guide
|
||||||
|
- `/.github/GITHUB_ENTERPRISE_SETUP.md` - GitHub org structure
|
||||||
|
- `/.github/CODEOWNERS` - Code ownership
|
||||||
|
- `/NEXT_ACTIONS_ALEXA.md` - This file!
|
||||||
|
|
||||||
|
**Reference Docs**:
|
||||||
|
- `/BLACKROAD_OS_BIG_KAHUNA_VISION.md` - Complete OS vision
|
||||||
|
- `/blackroad-universe/operations/roadmap/EXECUTION_ROADMAP.md` - 18-24 month roadmap
|
||||||
|
- `/blackroad-universe/brand/architecture/BRAND_ARCHITECTURE.md` - Brand strategy
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💬 WHEN YOU'RE STUCK
|
||||||
|
|
||||||
|
**Question**: "Which task should I do next?"
|
||||||
|
**Answer**: Look at this file, pick the next unchecked item in order
|
||||||
|
|
||||||
|
**Question**: "This is overwhelming"
|
||||||
|
**Answer**: Just do #1 (Cloudflare DNS). Then #2. One at a time.
|
||||||
|
|
||||||
|
**Question**: "Something broke"
|
||||||
|
**Answer**: Check Railway logs: `railway logs --service backend --tail 100`
|
||||||
|
|
||||||
|
**Question**: "I need help with X"
|
||||||
|
**Answer**: Ask Claude! Or check docs. Or Discord community (once launched).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎉 CELEBRATE WINS
|
||||||
|
|
||||||
|
**After Week 1**: Infrastructure is solid! 🎊
|
||||||
|
**After Week 2**: Sites are live! 🚀
|
||||||
|
**After Week 3**: First users! 🌟
|
||||||
|
**After Month 1**: Momentum building! 💪
|
||||||
|
**After Month 3**: Real traction! 🔥
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Ready to build the road, Operator?**
|
||||||
|
|
||||||
|
**Your first action**: Item #1 (Cloudflare DNS migration)
|
||||||
|
|
||||||
|
**Your north star**: Phase 1, Q1 - Prove the OS works
|
||||||
|
|
||||||
|
**Your superpower**: You've already built the foundation. Now make it real.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*"Not just infrastructure. Not just intelligence. A constellation."*
|
||||||
|
|
||||||
|
**Where AI meets the open road.** 🛣️
|
||||||
523
infra/cloudflare/CLOUDFLARE_DNS_BLUEPRINT.md
Normal file
523
infra/cloudflare/CLOUDFLARE_DNS_BLUEPRINT.md
Normal file
@@ -0,0 +1,523 @@
|
|||||||
|
# Cloudflare DNS Blueprint
|
||||||
|
## Complete DNS Configuration for BlackRoad Universe
|
||||||
|
|
||||||
|
**Version:** 1.0
|
||||||
|
**Date:** 2025-11-18
|
||||||
|
**Purpose:** Canonical DNS configuration for all BlackRoad domains via Cloudflare
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This document provides the complete DNS setup for migrating all BlackRoad domains from GoDaddy DNS to Cloudflare DNS.
|
||||||
|
|
||||||
|
**Why Cloudflare?**
|
||||||
|
- Free tier includes: DNS, SSL, CDN, DDoS protection, Web Analytics
|
||||||
|
- Global anycast network (faster DNS resolution)
|
||||||
|
- CNAME flattening (allows root domain CNAMEs to Railway)
|
||||||
|
- Better security (WAF, rate limiting available)
|
||||||
|
- Future-ready for Workers, Zero Trust, edge functions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Migration Process
|
||||||
|
|
||||||
|
### Step 1: Add Domain to Cloudflare
|
||||||
|
|
||||||
|
For each domain:
|
||||||
|
|
||||||
|
1. **Log in to Cloudflare dashboard**
|
||||||
|
2. Click **"Add a site"**
|
||||||
|
3. Enter domain (e.g., `blackroad.systems`)
|
||||||
|
4. Select **Free plan**
|
||||||
|
5. Cloudflare auto-scans existing DNS records from GoDaddy
|
||||||
|
6. Review scanned records, make adjustments (see configurations below)
|
||||||
|
7. Cloudflare provides 2 nameservers (e.g., `aaaa.ns.cloudflare.com`, `bbbb.ns.cloudflare.com`)
|
||||||
|
|
||||||
|
### Step 2: Update Nameservers at GoDaddy
|
||||||
|
|
||||||
|
For each domain:
|
||||||
|
|
||||||
|
1. **Log in to GoDaddy**
|
||||||
|
2. Go to **My Domains** → select domain → **Manage DNS**
|
||||||
|
3. Scroll to **Nameservers** section
|
||||||
|
4. Click **Change** → Select **Custom**
|
||||||
|
5. Enter Cloudflare nameservers (from Step 1)
|
||||||
|
6. Click **Save**
|
||||||
|
7. **Wait 5-60 minutes** for DNS propagation
|
||||||
|
|
||||||
|
### Step 3: Verify & Configure SSL
|
||||||
|
|
||||||
|
1. Return to Cloudflare dashboard
|
||||||
|
2. Wait for status to change from "Pending" to **"Active"**
|
||||||
|
3. Go to **SSL/TLS** → Set encryption mode to **"Full (strict)"**
|
||||||
|
4. Go to **SSL/TLS** → **Edge Certificates** → Enable **"Always Use HTTPS"**
|
||||||
|
5. Enable **"Automatic HTTPS Rewrites"**
|
||||||
|
6. Enable **"HTTP Strict Transport Security (HSTS)"** (optional, but recommended)
|
||||||
|
|
||||||
|
### Step 4: Optimize Performance
|
||||||
|
|
||||||
|
1. Go to **Speed** → **Optimization**
|
||||||
|
2. Enable **Auto Minify** (HTML, CSS, JS)
|
||||||
|
3. Enable **Brotli** compression
|
||||||
|
4. Enable **Rocket Loader** (optional - test first)
|
||||||
|
5. Go to **Caching** → Set **Browser Cache TTL** to "Respect Existing Headers"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## DNS Records Configuration
|
||||||
|
|
||||||
|
### Domain: blackroad.systems
|
||||||
|
|
||||||
|
**Purpose**: Flagship corporate site + OS application
|
||||||
|
|
||||||
|
| Type | Name | Target | TTL | Proxy | Notes |
|
||||||
|
|------|------|--------|-----|-------|-------|
|
||||||
|
| CNAME | @ | `blackroad-os-production.up.railway.app` | Auto | ✅ Proxied | Root domain → Railway (CNAME flattening) |
|
||||||
|
| CNAME | www | `blackroad.systems` | Auto | ✅ Proxied | www redirects to apex |
|
||||||
|
| CNAME | os | `blackroad.systems` | Auto | ✅ Proxied | Alternative OS alias |
|
||||||
|
| CNAME | api | `blackroad-os-production.up.railway.app` | Auto | ✅ Proxied | Explicit API subdomain |
|
||||||
|
| CNAME | prism | `blackroad-os-production.up.railway.app` | Auto | ✅ Proxied | Prism Console subdomain |
|
||||||
|
| CNAME | docs | `blackboxprogramming.github.io` | Auto | ✅ Proxied | GitHub Pages for docs |
|
||||||
|
| CNAME | cdn | `blackroad.systems` | Auto | ✅ Proxied | CDN alias (for future asset delivery) |
|
||||||
|
| TXT | @ | `v=spf1 include:_spf.google.com ~all` | Auto | - | SPF record (if using Google Workspace) |
|
||||||
|
| MX | @ | `1 aspmx.l.google.com` | Auto | - | Gmail MX (priority 1) |
|
||||||
|
| MX | @ | `5 alt1.aspmx.l.google.com` | Auto | - | Gmail MX (priority 5) |
|
||||||
|
| MX | @ | `5 alt2.aspmx.l.google.com` | Auto | - | Gmail MX (priority 5) |
|
||||||
|
|
||||||
|
**Page Rules** (Optional):
|
||||||
|
- `www.blackroad.systems/*` → Forwarding URL (301) → `https://blackroad.systems/$1`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Domain: blackroad.ai
|
||||||
|
|
||||||
|
**Purpose**: Product console, admin interface
|
||||||
|
|
||||||
|
| Type | Name | Target | TTL | Proxy | Notes |
|
||||||
|
|------|------|--------|-----|-------|-------|
|
||||||
|
| CNAME | @ | `os.blackroad.systems` | Auto | ✅ Proxied | Alias to main OS |
|
||||||
|
| CNAME | www | `blackroad.ai` | Auto | ✅ Proxied | www → apex redirect |
|
||||||
|
| CNAME | console | `os.blackroad.systems` | Auto | ✅ Proxied | Explicit console subdomain |
|
||||||
|
|
||||||
|
**Page Rules**:
|
||||||
|
- `www.blackroad.ai/*` → Forwarding URL (301) → `https://blackroad.ai/$1`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Domain: blackroad.network
|
||||||
|
|
||||||
|
**Purpose**: Developer hub, documentation, community
|
||||||
|
|
||||||
|
| Type | Name | Target | TTL | Proxy | Notes |
|
||||||
|
|------|------|--------|-----|-------|-------|
|
||||||
|
| CNAME | @ | `blackboxprogramming.github.io` | Auto | ✅ Proxied | GitHub Pages for docs |
|
||||||
|
| CNAME | www | `blackroad.network` | Auto | ✅ Proxied | www → apex redirect |
|
||||||
|
| CNAME | api | `blackroad-os-production.up.railway.app` | Auto | ✅ Proxied | API access for developers |
|
||||||
|
| CNAME | sandbox | `blackroad-os-staging.up.railway.app` | Auto | ✅ Proxied | Staging/sandbox environment |
|
||||||
|
|
||||||
|
**CNAME File** (for GitHub Pages):
|
||||||
|
Create file `CNAME` in your `docs/` or GitHub Pages root:
|
||||||
|
```
|
||||||
|
blackroad.network
|
||||||
|
```
|
||||||
|
|
||||||
|
**Page Rules**:
|
||||||
|
- `www.blackroad.network/*` → Forwarding URL (301) → `https://blackroad.network/$1`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Domain: blackroad.me
|
||||||
|
|
||||||
|
**Purpose**: Personal identity portal, Pocket OS
|
||||||
|
|
||||||
|
| Type | Name | Target | TTL | Proxy | Notes |
|
||||||
|
|------|------|--------|-----|-------|-------|
|
||||||
|
| CNAME | @ | `os.blackroad.systems` | Auto | ✅ Proxied | Identity portal via main OS |
|
||||||
|
| CNAME | www | `blackroad.me` | Auto | ✅ Proxied | www → apex redirect |
|
||||||
|
| CNAME | id | `os.blackroad.systems` | Auto | ✅ Proxied | Explicit identity subdomain |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Domain: lucidia.earth
|
||||||
|
|
||||||
|
**Purpose**: Narrative experiences, interactive storytelling (Phase 2)
|
||||||
|
|
||||||
|
| Type | Name | Target | TTL | Proxy | Notes |
|
||||||
|
|------|------|--------|-----|-------|-------|
|
||||||
|
| CNAME | @ | `blackboxprogramming.github.io` | Auto | ✅ Proxied | GitHub Pages (Phase 2) |
|
||||||
|
| CNAME | www | `lucidia.earth` | Auto | ✅ Proxied | www → apex redirect |
|
||||||
|
| CNAME | studio | `lucidia-studio.vercel.app` | Auto | ✅ Proxied | Lucidia Studio (Phase 3) |
|
||||||
|
|
||||||
|
**CNAME File** (for GitHub Pages):
|
||||||
|
```
|
||||||
|
lucidia.earth
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Domain: aliceqi.com
|
||||||
|
|
||||||
|
**Purpose**: ALICE QI research showcase (Phase 2)
|
||||||
|
|
||||||
|
| Type | Name | Target | TTL | Proxy | Notes |
|
||||||
|
|------|------|--------|-----|-------|-------|
|
||||||
|
| CNAME | @ | `blackboxprogramming.github.io` | Auto | ✅ Proxied | GitHub Pages |
|
||||||
|
| CNAME | www | `aliceqi.com` | Auto | ✅ Proxied | www → apex redirect |
|
||||||
|
| CNAME | research | `aliceqi.com` | Auto | ✅ Proxied | Research portal |
|
||||||
|
| CNAME | docs | `aliceqi.com` | Auto | ✅ Proxied | Technical documentation |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Domain: blackroadqi.com
|
||||||
|
|
||||||
|
**Purpose**: Financial/quantitative intelligence product (Phase 2)
|
||||||
|
|
||||||
|
| Type | Name | Target | TTL | Proxy | Notes |
|
||||||
|
|------|------|--------|-----|-------|-------|
|
||||||
|
| CNAME | @ | `blackroadqi-app.up.railway.app` | Auto | ✅ Proxied | Dedicated QI app (Phase 2) |
|
||||||
|
| CNAME | www | `blackroadqi.com` | Auto | ✅ Proxied | www → apex redirect |
|
||||||
|
| CNAME | api | `blackroadqi-api.up.railway.app` | Auto | ✅ Proxied | QI API endpoint |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Domain: roadwallet.com
|
||||||
|
|
||||||
|
**Purpose**: Wallet interface (alias to OS)
|
||||||
|
|
||||||
|
| Type | Name | Target | TTL | Proxy | Notes |
|
||||||
|
|------|------|--------|-----|-------|-------|
|
||||||
|
| CNAME | @ | `os.blackroad.systems` | Auto | ✅ Proxied | Alias to main OS wallet |
|
||||||
|
| CNAME | www | `roadwallet.com` | Auto | ✅ Proxied | www → apex redirect |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Domain: aliceos.io
|
||||||
|
|
||||||
|
**Purpose**: Legacy alias (points to main OS)
|
||||||
|
|
||||||
|
| Type | Name | Target | TTL | Proxy | Notes |
|
||||||
|
|------|------|--------|-----|-------|-------|
|
||||||
|
| CNAME | @ | `os.blackroad.systems` | Auto | ✅ Proxied | Legacy domain |
|
||||||
|
| CNAME | www | `aliceos.io` | Auto | ✅ Proxied | www → apex redirect |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Domain: blackroadquantum.com
|
||||||
|
|
||||||
|
**Purpose**: Quantum research hub (Phase 2)
|
||||||
|
|
||||||
|
| Type | Name | Target | TTL | Proxy | Notes |
|
||||||
|
|------|------|--------|-----|-------|-------|
|
||||||
|
| CNAME | @ | `blackboxprogramming.github.io` | Auto | ✅ Proxied | GitHub Pages |
|
||||||
|
| CNAME | www | `blackroadquantum.com` | Auto | ✅ Proxied | www → apex redirect |
|
||||||
|
| CNAME | lab | `quantum-lab.up.railway.app` | Auto | ✅ Proxied | Quantum Lab app (Phase 2) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Advanced Configuration
|
||||||
|
|
||||||
|
### SSL/TLS Settings
|
||||||
|
|
||||||
|
**For all domains**:
|
||||||
|
|
||||||
|
1. **Encryption Mode**: Full (strict)
|
||||||
|
- Cloudflare ↔ Railway: encrypted with valid cert
|
||||||
|
|
||||||
|
2. **Edge Certificates**:
|
||||||
|
- ✅ Always Use HTTPS
|
||||||
|
- ✅ Automatic HTTPS Rewrites
|
||||||
|
- ✅ Certificate Transparency Monitoring
|
||||||
|
- ✅ TLS 1.3 (enabled by default)
|
||||||
|
|
||||||
|
3. **HSTS** (HTTP Strict Transport Security):
|
||||||
|
- ✅ Enable HSTS
|
||||||
|
- Max Age: 6 months (15768000 seconds)
|
||||||
|
- ✅ Include subdomains
|
||||||
|
- ❌ Preload (wait until stable, then enable)
|
||||||
|
|
||||||
|
### Caching Rules
|
||||||
|
|
||||||
|
**Static Assets** (CSS, JS, images):
|
||||||
|
```
|
||||||
|
Cache Level: Standard
|
||||||
|
Browser Cache TTL: Respect Existing Headers
|
||||||
|
Edge Cache TTL: 1 month
|
||||||
|
```
|
||||||
|
|
||||||
|
**API Endpoints** (`/api/*`):
|
||||||
|
```
|
||||||
|
Cache Level: Bypass
|
||||||
|
(Don't cache API responses)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Page Rules Example** (`blackroad.systems`):
|
||||||
|
```
|
||||||
|
Rule 1: *blackroad.systems/api/*
|
||||||
|
- Cache Level: Bypass
|
||||||
|
- Disable Apps
|
||||||
|
- Disable Performance
|
||||||
|
|
||||||
|
Rule 2: *blackroad.systems/*.css
|
||||||
|
- Cache Level: Cache Everything
|
||||||
|
- Edge Cache TTL: 1 month
|
||||||
|
- Browser Cache TTL: 1 day
|
||||||
|
|
||||||
|
Rule 3: *blackroad.systems/*.js
|
||||||
|
- Cache Level: Cache Everything
|
||||||
|
- Edge Cache TTL: 1 month
|
||||||
|
- Browser Cache TTL: 1 day
|
||||||
|
|
||||||
|
Rule 4: www.blackroad.systems/*
|
||||||
|
- Forwarding URL: 301 redirect to https://blackroad.systems/$1
|
||||||
|
```
|
||||||
|
|
||||||
|
### Firewall Rules
|
||||||
|
|
||||||
|
**Block known bots** (optional):
|
||||||
|
```
|
||||||
|
Field: User Agent
|
||||||
|
Operator: contains
|
||||||
|
Value: "BadBot|Scraper|AhrefsBot"
|
||||||
|
Action: Block
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rate Limiting** (protect API):
|
||||||
|
```
|
||||||
|
Field: URI Path
|
||||||
|
Operator: starts with
|
||||||
|
Value: /api/
|
||||||
|
Rate: 100 requests per minute
|
||||||
|
Action: Challenge (CAPTCHA)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Security Headers
|
||||||
|
|
||||||
|
**Via Cloudflare Workers** (optional, advanced):
|
||||||
|
|
||||||
|
Create a Worker to add security headers:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
addEventListener('fetch', event => {
|
||||||
|
event.respondWith(handleRequest(event.request))
|
||||||
|
})
|
||||||
|
|
||||||
|
async function handleRequest(request) {
|
||||||
|
const response = await fetch(request)
|
||||||
|
const newHeaders = new Headers(response.headers)
|
||||||
|
|
||||||
|
// Security headers
|
||||||
|
newHeaders.set('X-Frame-Options', 'DENY')
|
||||||
|
newHeaders.set('X-Content-Type-Options', 'nosniff')
|
||||||
|
newHeaders.set('Referrer-Policy', 'strict-origin-when-cross-origin')
|
||||||
|
newHeaders.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=()')
|
||||||
|
|
||||||
|
return new Response(response.body, {
|
||||||
|
status: response.status,
|
||||||
|
statusText: response.statusText,
|
||||||
|
headers: newHeaders
|
||||||
|
})
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verification Checklist
|
||||||
|
|
||||||
|
After DNS setup for each domain:
|
||||||
|
|
||||||
|
- [ ] **DNS Propagation**: Check with `dig <domain>` or https://dnschecker.org
|
||||||
|
- [ ] **SSL Certificate**: Visit `https://<domain>` - should show valid cert (🔒)
|
||||||
|
- [ ] **WWW Redirect**: Visit `https://www.<domain>` - should redirect to apex
|
||||||
|
- [ ] **HTTP → HTTPS**: Visit `http://<domain>` - should redirect to HTTPS
|
||||||
|
- [ ] **API Endpoint**: Test `curl https://<domain>/health` (if applicable)
|
||||||
|
- [ ] **Cloudflare Analytics**: Check Cloudflare dashboard → Analytics tab
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Automation Script
|
||||||
|
|
||||||
|
**File**: `scripts/cloudflare/sync_dns.py`
|
||||||
|
|
||||||
|
```python
|
||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Sync DNS records from ops/domains.yaml to Cloudflare
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
export CF_API_TOKEN="your-token"
|
||||||
|
export CF_ZONE_ID="your-zone-id"
|
||||||
|
python scripts/cloudflare/sync_dns.py
|
||||||
|
"""
|
||||||
|
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
import yaml
|
||||||
|
import requests
|
||||||
|
from typing import Dict, List
|
||||||
|
|
||||||
|
CF_API_TOKEN = os.getenv("CF_API_TOKEN")
|
||||||
|
CF_ZONE_ID = os.getenv("CF_ZONE_ID")
|
||||||
|
CF_API_BASE = "https://api.cloudflare.com/client/v4"
|
||||||
|
|
||||||
|
def load_domains() -> Dict:
|
||||||
|
"""Load domain config from ops/domains.yaml"""
|
||||||
|
with open("ops/domains.yaml") as f:
|
||||||
|
return yaml.safe_load(f)
|
||||||
|
|
||||||
|
def get_existing_records(zone_id: str) -> List[Dict]:
|
||||||
|
"""Fetch all DNS records for a zone"""
|
||||||
|
url = f"{CF_API_BASE}/zones/{zone_id}/dns_records"
|
||||||
|
headers = {
|
||||||
|
"Authorization": f"Bearer {CF_API_TOKEN}",
|
||||||
|
"Content-Type": "application/json"
|
||||||
|
}
|
||||||
|
response = requests.get(url, headers=headers)
|
||||||
|
response.raise_for_status()
|
||||||
|
return response.json()["result"]
|
||||||
|
|
||||||
|
def create_dns_record(zone_id: str, record: Dict) -> Dict:
|
||||||
|
"""Create a DNS record"""
|
||||||
|
url = f"{CF_API_BASE}/zones/{zone_id}/dns_records"
|
||||||
|
headers = {
|
||||||
|
"Authorization": f"Bearer {CF_API_TOKEN}",
|
||||||
|
"Content-Type": "application/json"
|
||||||
|
}
|
||||||
|
response = requests.post(url, headers=headers, json=record)
|
||||||
|
response.raise_for_status()
|
||||||
|
return response.json()["result"]
|
||||||
|
|
||||||
|
def update_dns_record(zone_id: str, record_id: str, record: Dict) -> Dict:
|
||||||
|
"""Update a DNS record"""
|
||||||
|
url = f"{CF_API_BASE}/zones/{zone_id}/dns_records/{record_id}"
|
||||||
|
headers = {
|
||||||
|
"Authorization": f"Bearer {CF_API_TOKEN}",
|
||||||
|
"Content-Type": "application/json"
|
||||||
|
}
|
||||||
|
response = requests.put(url, headers=headers, json=record)
|
||||||
|
response.raise_for_status()
|
||||||
|
return response.json()["result"]
|
||||||
|
|
||||||
|
def sync_records():
|
||||||
|
"""Sync DNS records from domains.yaml to Cloudflare"""
|
||||||
|
if not CF_API_TOKEN or not CF_ZONE_ID:
|
||||||
|
print("Error: CF_API_TOKEN and CF_ZONE_ID must be set")
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
config = load_domains()
|
||||||
|
existing = get_existing_records(CF_ZONE_ID)
|
||||||
|
|
||||||
|
# Build index of existing records
|
||||||
|
existing_index = {
|
||||||
|
f"{r['type']}:{r['name']}": r for r in existing
|
||||||
|
}
|
||||||
|
|
||||||
|
for domain in config.get("domains", []):
|
||||||
|
if domain.get("mode") != "dns":
|
||||||
|
continue
|
||||||
|
|
||||||
|
record_data = {
|
||||||
|
"type": domain["record"]["type"],
|
||||||
|
"name": domain["name"],
|
||||||
|
"content": domain["record"]["value"],
|
||||||
|
"ttl": 1, # Auto
|
||||||
|
"proxied": True # Enable Cloudflare proxy
|
||||||
|
}
|
||||||
|
|
||||||
|
key = f"{record_data['type']}:{record_data['name']}"
|
||||||
|
|
||||||
|
if key in existing_index:
|
||||||
|
# Update existing
|
||||||
|
record_id = existing_index[key]["id"]
|
||||||
|
print(f"Updating: {key}")
|
||||||
|
update_dns_record(CF_ZONE_ID, record_id, record_data)
|
||||||
|
else:
|
||||||
|
# Create new
|
||||||
|
print(f"Creating: {key}")
|
||||||
|
create_dns_record(CF_ZONE_ID, record_data)
|
||||||
|
|
||||||
|
print("✅ DNS sync complete!")
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
sync_records()
|
||||||
|
```
|
||||||
|
|
||||||
|
**Make executable**:
|
||||||
|
```bash
|
||||||
|
chmod +x scripts/cloudflare/sync_dns.py
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### DNS Not Resolving
|
||||||
|
|
||||||
|
**Problem**: `dig blackroad.systems` returns no results
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. Check nameservers are updated at GoDaddy
|
||||||
|
2. Wait 5-60 minutes for propagation
|
||||||
|
3. Verify zone is "Active" in Cloudflare dashboard
|
||||||
|
4. Check DNS records exist in Cloudflare
|
||||||
|
|
||||||
|
### SSL Certificate Errors
|
||||||
|
|
||||||
|
**Problem**: Browser shows "Not Secure" or certificate error
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. Check SSL/TLS mode is "Full (strict)" in Cloudflare
|
||||||
|
2. Verify Railway app has valid SSL cert
|
||||||
|
3. Check "Always Use HTTPS" is enabled
|
||||||
|
4. Wait a few minutes for edge certificate provisioning
|
||||||
|
|
||||||
|
### Site Not Loading
|
||||||
|
|
||||||
|
**Problem**: Domain resolves but site doesn't load
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. Check Railway app is deployed and healthy
|
||||||
|
2. Verify custom domain is added in Railway dashboard
|
||||||
|
3. Check Railway logs for errors: `railway logs --service backend`
|
||||||
|
4. Test Railway URL directly (e.g., `your-app.up.railway.app`)
|
||||||
|
|
||||||
|
### Mixed Content Warnings
|
||||||
|
|
||||||
|
**Problem**: Page loads but some assets show as insecure
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. Enable "Automatic HTTPS Rewrites" in Cloudflare
|
||||||
|
2. Update hard-coded `http://` URLs to `https://` in code
|
||||||
|
3. Use protocol-relative URLs: `//example.com/asset.js`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Maintenance
|
||||||
|
|
||||||
|
**Monthly**:
|
||||||
|
- Review Cloudflare analytics
|
||||||
|
- Check SSL certificate status
|
||||||
|
- Review firewall logs (if WAF enabled)
|
||||||
|
|
||||||
|
**Quarterly**:
|
||||||
|
- Audit DNS records (remove unused)
|
||||||
|
- Review page rules and caching
|
||||||
|
- Update security headers if needed
|
||||||
|
|
||||||
|
**Annually**:
|
||||||
|
- Review Cloudflare plan (consider Pro if traffic grows)
|
||||||
|
- Audit all domain registrations (renew at GoDaddy)
|
||||||
|
- Review and update security policies
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- **Cloudflare Docs**: https://developers.cloudflare.com/dns/
|
||||||
|
- **Railway Custom Domains**: https://docs.railway.app/deploy/custom-domains
|
||||||
|
- **DNS Checker**: https://dnschecker.org
|
||||||
|
- **SSL Labs Test**: https://www.ssllabs.com/ssltest/
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**This blueprint ensures all BlackRoad domains are properly configured with Cloudflare for optimal performance, security, and reliability.**
|
||||||
Reference in New Issue
Block a user