mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-16 23:57:10 -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
151 lines
2.9 KiB
Markdown
151 lines
2.9 KiB
Markdown
# Service Analysis: Postgres
|
|
|
|
**Status**: ✅ ACTIVE (Production)
|
|
**Last Analyzed**: 2025-11-19
|
|
**Service Type**: Managed Database (PostgreSQL)
|
|
**Provider**: Railway
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Managed PostgreSQL database service provided by Railway. Stores all persistent data for BlackRoad OS including users, wallets, blockchain, and application data.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### Version
|
|
- **PostgreSQL**: 15+ (Railway managed, auto-updates minor versions)
|
|
|
|
### Resources
|
|
- **Storage**: Auto-scaling (starts at 1GB)
|
|
- **Memory**: Shared (Railway managed)
|
|
- **Connections**: Max 100 concurrent
|
|
|
|
### Performance Tuning
|
|
```sql
|
|
-- Current settings (Railway defaults)
|
|
max_connections = 100
|
|
shared_buffers = 256MB
|
|
effective_cache_size = 1GB
|
|
work_mem = 4MB
|
|
maintenance_work_mem = 64MB
|
|
```
|
|
|
|
---
|
|
|
|
## Schema
|
|
|
|
### Current Tables
|
|
- `users` - User accounts (auth, profiles)
|
|
- `wallets` - Blockchain wallets (encrypted keys)
|
|
- `blocks` - RoadChain blockchain
|
|
- `transactions` - Blockchain transactions
|
|
- `jobs` - Prism job queue (future)
|
|
- `events` - Audit/compliance events
|
|
|
|
### Migration Management
|
|
- **Tool**: Alembic
|
|
- **Location**: `backend/alembic/`
|
|
- **Strategy**: Manual migrations (no auto-upgrade in production)
|
|
|
|
---
|
|
|
|
## Backups
|
|
|
|
### Automated Backups (Railway)
|
|
- **Frequency**: Daily
|
|
- **Retention**: 30 days
|
|
- **Storage**: Railway managed
|
|
|
|
### Restore Process
|
|
1. Railway Dashboard → Database → Backups
|
|
2. Select backup date
|
|
3. Click "Restore"
|
|
4. Verify data integrity
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
### Access Control
|
|
- **Network**: Private Railway network only
|
|
- **Credentials**: Auto-generated, injected via `${{Postgres.DATABASE_URL}}`
|
|
- **SSL/TLS**: Enforced
|
|
|
|
### Encryption
|
|
- **At Rest**: Railway managed encryption
|
|
- **In Transit**: SSL/TLS (required)
|
|
|
|
---
|
|
|
|
## Monitoring
|
|
|
|
### Metrics (Railway Dashboard)
|
|
- Connection count
|
|
- Query performance
|
|
- Storage usage
|
|
- CPU/memory usage
|
|
|
|
### Alerts (Recommended)
|
|
- Storage > 80% full
|
|
- Connection pool exhausted
|
|
- Slow queries (> 1s)
|
|
|
|
---
|
|
|
|
## Maintenance
|
|
|
|
### Regular Tasks
|
|
- **Vacuum**: Automatic (Railway managed)
|
|
- **Analyze**: Automatic (Railway managed)
|
|
- **Index optimization**: Manual (as needed)
|
|
|
|
### Scaling
|
|
- **Vertical**: Upgrade Railway plan
|
|
- **Storage**: Auto-scales up to plan limit
|
|
|
|
---
|
|
|
|
## Connection Details
|
|
|
|
### Environment Variable
|
|
```bash
|
|
DATABASE_URL=${{Postgres.DATABASE_URL}}
|
|
# Format: postgresql+asyncpg://user:pass@host:port/db
|
|
```
|
|
|
|
### Connection Pool (SQLAlchemy)
|
|
```python
|
|
# backend/app/database.py
|
|
engine = create_async_engine(
|
|
DATABASE_URL,
|
|
echo=False,
|
|
pool_size=10,
|
|
max_overflow=20,
|
|
pool_pre_ping=True
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Connection Issues
|
|
1. Verify `DATABASE_URL` is set in Railway
|
|
2. Check service logs for connection errors
|
|
3. Verify database service is running
|
|
4. Check connection pool exhaustion
|
|
|
|
### Performance Issues
|
|
1. Check slow query log
|
|
2. Analyze query plans with `EXPLAIN`
|
|
3. Add missing indexes
|
|
4. Optimize N+1 queries
|
|
|
|
---
|
|
|
|
*Analysis Date: 2025-11-19*
|
|
*Next Review: 2025-12-19*
|