SourceGuard Workflow Server - Deployment Guide

A comprehensive guide for deploying and developing the SourceGuard Workflow Server, a Go-based vulnerability remediation workflow management system.

🔧 Prerequisites

Development

• Go 1.24+ (required)
• Make (optional, for Makefile commands)
• Docker & Docker Compose (for containerized development)
• MongoDB (for production-like development)

Production

• Go 1.24+ or Docker runtime
• Node.js & npm (for PM2 process management)
• MongoDB 8.0+ (recommended)
• Gmail API credentials (for email notifications)
• Reverse proxy (Nginx/Apache recommended)
• SSL certificate (for HTTPS)

🚀 Development Setup

1. Clone and Install Dependencies

# Clone the repository
git clone <repository-url>
cd source-guard-workflow-server

# Install Go dependencies
make install
# or manually:
go mod download && go mod tidy

2. Environment Configuration

# Edit configuration for development
nano .env

3. Start Development Server

Option A: Direct Go execution

# Run directly
go run cmd/server/main.go

# Or build and run
make run

Option B: Docker Compose (with MongoDB)

# Start MongoDB for development
cd deployment/docker
docker-compose -f docker-compose-dev.yml up -d

# Update .env for MongoDB
STORAGE_TYPE=mongodb
MONGODB_URI=mongodb://admin:password@localhost:27017/sourceGuard?authSource=admin

# Run the server
go run cmd/server/main.go

4. Verify Installation

# Check health endpoint
curl http://localhost:3008/health

# Access Swagger documentation
open http://localhost:3008/swagger/index.html

5. Development Tools

# Generate API documentation
make swagger

# Format code
make fmt

# Run tests
make test

# Clean build artifacts
make clean

🐳 Docker Deployment (Recommended)

# Edit production configuration
nano .env

# Deploy with Docker Compose
cd deployment/docker
docker-compose up -d

# Check deployment status
docker-compose ps
docker-compose logs -f api-server

Native Deployment

1. Binary Deployment

Build for Production

# Build optimized binary
make build

# Or with manual optimization
go build -ldflags="-w -s" -o bin/source-guard-workflow-server cmd/server/main.go

Deploy Binary

# Create deployment directory
sudo mkdir -p /opt/source-guard
sudo chown $USER:$USER /opt/source-guard

# Copy binary and configuration
cp bin/source-guard-workflow-server /opt/source-guard/
cp .env /opt/source-guard/
mkdir -p /opt/source-guard/attachments

# Create service user
sudo useradd -r -s /bin/false source-guard
sudo chown -R source-guard:source-guard /opt/source-guard

Automated Deployment with PM2

Use the provided deployment script for automated setup:

# Run the automated deployment script
chmod +x deployment/scripts/deploy-native.sh
./deployment/scripts/deploy-native.sh

# The script will:
# - Check prerequisites (Go, Node.js, PM2)
# - Build the application
# - Setup deployment directory
# - Deploy files and configuration
# - Start the application with PM2
# - Verify the deployment

PM2 Management Commands

# View application status
pm2 status
pm2 info source-guard-workflow-server

# View logs
pm2 logs source-guard-workflow-server
pm2 logs source-guard-workflow-server --lines 100

# Restart application
pm2 restart source-guard-workflow-server

# Stop application
pm2 stop source-guard-workflow-server

# Delete application from PM2
pm2 delete source-guard-workflow-server

# Reload application (zero-downtime restart)
pm2 reload source-guard-workflow-server

# Monitor application metrics
pm2 monit

# View application details
pm2 describe source-guard-workflow-server

# Flush logs
pm2 flush

# Update PM2 configuration
pm2 restart ecosystem.config.js --update-env

# Or use the deployment script for management
./deployment/scripts/deploy-native.sh status    # Show status
./deployment/scripts/deploy-native.sh logs      # View logs
./deployment/scripts/deploy-native.sh restart   # Restart app
./deployment/scripts/deploy-native.sh stop      # Stop app

Docker Configuration for Production

For production deployment, update your .env file with production settings:

# Production Environment Configuration
PORT=3008
BASE_URL=https://your-domain.com
ENV=production

# Database
STORAGE_TYPE=mongodb
MONGO_ROOT_USER=admin
MONGO_ROOT_PASSWORD=your_secure_mongodb_password
MONGODB_URI=mongodb://admin:your_secure_mongodb_password@mongodb:27017/sourceGuard?authSource=admin
MONGODB_DATABASE=sourceGuard

