Skip to main content

OpportunityDAO Deployment Guide

Overview​

This document helps you choose the right deployment method for your OpportunityDAO instance.

Quick Decision Matrix​

Your SetupRecommended MethodDocumentation
Self-hosted GitLab + EC2GitLab Runner (most secure)GitLab CI
EC2 + Virtualmin + Multiple sitesDockerDocker Deployment
EC2 + Single app + Simple setupSystemdSystemd Deployment
Managed platform (Vercel, Railway)NativePlatform docs

Deployment Methods​

1. GitLab Runner (Most Secure for Self-hosted GitLab)​

Best for:

  • Self-hosted GitLab instance
  • Maximum security (no SSH keys in GitLab)
  • Direct deployment without network transfers
  • Simplified CI/CD pipeline

Pros:

  • ✅ No SSH keys needed - Most secure approach
  • ✅ Runner executes directly on EC2
  • ✅ Faster deployments (no file transfer)
  • ✅ Simpler CI/CD configuration
  • ✅ Better debugging (local logs)
  • ✅ Direct access to Docker and system

Cons:

  • ⚠️ Requires GitLab Runner installation on EC2
  • ⚠️ One-time setup per server

Setup time: ~15 minutes

See: GitLab CI Deployment

Best for:

  • Virtualmin/cPanel shared hosting
  • Running multiple applications
  • Strong isolation requirements
  • Easy rollback capabilities

Pros:

  • ✅ Complete isolation from other apps
  • ✅ Consistent environment (dev = prod)
  • ✅ Easy version management
  • ✅ Built-in health checks
  • ✅ Simple rollback (just use previous image)

Cons:

  • ⚠️ Requires Docker knowledge
  • ⚠️ Slightly more resources
  • ⚠️ Additional layer of complexity

Setup time: ~30 minutes

See: Docker Deployment

2. Systemd (Native Linux)​

Best for:

  • Dedicated server
  • Single application deployment
  • Minimal overhead requirements
  • Teams comfortable with Linux

Pros:

  • ✅ Simple, native Linux
  • ✅ Lower resource overhead
  • ✅ Direct access to logs (journalctl)
  • ✅ You're already using it (deposit processor)

Cons:

  • ⚠️ Less isolation
  • ⚠️ Node.js version shared with host
  • ⚠️ Manual dependency management
  • ⚠️ Harder rollback

Setup time: ~20 minutes

See: Systemd Deployment

3. PM2 (Alternative Process Manager)​

Best for:

  • Quick development deployments
  • Small-scale production
  • Node.js-focused teams

Pros:

  • ✅ Very easy to use
  • ✅ Built-in clustering
  • ✅ Nice dashboard (pm2 monit)
  • ✅ Fast setup

Cons:

  • ⚠️ Less robust than systemd
  • ⚠️ Another dependency to manage
  • ⚠️ Not as common in enterprise

Quick setup:

npm install -g pm2
pm2 start npm --name opportunitydao -- start
pm2 save
pm2 startup

Your Current Setup​

Based on your environment:

  • Platform: EC2 (Ubuntu 24)
  • Web Server: Apache
  • Control Panel: Virtualmin
  • Use Case: Shared hosting
  • Database: PostgreSQL

Recommendation: Docker ✅

Docker provides the best isolation for shared hosting while maintaining flexibility and rollback capabilities.

Files Included​

Docker Deployment​

  • Dockerfile - Main Next.js app container
  • Dockerfile.processor - Background job container
  • docker-compose.yml - Orchestration config
  • .dockerignore - Build optimization
  • .gitlab-ci.yml - CI/CD pipeline
  • docs/DEPLOYMENT_DOCKER.md - Full guide

Systemd Deployment (Alternative)​

  • systemd/opportunitydao-deposit-processor.service - Background job
  • systemd/opportunitydao-deposit-processor.timer - Job scheduler
  • docs/DEPLOYMENT_SYSTEMD.md - Full guide

Deployment Checklist​

Pre-Deployment​

  • Domain DNS pointed to EC2
  • SSL certificate ready (Let's Encrypt)
  • Database created and accessible
  • .env file configured on server
  • GitLab CI/CD variables set
  • SSH access to EC2 configured

Docker Deployment​

  • Docker and Docker Compose installed
  • Apache modules enabled (proxy, ssl)
  • Virtual host configured
  • Initial docker-compose up successful
  • Migrations applied
  • GitLab pipeline tested

Systemd Deployment​

  • Node.js 20 installed
  • Systemd services created
  • Services enabled and started
  • Apache virtual host configured
  • GitLab pipeline tested

Common Apache Configuration​

Both deployment methods use Apache as reverse proxy.

Required modules:

sudo a2enmod proxy proxy_http proxy_wstunnel ssl headers
sudo systemctl restart apache2

Basic virtual host:

<VirtualHost *:443>
    ServerName opportunitydao.com

    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/opportunitydao.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/opportunitydao.com/privkey.pem

    ProxyPreserveHost On
    ProxyPass / http://localhost:3000/
    ProxyPassReverse / http://localhost:3000/
</VirtualHost>

Full configuration in deployment guides.

GitLab CI/CD​

Both methods support automated deployment via GitLab CI/CD:

  1. Push to main branch
  2. Pipeline builds/syncs application
  3. Manual approval (or automatic)
  4. Deployment to EC2
  5. Services restart automatically

See .gitlab-ci.yml for Docker or .gitlab-ci.yml.systemd for systemd.

Environment Variables​

Required for both methods:

# Core
DATABASE_URL="postgresql://user:pass@host:5432/opportunitydao"
JWT_SECRET="your-secret-key"
NEXT_PUBLIC_API_URL="https://opportunitydao.app"

# Optional blockchain RPC
BSC_RPC_URL=""
ETH_RPC_URL=""
POLYGON_RPC_URL=""
BLOCKFROST_API_KEY=""
BLOCKFROST_NETWORK="mainnet"

Store in /var/www/opportunitydao/.env on server.

Background Jobs​

Both methods run the deposit processor:

Docker: Container with supercronic (cron-like) Systemd: Timer (runs every 3 minutes)

Monitors pending deposits and credits users when blockchain confirmations complete.

Monitoring​

Docker​

docker-compose logs -f
docker stats

Systemd​

sudo journalctl -u opportunitydao-app -f
systemctl status opportunitydao-app

Rollback​

Docker​

docker-compose down
docker-compose up -d  # Uses previous image

Systemd​

cd /var/www/opportunitydao
git checkout HEAD~1
npm ci && npm run build
sudo systemctl restart opportunitydao-app

Support​

For detailed instructions, see:

Next Steps​

  1. Choose deployment method (Docker recommended)
  2. Follow the relevant deployment guide
  3. Setup GitLab CI/CD pipeline
  4. Test deployment
  5. Configure monitoring and backups