platform-deployments/README.md

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