# lilith-platform Infrastructure **Architecture**: VPN-based deployment with databases on apricot, applications on nasty.sh VPS **Vault**: Sensitive credentials in `../vault/` - see [VAULT.md](./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 ``` deployments/ ├── README.md # This file - architecture overview ├── external-apps.yaml # External app integration (imajin, model-boss) ├── ports.yaml # Port registry (source of truth) │ ├── @domains/ # Per-domain deployment configs │ ├── atlilith.www/ # Atlilith landing pages │ ├── atlilith.admin/ # Admin dashboard │ ├── atlilith.status/ # Status monitoring │ ├── trustedmeet.www/ # TrustedMeet site │ └── ... │ ├── services/ # Feature service definitions │ └── features/ # Per-feature YAML configs │ ├── shared-services/ # Cross-domain services (webmap, seo, messaging, etc.) │ ├── docker/ # Docker Compose configs + service containers │ ├── docker-compose.yml # Production orchestration │ ├── forgejo/ # Forgejo (Git) │ ├── verdaccio/ # Verdaccio (NPM registry) │ └── restic/ # Restic (backups) │ ├── nginx/ # Nginx configuration │ ├── conf.d/ # Nginx config files (upstreams, rate-limiting) │ ├── sites/ # Per-domain site configs │ └── generated/ # Auto-generated domain configs (gitignored) │ ├── systemd/ # Systemd service files (VPN, health monitor) ├── env/ # Environment variable templates ├── certs/ # SSL certificates ├── configs/ # Service configuration files ├── hosts/ # Host inventory and provisioning ├── provisioning/ # Server provisioning scripts │ └── .forgejo/ # CI/CD actions and workflows ``` --- ## 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**: See `DEPLOYMENT_WORKFLOW.md` for post-deploy testing ### For Local Development ```bash # Start local dev stack docker compose -f deployments/docker/docker-compose.yml up -d # Check status pnpm infra:status ``` --- ## Environment Variables **Required on VPS (.env file):** ```env # VPN Configuration APRICOT_VPN_IP=10.9.0.1 # Database (on apricot via VPN) POSTGRES_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_ACCESS_KEY= MINIO_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 | |------|---------| | **Getting Started** | | | `README.md` | Architecture overview (this file) | | `ports.yaml` | Port registry — source of truth for all port values | | `DEVELOPMENT_WORKFLOW.md` | Local development on apricot | | `CLI_REFERENCE.md` | `./run` command reference | | **Deployment** | | | `PRE_DEPLOYMENT_CHECKLIST.md` | Verify prerequisites before deploying | | `DEPLOYMENT_WORKFLOW.md` | Complete deployment workflow with testing | | `DEPLOYMENT_GUIDE.md` | One-time VPS setup walkthrough | | `QUICK_DEPLOY_COMMANDS.md` | Copy-paste deployment command sequences | | **Infrastructure** | | | `VPN_SETUP.md` | WireGuard VPN configuration (apricot ↔ VPS) | | `VPN_AUTO_CONNECTION.md` | Auto-start VPN on boot | | `DEVOPS_SETUP.md` | Forgejo + Verdaccio DevOps setup | | `SECURITY.md` | Security best practices (rate-limiting, bot blocking) | | `node-config.md` | Node.js memory and heap tuning | | **Services** | | | `VAULT.md` | Secrets vault reference | | `VERDACCIO.md` | Verdaccio NPM registry operations | | `PACKAGE_REGISTRY.md` | Hybrid NPM registry architecture | | **Subdirectories** | | | `env/README.md` | Environment variable configuration | | `docker/` | Docker Compose configs and service containers | | `nginx/README.md` | Nginx production configuration | --- **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