madbase/control-plane-api/README.md

# MadBase Control Plane API

Infrastructure automation for MadBase deployments on any VPS provider.

## Features

- 🚀 **Auto-Provisioning** - Automatic server creation on Hetzner Cloud
- 🔄 **Auto-Scaling** - Horizontal scaling with a single API call
- 🛡️ **Data Integrity** - Safe server removal with automatic failover
- 🔐 **Security Hardening** - Firewall, SSH hardening, fail2ban
- 💰 **Cost Optimization** - Plan comparison and cost estimation
- 🌐 **Multi-Provider** - Support for Hetzner, DigitalOcean, Linode, Vultr, and any VPS
- 📊 **Monitoring** - Cluster health tracking via VictoriaMetrics + Loki

## Quick Start (5 minutes)

```bash
# 1. Set up database
createdb madbase_control_plane
psql madbase_control_plane < control-plane-api/migrations/001_initial.sql

# 2. Set environment variables
export DATABASE_URL="postgresql://user:pass@localhost/madbase_control_plane"
export HETZNER_API_KEY="your_hetzner_api_token"

# 3. Run Control Plane API
cd control-plane-api
cargo run --release

# 4. Add your first server
curl -X POST http://localhost:8001/api/v1/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "worker-1",
    "template": "worker-node",
    "provider": "hetzner",
    "plan": "cx11",
    "region": "fsn1"
  }'
``
## Templates

| Template | Description | Min Plan | Cost/Mo |
|----------|-------------|----------|---------|
| `db-node` | PostgreSQL with Patroni HA | CX21 | €6.94 |
| `worker-node` | API worker for scaling | CX11 | €3.69 |
| `control-plane-node` | Management APIs | CX11 | €3.69 |
| `monitoring-node` | VictoriaMetrics + Loki | CX11 | €3.69 |
| `worker-db-combo` | Worker + Database combined | CX31 | €14.21 |
| `worker-monitor-combo` | Worker + Monitoring combined | CX21 | €6.94 |
| `all-in-one` | All services on one node | CX41 | €25.60 |

## API Endpoints

### Servers
- `GET /api/v1/servers` - List all servers
- `POST /api/v1/servers` - Add new server
- `GET /api/v1/servers/{id}` - Get server details
- `DELETE /api/v1/servers/{id}` - Remove server

### Providers
- `GET /api/v1/providers` - List available providers
- `GET /api/v1/providers/{provider}/plans` - Get provider plans
- `GET /api/v1/providers/{provider}/regions` - Get provider regions

### Scaling
- `POST /api/v1/cluster/scale-plan` - Create scaling plan
- `POST /api/v1/cluster/scale-execute` - Execute scaling plan

### Cluster
- `GET /api/v1/cluster/health` - Get cluster health

### Templates
- `GET /api/v1/templates` - List all templates
- `GET /api/v1/templates/{id}` - Get template details

## Documentation

- [Multi-Provider VPS Support](../MULTI_PROVIDER_VPS.md) - Use any VPS provider
- [Hetzner Auto-Scaling Guide](../HETZNER_SCALING.md) - Hetzner-specific scaling
- [Control Plane API Reference](../CONTROL_PLANE_API.md) - Full API documentation
- [Control Plane Quick Start](../CONTROL_PLANE_QUICKSTART.md) - 5-minute setup guide
- [Node Templates](../NODE_TEMPLATES.md) - Template reference
- [Storage Configuration](../STORAGE_CONFIGURATION.md) - S3-compatible storage

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Control Plane API                         │
│  (Server Management | Scaling | Templates | Providers)      │
└──────────────────────┬──────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
        ▼              ▼              ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  Hetzner     │ │  DigitalOcean│ │   Generic    │
│  Provider    │ │  Provider    │ │   Provider   │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
       │                │                │
       ▼                ▼                ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  Server 1    │ │  Server 2    │ │  Server 3    │
│  (worker)    │ │  (database)  │ │  (control)   │
└──────────────┘ └──────────────┘ └──────────────┘
``
## Development

```bash
# Build
cd control-plane-api
cargo build

# Run tests
cargo test

# Run with debug logging
RUST_LOG=control_plane_api=debug cargo run

# Format code
cargo fmt

# Lint
cargo clippy
``
## Deployment

### Docker

```bash
docker build -t madbase/control-plane .
docker run -p 8001:8001 \
  -e DATABASE_URL=$DATABASE_URL \
  -e HETZNER_API_KEY=$HETZNER_API_KEY \
  -e HETZNER_SSH_KEY_PATH=/root/.ssh/id_rsa \
  madbase/control-plane
``
### Docker Compose

```yaml
services:
  control-plane:
    build: ./control-plane-api
    ports:
      - "8001:8001"
    environment:
      - DATABASE_URL=postgresql://madbase:password@db:5432/madbase_control_plane
      - HETZNER_API_KEY=${HETZNER_API_KEY}
    depends_on:
      - db
``
## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `DATABASE_URL` | PostgreSQL connection string | Yes |
| `HETZNER_API_KEY` | Hetzner Cloud API token | Yes (for Hetzner) |
| `HETZNER_SSH_KEY_PATH` | Path to SSH private key | Yes |
| `RUST_LOG` | Log level filter | No (default: info) |

## License

MIT

## Contributing

Contributions welcome! Please read our contributing guidelines.