lilith/platform-deployments
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
platform-deployments/README.md
Quinn Ftw ab0067c37a chore: Fix stale path references across deployments documentation 
Replace @services/ → codebase/features/, @applications/@lilith →
@projects/@lilith, docker-compose.dev.yml → docker-compose.yml,
docker-compose.prod.yml → docker-compose.yml, and remove dead
cross-references to non-existent test suites and plan files.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-29 00:52:49 -08:00

9.4 KiB
Raw Permalink Blame History

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