mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 05:57:21 -05:00
Establish BlackRoad OS infrastructure control plane
Add comprehensive infrastructure management system to centralize all service definitions, deployment configurations, and operational tooling. ## New Infrastructure Components ### 1. Service Manifest (infra/blackroad-manifest.yml) - Complete catalog of all active and planned services - Deployment configuration for each service - Environment variable definitions - Domain mappings and routing - Database and cache dependencies - Health check endpoints - CI/CD integration specifications ### 2. Operations CLI (scripts/br_ops.py) - Command-line tool for managing all BlackRoad services - Commands: list, env, repo, open, status, health - Reads from service manifest for unified operations - Colored terminal output for better readability ### 3. Service Analysis Documents (infra/analysis/) - Detailed technical analysis for each service - Active services: - blackroad-backend.md (FastAPI backend) - postgres.md (PostgreSQL database) - redis.md (Redis cache) - docs-site.md (MkDocs documentation) - Planned services: - blackroad-api.md (API gateway - Phase 2) - prism-console.md (Admin console - Phase 2) ### 4. Infrastructure Templates (infra/templates/) - railway.toml.template - Railway deployment config - railway.json.template - Alternative Railway config - Dockerfile.fastapi.template - Multi-stage FastAPI Dockerfile - github-workflow-railway-deploy.yml.template - CI/CD workflow - .env.example.template - Comprehensive env var template ### 5. Documentation (infra/README.md) - Complete guide to infrastructure control plane - Usage instructions for ops CLI - Service manifest documentation - Deployment procedures - Troubleshooting guide - Phase 2 migration plan ## Architecture This establishes BlackRoad-Operating-System as the canonical control plane for all BlackRoad services, both current and planned: **Phase 1 (Active)**: - blackroad-backend (FastAPI + static UI) - postgres (Railway managed) - redis (Railway managed) - docs-site (GitHub Pages) **Phase 2 (Planned)**: - blackroad-api (API gateway) - blackroad-prism-console (Admin UI) - blackroad-agents (Orchestration) - blackroad-web (Marketing site) **Phase 3 (Future)**: - lucidia (AI orchestration) - Additional microservices ## Usage # List all services python scripts/br_ops.py list # Show environment variables python scripts/br_ops.py env blackroad-backend # Show repository info python scripts/br_ops.py repo blackroad-backend # Show service URL python scripts/br_ops.py open blackroad-backend prod # Show overall status python scripts/br_ops.py status # Show health checks python scripts/br_ops.py health blackroad-backend ## Benefits 1. **Single Source of Truth**: All service configuration in one manifest 2. **Unified Operations**: One CLI for all services 3. **Documentation**: Comprehensive per-service analysis 4. **Templates**: Reusable infrastructure patterns 5. **Migration Ready**: Clear path to Phase 2 microservices ## References - MASTER_ORCHESTRATION_PLAN.md - 7-layer architecture - ORG_STRUCTURE.md - Repository strategy - PRODUCTION_STACK_AUDIT_2025-11-18.md - Current state Implemented by: Atlas (AI Infrastructure Orchestrator) Date: 2025-11-19
This commit is contained in:
Claude
149
infra/analysis/docs-site.md
Normal file
149
infra/analysis/docs-site.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# Service Analysis: docs-site
|
||||
|
||||
**Status**: ✅ ACTIVE (GitHub Pages)
|
||||
**Last Analyzed**: 2025-11-19
|
||||
**Service Type**: Static Documentation Site
|
||||
**Platform**: GitHub Pages + Cloudflare CDN
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Technical documentation site built with MkDocs Material theme. Deployed to GitHub Pages and served via Cloudflare CDN at `docs.blackroad.systems`.
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack
|
||||
|
||||
### Static Site Generator
|
||||
- **Tool**: MkDocs 1.5+
|
||||
- **Theme**: Material for MkDocs
|
||||
- **Plugins**: search, minify, git-revision-date
|
||||
|
||||
### Build Process
|
||||
```bash
|
||||
cd codex-docs
|
||||
mkdocs build --strict
|
||||
# Output: site/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content Structure
|
||||
|
||||
### Documentation Categories
|
||||
- **Architecture**: System design, decisions, deployment
|
||||
- **API Reference**: Endpoint documentation, schemas
|
||||
- **Guides**: Quickstart, development, deployment
|
||||
- **Agents**: Agent ecosystem, creating agents
|
||||
- **Contributing**: Contribution guidelines
|
||||
|
||||
### Source Location
|
||||
- **Root**: `codex-docs/`
|
||||
- **Config**: `codex-docs/mkdocs.yml`
|
||||
- **Docs**: `codex-docs/docs/`
|
||||
- **Build Output**: `codex-docs/site/` (gitignored)
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
### Platform
|
||||
- **Primary**: GitHub Pages
|
||||
- **Branch**: `gh-pages` (auto-generated)
|
||||
- **CDN**: Cloudflare (proxied)
|
||||
|
||||
### CI/CD
|
||||
```yaml
|
||||
# .github/workflows/docs-deploy.yml
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths: ['codex-docs/**']
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Install dependencies
|
||||
run: pip install mkdocs mkdocs-material
|
||||
- name: Build docs
|
||||
run: cd codex-docs && mkdocs build --strict
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: peaceiris/actions-gh-pages@v3
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./codex-docs/site
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Domain Configuration
|
||||
|
||||
### DNS (Cloudflare)
|
||||
```
|
||||
Type: CNAME
|
||||
Name: docs
|
||||
Value: blackboxprogramming.github.io
|
||||
Proxy: Enabled (Orange cloud)
|
||||
TTL: Auto
|
||||
```
|
||||
|
||||
### GitHub Pages
|
||||
```
|
||||
Repository Settings → Pages
|
||||
Source: gh-pages branch
|
||||
Custom domain: docs.blackroad.systems
|
||||
HTTPS: Enforced
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance
|
||||
|
||||
### Metrics
|
||||
- **Build Time**: ~10-20 seconds
|
||||
- **Deploy Time**: ~30-60 seconds
|
||||
- **Page Load**: < 1s (CDN cached)
|
||||
- **Size**: ~5-10 MB (all pages)
|
||||
|
||||
### Optimizations
|
||||
- Minified HTML/CSS/JS
|
||||
- Image optimization
|
||||
- Cloudflare CDN caching
|
||||
- Gzip compression
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Regular Tasks
|
||||
- Update documentation with code changes
|
||||
- Review for outdated content
|
||||
- Check broken links
|
||||
- Update screenshots
|
||||
|
||||
### Versioning
|
||||
- Current: Single version (latest)
|
||||
- Future: Multi-version support with mike
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Failures
|
||||
1. Check MkDocs config syntax
|
||||
2. Verify all referenced files exist
|
||||
3. Look for broken internal links
|
||||
4. Check plugin compatibility
|
||||
|
||||
### DNS Issues
|
||||
1. Verify CNAME record in Cloudflare
|
||||
2. Check GitHub Pages custom domain setting
|
||||
3. Wait for DNS propagation (up to 24h)
|
||||
|
||||
---
|
||||
|
||||
*Analysis Date: 2025-11-19*
|
||||
*Next Review: 2025-12-19*
|
||||
Reference in New Issue
Block a user