Deployment Guide

Deploy PulseGen to production with confidence.

Table of contents

  1. Overview
  2. Quick Start with Docker Compose
    1. Prerequisites
    2. Steps
    3. With Redis (Optional, for improved performance)
    4. With Nginx Reverse Proxy (Production)
  3. Individual Container Setup
    1. 1. Network Setup
    2. 2. PostgreSQL Database
    3. 3. Redis Cache (Optional)
    4. 4. Backend API
    5. 5. Frontend
  4. Development Setup
    1. Using Docker Compose
    2. Without Docker
  5. Production Deployment
    1. Pre-deployment Checklist
    2. Production Docker Compose
    3. Resource Recommendations
  6. Cloud Deployments
    1. AWS Deployment
      1. Option 1: EC2 with Docker Compose
      2. Option 2: ECS with Fargate
      3. Option 3: EKS with Kubernetes
      4. Using RDS for Database
      5. Using ElastiCache for Redis
    2. Google Cloud Platform
      1. Option 1: Compute Engine with Docker
      2. Option 2: Cloud Run
      3. Using Cloud SQL
    3. Azure Deployment
      1. Option 1: Virtual Machine with Docker
      2. Option 2: Container Instances
      3. Using Azure Database for PostgreSQL
  7. Environment Variables
    1. Required Variables
    2. Optional Variables
  8. SSL/HTTPS Configuration
    1. Using Let’s Encrypt (Recommended)
    2. Using Cloud Provider SSL
  9. Backup and Recovery
    1. Database Backups
      1. Automated Backups
      2. Manual Backup
    2. File Uploads Backup
  10. Monitoring and Logging
    1. View Logs
    2. Log Rotation
    3. Health Checks
    4. Monitoring Tools
  11. Troubleshooting
    1. Common Issues
    2. Getting Help
  12. Next Steps

This guide covers different deployment options for PulseGen, from simple Docker Compose setups to cloud deployments.

Overview

Quick Start with Docker Compose

The fastest way to get PulseGen running is with Docker Compose.

Prerequisites

  • Docker Engine 20.10+
  • Docker Compose 2.0+
  • At least 2GB RAM available
  • 10GB disk space

Steps

  1. Clone the repository 
    1
2

    git clone https://github.com/genesis-nexus/pulsegen.git
cd pulsegen
  2. Configure environment 
    1

    cp .env.example .env
  3. Edit the .env file with your settings: 
    1

    nano .env  # or use your preferred editor

    At minimum, change these values:

    POSTGRES_PASSWORD=your_secure_password_here
JWT_SECRET=your_jwt_secret_here
JWT_REFRESH_SECRET=your_refresh_secret_here
ENCRYPTION_KEY=your_64_char_hex_encryption_key_here

    Generate secure secrets:

    1
2
3
4
5

    # Generate JWT secrets
openssl rand -base64 32

# Generate encryption key
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
  4. Start all services 
    1

    docker-compose up -d
  5. Access the application
    • Frontend: http://localhost:3001
    • API: http://localhost:5001
    • Default admin credentials: admin@example.com / admin123 (change immediately!)
  6. Check logs 
    1

    docker-compose logs -f

With Redis (Optional, for improved performance)

To start with Redis cache:

1

docker-compose --profile with-redis up -d

With Nginx Reverse Proxy (Production)

To start with Nginx reverse proxy:

1

docker-compose --profile production up -d

Access via: http://localhost

Individual Container Setup

Run each component as a separate container for more control.

1. Network Setup

Create a shared network:

1

docker network create pulsegen_network

2. PostgreSQL Database 

1
2
3
4
5
6
7
8
9

docker run -d \
  --name pulsegen_postgres \
  --network pulsegen_network \
  -e POSTGRES_DB=pulsegen \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=your_secure_password \
  -v pulsegen_postgres_data:/var/lib/postgresql/data \
  -p 5432:5432 \
  postgres:16-alpine

3. Redis Cache (Optional) 

1
2
3
4
5
6

docker run -d \
  --name pulsegen_redis \
  --network pulsegen_network \
  -v pulsegen_redis_data:/data \
  -p 6379:6379 \
  redis:7-alpine

4. Backend API

Build the backend image:

1
2

cd backend
docker build -t pulsegen-backend .

Run the backend:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

docker run -d \
  --name pulsegen_backend \
  --network pulsegen_network \
  -e NODE_ENV=production \
  -e PORT=5000 \
  -e DATABASE_URL=postgresql://postgres:your_secure_password@pulsegen_postgres:5432/pulsegen \
  -e REDIS_URL=redis://pulsegen_redis:6379 \
  -e JWT_SECRET=your_jwt_secret \
  -e JWT_REFRESH_SECRET=your_refresh_secret \
  -e ENCRYPTION_KEY=your_encryption_key \
  -p 5001:5000 \
  -v $(pwd)/uploads:/app/uploads \
  -v $(pwd)/logs:/app/logs \
  pulsegen-backend

