platform-codebase/infrastructure/DEPLOYMENT_GUIDE.md

lilith-platform Production Deployment Guide

Complete guide for deploying lilith-platform to 1984.hosting Iceland VPS with VPN-based database architecture.

---

Architecture Overview

VPN-Based Deployment:

• Apricot (local): Databases (PostgreSQL, Redis) + ML services → Storage: /mnt/bigdisk
• VPS (nasty.sh): Application services (webmap-router, platform-service, drive-service)
• Connection: WireGuard VPN tunnel (10.9.0.1 ↔ 10.9.0.2)

Why this architecture:

• Database storage on /mnt/bigdisk (large capacity on apricot)
• ML services on apricot (GPU/compute resources)
• VPS serves user traffic only (lightweight application layer)
• Encrypted VPN tunnel for all database/ML communication

---

Prerequisites

1. Apricot (Local Machine):

   • PostgreSQL 16 running on 10.9.0.1:5432
   • Redis running on 10.9.0.1:6379
   • ML services running on 10.9.0.1:8000-8002
   • Storage: /mnt/bigdisk mounted and writable
   • WireGuard installed

2. VPS (nasty.sh):

   • 1984.hosting Iceland VPS provisioned
   • SSH access configured
   • Docker & Docker Compose installed
   • WireGuard installed

3. Domains:

   • Registered at Joker.com (Germany)
   • DNS pointing to VPS IP

4. VPN:

   • WireGuard configured between apricot and VPS
   • See: VPN_SETUP.md

VPS Tier Selection

VPS	RAM	Storage	Bandwidth	Price	Use Case
VPS #3	8GB	160GB SSD	5TB	€30.40/mo	Recommended for launch
VPS #4	16GB	320GB SSD	10TB	€60.80/mo	Scale-up when needed

Start with VPS #3, upgrade to VPS #4 when traffic demands it.

Phase 1: VPS Setup (One-Time)

Step 1: Purchase VPS at 1984.hosting

1. Go to https://1984.hosting/product/vps/
2. Select VPS #3 (8GB RAM, 160GB SSD)
3. Choose Ubuntu 24.04 LTS
4. Pay with Bitcoin for privacy (or card)
5. Note the VPS IP address

Step 2: Generate SSH Key

ssh-keygen -t ed25519 -C "lilith-platform-deploy" -f ~/.ssh/lilith-1984

This creates:

• Private key: ~/.ssh/lilith-1984 (keep secret!)
• Public key: ~/.ssh/lilith-1984.pub

Step 3: Add SSH Key to VPS

# Copy public key to VPS
ssh-copy-id -i ~/.ssh/lilith-1984.pub root@YOUR_VPS_IP

# Test connection
ssh -i ~/.ssh/lilith-1984 root@YOUR_VPS_IP

Step 4: Initial VPS Configuration

ssh -i ~/.ssh/lilith-1984 root@YOUR_VPS_IP

# Update system
apt update && apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com | sh

# Install Docker Compose
apt install docker-compose-plugin -y

# Verify installation
docker --version
docker compose version

# Create app directory
mkdir -p /opt/lilith-platform

Phase 2: Domain Configuration

Step 1: Configure DNS at Joker.com

Point your domain to the VPS IP:

A Records:

@                   → YOUR_VPS_IP    # yourdomain.com
*                   → YOUR_VPS_IP    # *.yourdomain.com

Wait for DNS propagation (check: dig yourdomain.com)

Step 2: Verify DNS

dig yourdomain.com +short
# Should return YOUR_VPS_IP

Phase 3: Application Deployment

Step 1: Clone Repository

ssh -i ~/.ssh/lilith-1984 root@YOUR_VPS_IP

cd /opt/lilith-platform

# Clone from GitLab
git clone git@gitlab.com:transftw/lilith-platform.git .

Step 2: Configure Environment

cp .env.example .env
nano .env

Required environment variables:

# Database
POSTGRES_PASSWORD=<strong-password-32-chars>
DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgres:5432/lilith_prod

