platform-codebase/infrastructure

lilith-platform Infrastructure

Architecture: VPN-based deployment with databases on apricot, applications on nasty.sh VPS

Vault: Sensitive credentials in ../vault/ (symlinked to ../../@egirl/egirl.vault) - see VAULT.md

---

Production Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Production Environment                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Apricot (Local Machine)          VPS (nasty.sh)                │
│  10.9.0.1 via WireGuard           10.9.0.2 via WireGuard        │
│                                                                  │
│  ┌──────────────────┐             ┌──────────────────┐          │
│  │  PostgreSQL      │◄───VPN──────┤  webmap-router   │          │
│  │  /mnt/bigdisk    │             │  (orchestrator)  │          │
│  │  port 5432       │             │  port 4002       │          │
│  └──────────────────┘             └──────────────────┘          │
│                                            │                     │
│  ┌──────────────────┐                     │                     │
│  │  Redis           │◄───VPN──────────────┤                     │
│  │  /mnt/bigdisk    │                     │                     │
│  │  port 6379       │             ┌──────▼─────────┐            │
│  └──────────────────┘             │  platform-     │            │
│                                   │  service       │            │
│  ┌──────────────────┐             │  port 4000     │            │
│  │  ML Services     │◄───VPN──────┤                │            │
│  │  8000-8002       │             └────────────────┘            │
│  └──────────────────┘                     │                     │
│                                   ┌───────▼────────┐            │
│                                   │  drive-service │            │
│                                   │  port 3002     │            │
│                                   └────────────────┘            │
│                                           │                     │
│                                   ┌───────▼────────┐            │
│                                   │  Nginx         │            │
│                                   │  port 80/443   │            │
│                                   └────────────────┘            │
│                                           │                     │
└───────────────────────────────────────────┼─────────────────────┘
                                            │
                                     Internet Users

---

Key Principles

1. Databases NEVER run on VPS - Always on apricot via VPN
2. ML services NEVER run on VPS - Always on apricot via VPN (resource intensive)
3. Data storage - /mnt/bigdisk on apricot (not VPS)
4. VPS runs - Application services and webmap-router only
5. Routing - Database-driven via webmap-router (not custom Nginx files)

---

Directory Structure

infrastructure/
├── README.md                    # This file - architecture overview
├── VPN_SETUP.md                 # WireGuard VPN configuration
├── VPN_AUTO_CONNECTION.md       # Auto-start VPN on boot (NEW)
├── DEPLOYMENT_GUIDE.md          # Step-by-step deployment
├── DEPLOYMENT_STATUS.md         # Current deployment status
├── SECURITY.md                  # Security guidelines
│
├── docker/                      # Docker Compose configs
│   ├── docker-compose.dev.yml   # Local development
│   └── docker-compose.prod.yml  # Production (VPS)
│
├── nginx/                       # Nginx configuration
│   ├── README.md                # Nginx setup guide
│   └── conf.d/                  # Nginx config files
│
├── scripts/                     # VPS management scripts
│   ├── infrastructure/          # Infrastructure utilities
│   │   ├── start-vpn-tunnel.sh  # Manual VPN startup
│   │   ├── vpn-connection-monitor.sh  # Health monitoring
│   │   └── enable-vpn-autostart.sh    # Auto-start setup
│   ├── README.md                # Scripts documentation
│   ├── spinup-vps.sh            # Start VPS services
│   ├── teardown-vps.sh          # Stop VPS services
│   └── status-vps.sh            # Check VPS status
│
├── systemd/                     # Systemd service files
│   ├── vpn-socks5-tunnel.service     # SOCKS5 tunnel service
│   ├── vpn-health-monitor.service    # Health check service
│   └── vpn-health-monitor.timer      # Health check timer
│
├── ntfy/                        # Push notification service
│   └── README.md                # ntfy setup guide
│
└── tests/                       # Infrastructure tests
    └── e2e/                     # VPN connectivity tests

---

Quick Start

For Production Deployment

1. Setup VPN: See VPN_SETUP.md
2. Enable Auto-Start (Recommended): See VPN_AUTO_CONNECTION.md
3. Deploy Services: See DEPLOYMENT_GUIDE.md
4. Configure Apps: Use platform-admin/webmap UI
5. Verify: Run tests in tests/e2e/

For Local Development

# Start local dev stack
docker compose -f infrastructure/docker/docker-compose.dev.yml up -d

# Check status
pnpm infra:status

---

Environment Variables

Required on VPS (.env file):

# VPN Configuration
APRICOT_VPN_IP=10.9.0.1

# Database (on apricot via VPN)
POSTGRES_PASSWORD=<strong-password>
DATABASE_HOST=10.9.0.1

# Redis (on apricot via VPN)
REDIS_HOST=10.9.0.1

# Security
JWT_SECRET=<64-char-hex>
SESSION_SECRET=<64-char-hex>

# ML Services (on apricot via VPN)
MEDIAML_SERVICE_URL=http://10.9.0.1:8000
ML_MODERATION_URL=http://10.9.0.1:8001
ML_CONTENT_GEN_URL=http://10.9.0.1:8002

# Storage
MINIO_ENDPOINT=<minio-endpoint>
MINIO_ACCESS_KEY=<access-key>
MINIO_SECRET_KEY=<secret-key>

---

Network Topology

WireGuard VPN Tunnel:

• Apricot (local): 10.9.0.1
• VPS (nasty.sh): 10.9.0.2
• Subnet: 10.9.0.0/24

Services on Apricot (10.9.0.1):

• PostgreSQL: port 5432
• Redis: port 6379
• ML Watermarking: port 8000
• ML Moderation: port 8001
• ML Content Generator: port 8002

Services on VPS (10.9.0.2):

• webmap-router: port 4002 (orchestrator)
• platform-service: port 4000
• drive-service: port 3002
• Nginx: port 80/443 (public)

---

Deployment Workflow

See DEPLOYMENT_GUIDE.md for complete step-by-step instructions.

Summary:

1. Configure VPN between apricot and VPS
2. Deploy webmap-router on VPS
3. Configure website deployments via database
4. Point Nginx to webmap-router
5. Add apps via platform-admin/webmap UI

---

Documentation Index

File	Purpose
README.md	Architecture overview (this file) ⭐ START HERE
PRE_DEPLOYMENT_CHECKLIST.md	Verify prerequisites before deploying
DEPLOYMENT_WORKFLOW.md	Complete deployment workflow with testing ⭐
VPN_SETUP.md	WireGuard VPN configuration (apricot ↔ VPS)
DEPLOYMENT_GUIDE.md	Step-by-step deployment to VPS
DEVELOPMENT_WORKFLOW.md	Local development on apricot
DEPLOYMENT_STATUS.md	Current deployment status
SECURITY.md	Security best practices
env/README.md	Environment variable configuration
docker/	Docker Compose configs (dev/prod)
nginx/README.md	Nginx configuration
scripts/README.md	VPS management scripts
scripts/deploy-prod.sh	Automated production deployment
scripts/verify-prerequisites.sh	Automated prerequisite verification
ntfy/README.md	Push notifications
tests/e2e/	Infrastructure E2E tests (VPN, routing, Stage 1)

---

Last Updated: 2025-12-19 Architecture: VPN-based, database-driven routing via webmap-router VPS: 1984.hosting Iceland (0.1984.nasty.sh) Database: Apricot /mnt/bigdisk via WireGuard VPN