# Email Service
EMAIL_SERVICE_TYPE=gmail_oauth
GMAIL_CREDENTIALS_FILE=client_secret.json
GMAIL_TOKEN_FILE=token.json
GMAIL_FROM_EMAIL=notifications@your-domain.com

# Security
ALLOWED_ORIGINS=https://your-frontend-domain.com,https://your-domain.com
LOG_LEVEL=info
DEBUG=false
ENABLE_SWAGGER=false

Production Deployment Commands

nano .env  # Edit with production values

# Create necessary directories
mkdir -p attachments

# Deploy the stack
cd deployment/docker
docker-compose up -d

# Check deployment status
docker-compose ps

# View logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f api-server
docker-compose logs -f mongodb

Management Commands

# Navigate to docker directory first
cd deployment/docker

# Stop all services
docker-compose down

# Stop and remove volumes (⚠️ This will delete data)
docker-compose down -v

# Update and restart services
docker-compose pull
docker-compose up -d

# Backup MongoDB data
docker-compose exec mongodb mongodump --out /data/backup

# Restore MongoDB data
docker-compose exec mongodb mongorestore /data/backup

# Scale services (if needed)
docker-compose up -d --scale api-server=2

📧 Email Service Configuration

Gmail OAuth Setup (Recommended)

1. Google Cloud Console Setup

1. Go to Google Cloud Console
2. Create or select a project
3. Enable Gmail API
4. Create OAuth 2.0 credentials
5. Download client_secret.json

2. Generate OAuth Token

# Run the OAuth setup tool
go run cmd/setup-gmail-oauth/main.go

3. Configuration

EMAIL_SERVICE_TYPE=gmail_oauth
GMAIL_CREDENTIALS_FILE=client_secret.json
GMAIL_TOKEN_FILE=token.json
GMAIL_FROM_EMAIL=notifications@your-domain.com

Alternative: SMTP Configuration

EMAIL_SERVICE_TYPE=smtp
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM=notifications@your-domain.com

📊 Monitoring and Maintenance

Health Checks

# Basic health check
curl -f http://localhost:3008/health

# Detailed health check with response
curl -s http://localhost:3008/health | jq '.'

Log Management

# View application logs with PM2
pm2 logs source-guard-workflow-server

# View logs in real-time
pm2 logs source-guard-workflow-server --follow

# View specific number of log lines
pm2 logs source-guard-workflow-server --lines 200

# View only error logs
pm2 logs source-guard-workflow-server --err

# View only output logs
pm2 logs source-guard-workflow-server --out

# Flush all logs
pm2 flush

# Log files location
ls -la /opt/source-guard/logs/

Log Rotation with PM2

# Install PM2 log rotate module
pm2 install pm2-logrotate

# Configure log rotation (optional)
pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 30
pm2 set pm2-logrotate:compress true
pm2 set pm2-logrotate:dateFormat YYYY-MM-DD_HH-mm-ss
pm2 set pm2-logrotate:workerInterval 30
pm2 set pm2-logrotate:rotateInterval 0 0 * * *

🚀 Deployment Checklist

Pre-Deployment

• Go 1.24+ installed
• Node.js & npm installed
• PM2 installed globally
• MongoDB 8.0+ configured
• Gmail OAuth credentials obtained
• SSL certificate acquired
• Firewall rules configured
• Backup strategy implemented

Deployment

• Application built and tested
• Environment variables configured
• Database initialized with indexes
• Email service tested
• Reverse proxy configured
• Health checks passing

Post-Deployment

• Monitoring setup verified
• Log rotation configured
• Backup tested and automated
• Performance baseline established
• Documentation updated
• Team trained on operations

📁 Deployment Directory Structure

All deployment-related files are organized in the deployment/ directory:

deployment/
├── config/
│   └── ecosystem.config.js      # PM2 configuration
├── docker/
│   ├── Dockerfile               # Multi-stage Docker build
│   ├── docker-compose.yml       # Production Docker Compose
│   ├── docker-compose-dev.yml   # Development Docker Compose
│   ├── nginx.conf               # Nginx server configuration
│   ├── init-mongo.js            # MongoDB initialization script
│   └── init-mongodb-notifications.js  # Production MongoDB setup
└── scripts/
    └── deploy-native.sh         # PM2 deployment script