5. Frontend

Build the frontend image:

1
2
3
4

cd frontend
docker build -t pulsegen-frontend \
  --build-arg VITE_API_URL=http://localhost:5001 \
  .

Run the frontend:

1
2
3
4
5

docker run -d \
  --name pulsegen_frontend \
  --network pulsegen_network \
  -p 3001:80 \
  pulsegen-frontend

Development Setup

For local development with hot-reloading:

Using Docker Compose 

1
2
3
4
5

# Start development environment
docker-compose -f docker-compose.dev.yml up

# Start with Redis
docker-compose -f docker-compose.dev.yml --profile with-redis up

This provides:

  • Hot-reload for backend (tsx watch)
  • Hot-reload for frontend (Vite HMR)
  • Source code mounted as volumes
  • Development tools and debugging enabled

Without Docker

See Local Development Setup in the main README.

Production Deployment

Pre-deployment Checklist

  • Change all default passwords and secrets
  • Set up SSL/TLS certificates
  • Configure firewall rules
  • Set up database backups
  • Configure monitoring and alerting
  • Review security headers in nginx.conf
  • Set appropriate resource limits
  • Configure log rotation
  • Test disaster recovery procedures

Production Docker Compose

  1. Update docker-compose.yml for production:
    • Set production environment variables
    • Configure SSL in nginx
    • Set up volume backups
    • Configure restart policies
  2. Deploy with Nginx reverse proxy: 
    1

    docker-compose --profile production up -d
  3. Set up SSL certificates (Let’s Encrypt): 
    1
2
3
4
5
6
7
8
9

    # Install certbot
sudo apt-get install certbot

# Get certificates
sudo certbot certonly --standalone -d yourdomain.com

# Copy certificates
sudo cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem ./ssl/
sudo cp /etc/letsencrypt/live/yourdomain.com/privkey.pem ./ssl/

  4. Update nginx.conf to enable HTTPS (uncomment SSL section)

  5. Restart services: 
    1

    docker-compose restart nginx

Resource Recommendations

Minimum Requirements:

  • 2 CPU cores
  • 4GB RAM
  • 20GB storage
  • Handles ~100 concurrent users

Recommended for Production:

  • 4+ CPU cores
  • 8GB+ RAM
  • 50GB+ SSD storage
  • Handles 500+ concurrent users

Cloud Deployments

AWS Deployment

Option 1: EC2 with Docker Compose

  1. Launch EC2 instance
    • Instance type: t3.medium or larger
    • AMI: Amazon Linux 2 or Ubuntu 22.04
    • Storage: 30GB+ EBS volume
    • Security group: Allow ports 80, 443, 22
  2. Install Docker 
    1
2
3
4
5
6
7
8
9
10

    # Amazon Linux 2
sudo yum update -y
sudo yum install docker -y
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -a -G docker ec2-user

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
  3. Deploy application 
    1
2
3
4
5

    git clone https://github.com/genesis-nexus/pulsegen.git
cd pulsegen
cp .env.example .env
nano .env  # Configure environment
docker-compose --profile production up -d
  4. Configure Route 53 for DNS
    • Create A record pointing to EC2 public IP
  5. Set up Application Load Balancer (optional but recommended)
    • Create target group pointing to EC2 instance
    • Configure health checks
    • Add SSL certificate from ACM

Option 2: ECS with Fargate

See AWS ECS Deployment Guide for detailed instructions.

Option 3: EKS with Kubernetes

See AWS EKS Deployment Guide for detailed instructions.

Using RDS for Database

Instead of running PostgreSQL in a container:

  1. Create RDS PostgreSQL instance
    • Engine: PostgreSQL 16
    • Instance class: db.t3.micro (for testing) or db.t3.medium (production)
    • Storage: 20GB+ with autoscaling
    • Enable automatic backups
  2. Update DATABASE_URL in .env: 
    DATABASE_URL=postgresql://username:password@your-rds-endpoint:5432/pulsegen
  3. Remove postgres service from docker-compose.yml

Using ElastiCache for Redis

  1. Create ElastiCache Redis cluster
    • Engine: Redis 7.x
    • Node type: cache.t3.micro or larger
  2. Update REDIS_URL in .env: 
    REDIS_URL=redis://your-elasticache-endpoint:6379

Google Cloud Platform

Option 1: Compute Engine with Docker

  1. Create VM instance 
    1
2
3
4
5
6

    gcloud compute instances create pulsegen-vm \
  --machine-type=e2-medium \
  --image-family=ubuntu-2204-lts \
  --image-project=ubuntu-os-cloud \
  --boot-disk-size=30GB \
  --tags=http-server,https-server
  2. SSH into instance 
    1

    gcloud compute ssh pulsegen-vm
  3. Install Docker and deploy (same as AWS EC2 steps)

Option 2: Cloud Run

See GCP Cloud Run Deployment Guide

