mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 04:57:15 -05:00
abdbc764e6
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
150 lines
2.9 KiB
Markdown
150 lines
2.9 KiB
Markdown
# 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*
|