lilith-platform Infrastructure

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

Vault: Sensitive credentials in ../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

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

# 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):

# 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
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