Using Cloud SQL

  1. Create Cloud SQL PostgreSQL instance 
    1
2
3
4

    gcloud sql instances create pulsegen-db \
  --database-version=POSTGRES_16 \
  --tier=db-f1-micro \
  --region=us-central1
  2. Configure connection using Cloud SQL Proxy

Azure Deployment

Option 1: Virtual Machine with Docker

  1. Create VM 
    1
2
3
4
5
6
7

    az vm create \
  --resource-group pulsegen-rg \
  --name pulsegen-vm \
  --image UbuntuLTS \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys
  2. Install Docker and deploy (same as AWS EC2 steps)

Option 2: Container Instances

See Azure Container Instances Guide

Using Azure Database for PostgreSQL

  1. Create PostgreSQL server 
    1
2
3
4
5
6
7

    az postgres flexible-server create \
  --resource-group pulsegen-rg \
  --name pulsegen-db \
  --location eastus \
  --admin-user pgadmin \
  --admin-password <password> \
  --sku-name Standard_B1ms

Environment Variables

See .env.example for complete list of environment variables.

Required Variables

Variable Description Example
POSTGRES_PASSWORD PostgreSQL password secure_password_123
JWT_SECRET JWT signing secret random_32_char_string
JWT_REFRESH_SECRET Refresh token secret another_random_string
ENCRYPTION_KEY Encryption key (64 char hex) 0123456789abcdef...

Optional Variables

Variable Description Default
REDIS_URL Redis connection URL In-memory cache
SMTP_HOST Email server host -
ANTHROPIC_API_KEY Anthropic API key -
OPENAI_API_KEY OpenAI API key -

SSL/HTTPS Configuration

  1. Install Certbot 
    1

    sudo snap install --classic certbot
  2. Get certificates 
    1

    sudo certbot certonly --standalone -d yourdomain.com
  3. Copy to project directory 
    1
2
3
4

    mkdir -p ssl
sudo cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem ssl/
sudo cp /etc/letsencrypt/live/yourdomain.com/privkey.pem ssl/
sudo chown $USER:$USER ssl/*

  4. Update nginx.conf to enable HTTPS

  5. Set up auto-renewal 
    1

    sudo certbot renew --dry-run

Using Cloud Provider SSL

  • AWS: Use ACM certificates with ALB
  • GCP: Use Google-managed certificates with Load Balancer
  • Azure: Use App Service certificates or Key Vault

Backup and Recovery

Database Backups

Automated Backups

Create a backup script:

1
2
3
4
5
6
7
8
9
10
11
12
13

#!/bin/bash
# backup-db.sh

BACKUP_DIR="/backups/postgres"
DATE=$(date +%Y%m%d_%H%M%S)
CONTAINER="pulsegen_postgres"

mkdir -p $BACKUP_DIR

docker exec $CONTAINER pg_dump -U postgres pulsegen | gzip > $BACKUP_DIR/pulsegen_$DATE.sql.gz

# Keep only last 7 days
find $BACKUP_DIR -name "*.sql.gz" -mtime +7 -delete

Add to crontab:

1
2

# Backup daily at 2 AM
0 2 * * * /path/to/backup-db.sh

Manual Backup 

1
2
3
4
5

# Backup
docker exec pulsegen_postgres pg_dump -U postgres pulsegen > backup.sql

# Restore
cat backup.sql | docker exec -i pulsegen_postgres psql -U postgres -d pulsegen

File Uploads Backup 

1
2
3
4
5

# Backup uploads directory
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz backend/uploads/

# Restore
tar -xzf uploads_backup_20240101.tar.gz

Monitoring and Logging

View Logs 

1
2
3
4
5
6
7
8

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend

# Last 100 lines
docker-compose logs --tail=100 backend

Log Rotation

Configure in docker-compose.yml:

1
2
3
4
5
6
7

services:
  backend:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Health Checks

Check service health:

1
2
3
4
5
6
7
8

# Backend health
curl http://localhost:5001/api/health

# Database connection
docker exec pulsegen_postgres pg_isready -U postgres

# Redis connection
docker exec pulsegen_redis redis-cli ping

Monitoring Tools

  • Prometheus + Grafana: Metrics and dashboards
  • CloudWatch: AWS monitoring
  • Cloud Monitoring: GCP monitoring
  • Azure Monitor: Azure monitoring

Troubleshooting

Common Issues

  1. Database connection errors
    • Check DATABASE_URL is correct
    • Ensure postgres container is healthy
    • Verify network connectivity
  2. Frontend shows “API Error”
    • Check VITE_API_URL matches backend URL
    • Verify CORS_ORIGIN in backend .env
    • Check backend is running
  3. Docker Compose fails to start
    • Check docker-compose.yml syntax
    • Verify .env file exists
    • Ensure ports are not in use

Getting Help

  • GitHub Issues: https://github.com/genesis-nexus/pulsegen/issues
  • Documentation: https://github.com/genesis-nexus/pulsegen/docs

Next Steps