Oracle Bridge DNS & HTTPS Setup Runbook

Status: COMPLETE ✅

Resolved: 2025-12-05 Issue: Frontend E2E tests were failing - investigated oracle-bridge connectivity.

Current State

Component	Status
Oracle-bridge VPS	✅ Running (port 8787 staging, 8788 production)
PM2 Process	✅ Online
DNS Record	✅ staging-oracle.helloworlddao.com → 65.21.149.226
HTTPS/SSL	✅ Working (Let's Encrypt)
Health Check	✅ https://staging-oracle.helloworlddao.com/api/notifications/health
SMTP	⚠️ Unhealthy (expected - localhost maildev for staging)

Resolution Summary

DNS and HTTPS were already configured. Investigation confirmed:

1. DNS A record exists: staging-oracle.helloworlddao.com → 65.21.149.226
2. SSL certificate is valid and working
3. Oracle-bridge service is responding to requests

The SMTP "unhealthy" status is expected in staging (uses localhost maildev).

Prerequisites

• Access to GoDaddy DNS management for helloworlddao.com
• SSH access to VPS (via GitHub secrets or direct)
• VPS IP address (stored in VPS_HOST GitHub secret)

Step 1: Get VPS IP Address

Either check GitHub secrets or SSH to VPS:

# Option A: Check deployment logs
# Go to GitHub → oracle-bridge → Actions → Recent deployment → Logs

# Option B: Check from secrets (requires admin access)
# Go to GitHub → oracle-bridge → Settings → Secrets → VPS_HOST

Step 2: Add DNS Records in GoDaddy

1. Login to GoDaddy: https://dcc.godaddy.com/
2. Select helloworlddao.com
3. Go to DNS Management
4. Add A Record for staging:

   Type: A
   Name: staging-oracle
   Value: [VPS_IP_ADDRESS]
   TTL: 600 (10 minutes, can increase later)

5. (Optional) Add A Record for production:

   Type: A
   Name: oracle
   Value: [VPS_IP_ADDRESS]
   TTL: 600

6. Save and wait 5-10 minutes for propagation

Step 3: Verify DNS Propagation

# Check staging
dig staging-oracle.helloworlddao.com A +short

# Check production
dig oracle.helloworlddao.com A +short

# Should return VPS IP address

Step 4: Install Nginx on VPS

SSH to VPS and run:

# Install nginx
sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

# Check nginx status
sudo systemctl status nginx

Step 5: Configure Nginx Virtual Host

Create nginx config:

sudo nano /etc/nginx/sites-available/oracle-bridge

Add this configuration:

# Staging (staging-oracle.helloworlddao.com)
server {
    listen 80;
    server_name staging-oracle.helloworlddao.com;

    location / {
        proxy_pass http://localhost:8787;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;
    }
}

# Production (oracle.helloworlddao.com)
server {
    listen 80;
    server_name oracle.helloworlddao.com;

    location / {
        proxy_pass http://localhost:8788;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/oracle-bridge /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Step 6: Configure SSL with Certbot

# Get SSL certificates (will auto-configure nginx)
sudo certbot --nginx -d staging-oracle.helloworlddao.com -d oracle.helloworlddao.com

# Follow prompts:
# - Enter email for certificate expiry notices
# - Agree to ToS
# - Choose whether to redirect HTTP to HTTPS (recommended: yes)

# Test auto-renewal
sudo certbot renew --dry-run

Step 7: Configure Firewall

# Allow HTTP and HTTPS
sudo ufw allow 'Nginx Full'
sudo ufw status

Step 8: Verify Setup

# Test HTTPS endpoints
curl -v https://staging-oracle.helloworlddao.com/health
curl -v https://oracle.helloworlddao.com/health

# Should return: {"status":"ok"}

Step 9: Update Frontend Tests (if needed)

The frontend is already configured with the correct URL in .env.staging:

VITE_ORACLE_BRIDGE_URL=https://staging-oracle.helloworlddao.com

Re-run frontend E2E tests after DNS/SSL is configured.

Rollback

If issues occur:

1. Remove DNS records in GoDaddy (immediate effect within TTL)
2. Disable nginx sites:

   sudo rm /etc/nginx/sites-enabled/oracle-bridge
   sudo systemctl reload nginx

3. Frontend workaround: Update .env.staging to use direct IP temporarily:

   VITE_ORACLE_BRIDGE_URL=http://[VPS_IP]:8787

Related Documentation

• STAGING-PRODUCTION-SETUP.md
• DEPLOYMENT.md
• GoDaddy DNS Management

Estimated Time

• DNS setup: 5 minutes
• DNS propagation: 5-15 minutes
• Nginx + SSL setup: 15 minutes
• Total: ~30-45 minutes