ai-tools-suite/DEPLOY.md

Deployment Guide - AI Tools Suite (Privacy Scanner)

This guide covers deploying the Privacy Scanner for public testing and validation.

Quick Start Options

Option	Time	Cost	Best For
Hetzner VPS	30 min	~€4/month	Production, EU data residency
Railway	10 min	Free tier available	Quick demos
Render	15 min	Free tier available	Simplicity
Local + Tunnel	5 min	Free	Quick testing

---

Option 1: Hetzner Cloud (Recommended)

Hetzner offers excellent value with EU data centers (good for GDPR compliance).

Step 1: Create a Hetzner VPS

1. Sign up at hetzner.com/cloud
2. Create a new project
3. Add a server:
   • Location: Falkenstein or Nuremberg (Germany) for EU
   • Image: Ubuntu 24.04
   • Type: CX22 (2 vCPU, 4GB RAM) - €4.51/month
   • SSH Key: Add your public key

Step 2: Initial Server Setup

# SSH into your server
ssh root@YOUR_SERVER_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

# Create app user
useradd -m -s /bin/bash appuser
usermod -aG docker appuser

# Setup firewall
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Step 3: Deploy the Application

# Switch to app user
su - appuser

# Clone your repository (or copy files)
git clone YOUR_REPO_URL ai_tools_suite
cd ai_tools_suite

# Create production .env file
cat > .env << 'EOF'
# Backend
DATABASE_URL=sqlite:///./ai_tools.db
SECRET_KEY=$(openssl rand -hex 32)
CORS_ORIGINS=https://your-domain.com

# Frontend
PUBLIC_API_URL=https://your-domain.com
ORIGIN=https://your-domain.com
EOF

# Build and start
docker compose up -d --build

# Check status
docker compose ps
docker compose logs -f

Step 4: Setup Reverse Proxy (Caddy)

Caddy provides automatic HTTPS with Let's Encrypt.

# As root
apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
apt update
apt install caddy

# Configure Caddy
cat > /etc/caddy/Caddyfile << 'EOF'
your-domain.com {
    # Frontend
    reverse_proxy localhost:3000

    # API routes
    handle /api/* {
        reverse_proxy localhost:8000
    }

    # API docs
    handle /docs {
        reverse_proxy localhost:8000
    }
    handle /redoc {
        reverse_proxy localhost:8000
    }
    handle /openapi.json {
        reverse_proxy localhost:8000
    }
}
EOF

# Restart Caddy
systemctl restart caddy
systemctl enable caddy

Step 5: Point Your Domain

1. In your DNS provider, add an A record:

   • Type: A
   • Name: @ (or subdomain like privacy-scanner)
   • Value: YOUR_SERVER_IP
   • TTL: 300

2. Wait 5-10 minutes for DNS propagation

3. Visit https://your-domain.com - Caddy will automatically get SSL certificates

---

Option 2: Railway (Quick Deploy)

Railway offers a simple deployment experience with a generous free tier.

Step 1: Setup

1. Go to railway.app and sign in with GitHub
2. Click "New Project" → "Deploy from GitHub repo"
3. Select your repository

Step 2: Configure Backend

1. Add a new service from your repo
2. Set the root directory to backend
3. Add environment variables:

   PORT=8000
   DATABASE_URL=sqlite:///./ai_tools.db
   CORS_ORIGINS=https://YOUR_FRONTEND_URL
   

Step 3: Configure Frontend

1. Add another service from the same repo
2. Set root directory to frontend
3. Add environment variables:

   PUBLIC_API_URL=https://YOUR_BACKEND_URL
   ORIGIN=https://YOUR_FRONTEND_URL
   

Railway will automatically deploy on every push.

---

Option 3: Render

Render offers easy deployment with free tier.

render.yaml (add to repo root)

services:
  - type: web
    name: privacy-scanner-api
    env: docker
    dockerfilePath: ./backend/Dockerfile
    dockerContext: ./backend
    healthCheckPath: /api/v1/health
    envVars:
      - key: CORS_ORIGINS
        sync: false

  - type: web
    name: privacy-scanner-frontend
    env: docker
    dockerfilePath: ./frontend/Dockerfile
    dockerContext: ./frontend
    buildArgs:
      PUBLIC_API_URL: https://privacy-scanner-api.onrender.com
    envVars:
      - key: ORIGIN
        sync: false

1. Push render.yaml to your repo
2. Go to render.com → New Blueprint
3. Connect your repository

---

Option 4: Local + Tunnel (Quick Testing)

For quick demos without deployment:

# Terminal 1: Start the application
docker compose up

# Terminal 2: Create public tunnel (choose one)

# Using cloudflared (recommended)
brew install cloudflare/cloudflare/cloudflared
cloudflared tunnel --url http://localhost:3000

# OR using localtunnel
npx localtunnel --port 3000

# OR using ngrok
ngrok http 3000

Share the generated URL with testers.

---

Testing Your Deployment

Health Check

# Backend health
curl https://your-domain.com/api/v1/health

# Expected response:
# {"status": "healthy", "version": "0.1.0"}

Privacy Scanner Test

# Test PII detection
curl -X POST https://your-domain.com/api/v1/privacy/scan-text \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "text=Contact john.doe@example.com or call 555-123-4567"

API Documentation

• Swagger UI: https://your-domain.com/docs
• ReDoc: https://your-domain.com/redoc

---

Monitoring & Maintenance

View Logs

# On Hetzner/VPS
docker compose logs -f

# Specific service
docker compose logs -f backend
docker compose logs -f frontend

Update Deployment

cd ai_tools_suite
git pull
docker compose down
docker compose up -d --build

Backup Database

docker compose exec backend cp /app/ai_tools.db /app/data/backup_$(date +%Y%m%d).db

---

Security Checklist

• Change default SECRET_KEY in .env
• Set specific CORS_ORIGINS (not *)
• Enable firewall (ufw)
• Use HTTPS (automatic with Caddy)
• Keep Docker images updated
• Review logs regularly

---

Troubleshooting

Container won't start

# Check logs
docker compose logs backend

# Common issues:
# - Port already in use: change ports in docker-compose.yml
# - Missing dependencies: rebuild with --no-cache
docker compose build --no-cache

CORS errors

1. Check CORS_ORIGINS includes your frontend URL
2. Include protocol: https://your-domain.com not just your-domain.com
3. Restart backend after changing env vars

SSL certificate issues

# Check Caddy status
systemctl status caddy
journalctl -u caddy -f

# Ensure DNS is pointing to server
dig your-domain.com

---

Cost Comparison

Provider	Specs	Monthly Cost
Hetzner CX22	2 vCPU, 4GB RAM, 40GB	€4.51
Hetzner CX32	4 vCPU, 8GB RAM, 80GB	€8.98
Railway	Shared, usage-based	$5-20
Render	Shared (free tier)	$0-7
DigitalOcean	2 vCPU, 2GB RAM	$18

Recommendation: Start with Hetzner CX22 for production, or Railway/Render free tier for demos.