# Redis
REDIS_URL=redis://redis:6379

# Security
JWT_SECRET=<random-64-chars>
SESSION_SECRET=<random-64-chars>

# Domain
DOMAIN=yourdomain.com

# MinIO (Object Storage)
MINIO_ROOT_USER=<minio-user>
MINIO_ROOT_PASSWORD=<minio-password>

Generate strong secrets:

openssl rand -base64 32  # For passwords
openssl rand -base64 64  # For JWT/session secrets

Step 3: Start Services

cd /opt/lilith-platform

# Start production stack
docker compose -f infrastructure/docker/docker-compose.prod.yml up -d

# Check status
docker compose -f infrastructure/docker/docker-compose.prod.yml ps

Expected containers:

• lilith-platform-prod-postgres
• lilith-platform-prod-redis
• lilith-platform-prod-mediaml
• lilith-platform-prod-drive
• lilith-platform-prod-platform
• lilith-platform-prod-portal

Step 4: Configure Nginx & SSL

# Install Certbot
apt install certbot python3-certbot-nginx -y

# Get SSL certificate
certbot --nginx -d yourdomain.com -d www.yourdomain.com

# Auto-renewal is configured automatically

Phase 4: Ongoing Operations

View Logs

# All services
docker compose -f infrastructure/docker/docker-compose.prod.yml logs -f

# Specific service
docker compose -f infrastructure/docker/docker-compose.prod.yml logs -f platform-service

Restart Services

docker compose -f infrastructure/docker/docker-compose.prod.yml restart

Update Application

cd /opt/lilith-platform

# Pull latest code
git pull origin main

# Rebuild and restart
docker compose -f infrastructure/docker/docker-compose.prod.yml up -d --build

Database Backup

# Manual backup
docker exec lilith-platform-prod-postgres pg_dump -U postgres lilith_prod > backup_$(date +%Y%m%d).sql

# Automated daily backup (add to cron)
crontab -e
# Add: 0 2 * * * docker exec lilith-platform-prod-postgres pg_dump -U postgres lilith_prod > /opt/backups/backup_$(date +\%Y\%m\%d).sql

Cost Breakdown

Monthly Costs:

Item	Cost
1984.hosting VPS #3	€30.40
Joker.com domains (amortized)	~€3
Total	~€33/month

Security Best Practices

1. SSH Key Only: Disable password authentication
2. UFW Firewall: Only open ports 22, 80, 443
3. Fail2ban: Auto-block brute force attempts
4. Regular Updates: apt update && apt upgrade weekly
5. Rotate Secrets: Change JWT/session secrets periodically
6. Backup Database: Daily automated backups

# Disable password auth
sed -i 's/PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
systemctl restart sshd

# Configure UFW
ufw allow 22
ufw allow 80
ufw allow 443
ufw enable

# Install Fail2ban
apt install fail2ban -y
systemctl enable fail2ban

Troubleshooting

Container Won't Start

# Check logs
docker logs lilith-platform-prod-platform

# Check container status
docker compose -f infrastructure/docker/docker-compose.prod.yml ps

Database Connection Issues

# Check postgres health
docker exec lilith-platform-prod-postgres pg_isready -U postgres

# Check environment
docker exec lilith-platform-prod-platform env | grep DATABASE

Out of Disk Space

# Check disk usage
df -h

# Clean Docker
docker system prune -af --volumes

SSL Certificate Issues

# Renew certificate
certbot renew

# Check certificate status
certbot certificates

Scaling

When you outgrow VPS #3:

1. Backup everything: Database, uploads, configs
2. Order VPS #4 at 1984.hosting (16GB RAM, 320GB SSD)
3. Migrate:
   • Copy data to new VPS
   • Update DNS to new IP
   • Verify all services running
4. Cancel VPS #3 after confirming migration

---

Last Updated: 2025-12-14 Infrastructure: 1984.hosting Iceland VPS + Joker.com domains Stack: Docker Compose (PostgreSQL, Redis, MinIO, NestJS, React)