Deployment Guide

Prerequisites

Quick Deploy (60 Seconds)

# 1. Upload from your local machine
scp dissensus-engine.zip dissensus@YOUR_VPS_IP:~/
# 2. SSH into VPS and unpack
ssh dissensus@YOUR_VPS_IP
unzip -o dissensus-engine.zip -d ~/dissensus-engine
# 3. Install dependencies and configure
cd ~/dissensus-engine && npm install --production
cp .env.example .env && nano .env # Add DEEPSEEK_API_KEY
# 4. Start with PM2
pm2 start server/index.js --name dissensus
pm2 save && pm2 startup

Full Step-by-Step Deployment

1. System Setup

ssh root@YOUR_VPS_IP

apt update && apt upgrade -y

timedatectl set-timezone UTC

adduser dissensus
usermod -aG sudo dissensus
su - dissensus

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Verify
node --version # v20.x.x
npm --version # 10.x.x

2. Deploy the Engine

scp dissensus-engine.zip dissensus@YOUR_VPS_IP:~/

cd ~
unzip -o dissensus-engine.zip -d ~/dissensus-engine
cd ~/dissensus-engine
npm install --production

3. Configure Environment Variables

cp .env.example .env
nano .env

# Server Configuration
PORT=3000
NODE_ENV=production
# API Keys (at least one required for visitors to use without their own key)
DEEPSEEK_API_KEY=sk-your-deepseek-key
OPENAI_API_KEY=sk-your-openai-key
GEMINI_API_KEY=AIza-your-gemini-key
# Optional: Timezone for "Debate of the Day"
DEBATE_OF_THE_DAY_TZ=UTC

4. Nginx Reverse Proxy Setup

sudo apt install -y nginx

sudo nano /etc/nginx/sites-available/dissensus

server {
 listen 80;
 listen [::]:80;
 server_name app.dissensus.fun;
 # Security headers
 add_header X-Frame-Options "SAMEORIGIN" always;
 add_header X-Content-Type-Options "nosniff" always;
 add_header X-XSS-Protection "1; mode=block" always;
 add_header Referrer-Policy "strict-origin-when-cross-origin" always;
 # Gzip compression
 gzip on;
 gzip_vary on;
 gzip_min_length 1024;
 gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript image/svg+xml;
 # Static assets — serve directly from Nginx
 location /css/ {
 alias /home/dissensus/dissensus-engine/public/css/;
 expires 7d;
 add_header Cache-Control "public, immutable";
 }
 location /js/ {
 alias /home/dissensus/dissensus-engine/public/js/;
 expires 7d;
 add_header Cache-Control "public, immutable";
 }
 location /images/ {
 alias /home/dissensus/dissensus-engine/public/images/;
 expires 30d;
 add_header Cache-Control "public, immutable";
 }
 # SSE streaming — CRITICAL: disable buffering
 location /api/debate/stream {
 proxy_pass http://127.0.0.1:3000;
 proxy_http_version 1.1;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_set_header Connection '';
 # CRITICAL for SSE streaming — disable all buffering
 proxy_buffering off;
 proxy_cache off;
 chunked_transfer_encoding off;
 # Long timeout for debates (they can take 5+ minutes)
 proxy_read_timeout 600s;
 proxy_send_timeout 600s;
 }
 # API endpoints
 location /api/ {
 proxy_pass http://127.0.0.1:3000;
 proxy_http_version 1.1;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 }
 # Everything else — proxy to Node
 location / {
 proxy_pass http://127.0.0.1:3000;
 proxy_http_version 1.1;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 }
}

sudo ln -sf /etc/nginx/sites-available/dissensus /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
sudo systemctl enable nginx

5. SSL with Let's Encrypt

sudo apt install -y certbot python3-certbot-nginx

sudo certbot --nginx -d app.dissensus.fun

sudo certbot renew --dry-run

6. PM2 Process Management

sudo npm install -g pm2

cd ~/dissensus-engine
pm2 start server/index.js --name dissensus

pm2 save
pm2 startup systemd

pm2 status # View process status
pm2 logs dissensus # View logs
pm2 logs dissensus --lines 100
pm2 restart dissensus # Restart app
pm2 stop dissensus # Stop app
pm2 delete dissensus # Remove from PM2

7. Firewall (UFW)

sudo apt install -y ufw
# Set defaults
sudo ufw default deny incoming
sudo ufw default allow outgoing
# Allow SSH (IMPORTANT — do this first!)
sudo ufw allow 22/tcp
# Allow HTTP and HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
# Enable firewall
sudo ufw enable
# Verify
sudo ufw status verbose

Status: active
To Action From
-- ------ ----
22/tcp ALLOW Anywhere
80/tcp ALLOW Anywhere
443/tcp ALLOW Anywhere

Quick Reference Commands

Update Procedure

# 1. SSH into VPS
ssh dissensus@YOUR_VPS_IP
# 2. Backup current version
cp -r ~/dissensus-engine ~/dissensus-engine-backup-$(date +%Y%m%d)
# 3. Upload new zip from local machine (in another terminal)
scp dissensus-engine.zip dissensus@YOUR_VPS_IP:~/
# 4. Unpack over existing
cd ~ && unzip -o dissensus-engine.zip -d ~/dissensus-engine
# 5. Install dependencies (in case package.json changed)
cd ~/dissensus-engine && npm install --production
# 6. Restart
pm2 restart dissensus
# 7. Verify
pm2 status
curl http://localhost:3000/api/health

Rollback Procedure

# Stop current version
pm2 stop dissensus
# Restore backup
rm -rf ~/dissensus-engine
mv ~/dissensus-engine-backup-YYYYMMDD ~/dissensus-engine
# Restart
pm2 start dissensus
cd ~/dissensus-engine && pm2 start server/index.js --name dissensus

DNS Configuration

dissensus.fun → Landing page (Hostinger shared hosting)
app.dissensus.fun → Debate engine (Hostinger VPS)

Architecture Overview

Internet
 │
 ▼
┌─────────────────────────┐
│ Nginx (port 80/443) │ ← SSL termination, compression, static files
│ - SSL via Let's Encrypt
│ - Gzip compression
│ - Static asset caching
│ - SSE proxy (no buffer)
└──────────┬──────────────┘
 │ proxy_pass
 ▼
┌─────────────────────────┐
│ Node.js (port 3000) │ ← Express server, debate orchestration
│ - SSE streaming │
│ - Multi-provider AI │
│ - 4-phase debate engine│
└──────────┬──────────────┘
 │ HTTPS
 ▼
┌─────────────────────────┐
│ AI Providers │
│ - DeepSeek V3.2 │
│ - Google Gemini │
│ - OpenAI GPT-4o │
└─────────────────────────┘

Troubleshooting Quick Fixes

pm2 restart dissensus

# Check Nginx has proxy_buffering off in the stream location
sudo nginx -t && sudo systemctl reload nginx

sudo certbot renew --dry-run

# Add 2GB swap
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab