blackroad-deploy/ARCHITECTURE.md

BlackRoad Deploy Architecture

Overview

Self-hosted deployment platform to replace Railway.

Infrastructure

Deployment Server (DigitalOcean: 159.65.43.12)

• Docker Engine: Run application containers
• Deployment API: REST API for managing deployments
• PostgreSQL: Store deployment metadata, logs, configs
• Caddy: Reverse proxy for deployed services
• Health Monitor: Check service status

Cloudflare Integration

• Tunnel: Secure access to deployment server (no exposed ports)
• DNS: Automatic subdomain creation (*.blackroad.systems)
• KV: Store deployment configs, environment variables
• D1: Alternative database option
• Pages: Host the web dashboard

GitHub Integration

• Webhooks: Auto-deploy on push
• Actions: Optional CI/CD pipelines
• Container Registry: Store Docker images (ghcr.io)

Components

1. Deployment API (blackroad-api)

• Tech: Node.js + Express + TypeScript
• Features:
  • Create/delete/restart deployments
  • Stream logs
  • Manage environment variables
  • Health checks
  • PostgreSQL for persistence

2. CLI Tool (blackroad-cli)

blackroad init          # Initialize project
blackroad deploy        # Deploy current directory
blackroad logs <app>    # Stream logs
blackroad env set KEY=val
blackroad restart <app>
blackroad delete <app>
blackroad status        # List all deployments

3. Web Dashboard

• Tech: React + Vite on Cloudflare Pages
• Features:
  • View all deployments
  • Real-time logs
  • Environment variable management
  • Deployment history
  • Resource usage metrics

Deployment Flow

1. Developer: blackroad deploy
2. CLI:
   • Builds Docker image
   • Pushes to ghcr.io
   • Calls Deployment API
3. API:
   • Pulls image
   • Starts container with env vars
   • Configures Caddy reverse proxy
   • Updates DNS via Cloudflare API
4. Result: App live at <app-name>.blackroad.systems

Data Storage

PostgreSQL Schema

-- deployments
id, name, image, status, created_at, updated_at

-- environment_variables
deployment_id, key, value (encrypted)

-- deployment_logs
deployment_id, timestamp, level, message

-- domains
deployment_id, domain, status

Cloudflare KV

• Deployment configs
• API keys/tokens
• Backup for environment variables

Security

• API Authentication: Bearer tokens (stored in Cloudflare KV)
• Cloudflare Tunnel: No exposed ports on deployment server
• Environment Variables: Encrypted at rest
• Container Isolation: Docker network isolation
• HTTPS: Automatic via Cloudflare

Advantages Over Railway

✅ Full Control: Own your infrastructure ✅ Cost: ~$12/month (DigitalOcean) vs $20-100+ on Railway ✅ Unlimited Projects: No artificial limits ✅ Custom Domains: Free via Cloudflare ✅ Data Ownership: Everything on your server ✅ No Vendor Lock-in: Can migrate anywhere ✅ Integration: Deep Cloudflare + GitHub integration

Next Steps

1. Set up deployment server
2. Build API service
3. Create CLI tool
4. Deploy dashboard
5. Migrate Railway projects