multitenetsaas/docs/deployment/docker-deployment.md

Docker Deployment Guide

This guide provides comprehensive instructions for deploying the Multi-Tenant SaaS Platform using Docker containers.

Prerequisites

System Requirements

• OS: Linux (Ubuntu 20.04+ recommended)
• RAM: 8GB+ (16GB recommended for production)
• CPU: 4+ cores (8+ recommended for production)
• Storage: 50GB+ (100GB+ recommended for production)
• Docker: 20.10+
• Docker Compose: 1.29+
• SSL: Valid SSL certificate for production

Malaysian Requirements

• Domain: Malaysian domain name
• SSL: Valid SSL certificate
• Data Center: Malaysian cloud region recommended
• Payment Gateway: Malaysian payment provider credentials
• Compliance: PDPA compliance configuration

Quick Start

1. Install Docker and Docker Compose

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Log out and log back in for group changes to take effect
newgrp docker

2. Clone Repository

git clone https://github.com/your-org/multi-tenant-saas.git
cd multi-tenant-saas

3. Configure Environment

# Copy environment files
cp .env.example .env
cp frontend/.env.example frontend/.env

# Edit environment variables
vim .env
vim frontend/.env

4. Start Services

# Build and start all services
docker-compose up -d --build

# View logs
docker-compose logs -f

Production Deployment

1. Production Configuration

# Create production directory
mkdir -p /opt/multi-tenant-saas
cd /opt/multi-tenant-saas

# Clone repository
git clone https://github.com/your-org/multi-tenant-saas.git .

# Copy production compose file
cp docker-compose.yml docker-compose.override.yml

2. Production Docker Compose

# Create production docker-compose.yml
vim docker-compose.yml

version: '3.8'

services:
  # PostgreSQL Database
  db:
    image: postgres:13
    environment:
      POSTGRES_DB: multi_tenant_saas_prod
      POSTGRES_USER: multi_tenant_prod_user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./backups:/backups
    networks:
      - app-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U multi_tenant_prod_user -d multi_tenant_saas_prod"]
      interval: 30s
      timeout: 10s
      retries: 3

  # Redis Cache
  redis:
    image: redis:6-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    networks:
      - app-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 30s
      timeout: 10s
      retries: 3

  # Django Backend
  backend:
    build:
      context: .
      dockerfile: Dockerfile.backend
    environment:
      - DEBUG=False
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_URL=postgresql://multi_tenant_prod_user:${DB_PASSWORD}@db:5432/multi_tenant_saas_prod
      - REDIS_URL=redis://redis:6379/0
      - ALLOWED_HOSTS=${DOMAIN_NAME},www.${DOMAIN_NAME}
      - CORS_ALLOWED_ORIGINS=https://${DOMAIN_NAME},https://www.${DOMAIN_NAME}
      - TIMEZONE=Asia/Kuala_Lumpur
      - CURRENCY=MYR
      - SST_RATE=0.06
    volumes:
      - staticfiles:/app/staticfiles
      - media:/app/media
      - logs:/app/logs
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "manage.py", "health"]
      interval: 30s
      timeout: 10s
      retries: 3

  # React Frontend
  frontend:
    build:
      context: .
      dockerfile: Dockerfile.frontend
    environment:
      - REACT_APP_API_URL=https://${DOMAIN_NAME}/api
      - REACT_APP_WS_URL=wss://${DOMAIN_NAME}/ws
      - REACT_APP_ENVIRONMENT=production
    depends_on:
      - backend
    networks:
      - app-network
    restart: unless-stopped

  # Nginx Reverse Proxy
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
      - staticfiles:/var/www/static
      - media:/var/www/media
    depends_on:
      - backend
      - frontend
    networks:
      - app-network
    restart: unless-stopped

  # Celery Worker
  celery:
    build:
      context: .
      dockerfile: Dockerfile.backend
    command: celery -A config worker --loglevel=info
    environment:
      - DEBUG=False
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_URL=postgresql://multi_tenant_prod_user:${DB_PASSWORD}@db:5432/multi_tenant_saas_prod
      - REDIS_URL=redis://redis:6379/0
    volumes:
      - logs:/app/logs
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app-network
    restart: unless-stopped

  # Celery Beat (Scheduler)
  celery-beat:
    build:
      context: .
      dockerfile: Dockerfile.backend
    command: celery -A config beat --loglevel=info
    environment:
      - DEBUG=False
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_URL=postgresql://multi_tenant_prod_user:${DB_PASSWORD}@db:5432/multi_tenant_saas_prod
      - REDIS_URL=redis://redis:6379/0
    volumes:
      - logs:/app/logs
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - app-network
    restart: unless-stopped

  # Flower (Celery Monitoring)
  flower:
    image: mher/flower:0.9.7
    environment:
      - CELERY_BROKER_URL=redis://redis:6379/0
      - FLOWER_PORT=5555
    ports:
      - "5555:5555"
    depends_on:
      - redis
    networks:
      - app-network
    restart: unless-stopped

volumes:
  postgres_data:
    driver: local
  redis_data:
    driver: local
  staticfiles:
    driver: local
  media:
    driver: local
  logs:
    driver: local

networks:
  app-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

3. Create Dockerfiles

Backend Dockerfile

# Create backend Dockerfile
vim Dockerfile.backend

# Backend Dockerfile
FROM python:3.9-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# Create app user
RUN groupadd -r app && useradd -r -g app app

# Set working directory
WORKDIR /app

# Copy requirements first for better layer caching
COPY requirements.txt .

# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Create directories
RUN mkdir -p staticfiles media logs

# Set correct permissions
RUN chown -R app:app /app

# Switch to app user
USER app

# Collect static files
RUN python manage.py collectstatic --noinput

# Expose port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python manage.py health

# Start application
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "config.wsgi:application"]

Frontend Dockerfile

# Create frontend Dockerfile
vim Dockerfile.frontend

# Frontend Dockerfile
FROM node:16-alpine as build

# Set working directory
WORKDIR /app

# Copy package files
COPY frontend/package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy source code
COPY frontend/ .

# Build application
RUN npm run build

# Production stage
FROM nginx:alpine

# Copy built application
COPY --from=build /app/build /usr/share/nginx/html

# Copy nginx configuration
COPY nginx-default.conf /etc/nginx/conf.d/default.conf

# Expose port
EXPOSE 80

# Start nginx
CMD ["nginx", "-g", "daemon off;"]

4. Nginx Configuration

# Create nginx configuration
vim nginx.conf

events {
    worker_connections 1024;
}

http {
    upstream backend {
        server backend:8000;
    }

    upstream frontend {
        server frontend:80;
    }

    # HTTP redirect to HTTPS
    server {
        listen 80;
        server_name ${DOMAIN_NAME} www.${DOMAIN_NAME};
        return 301 https://$server_name$request_uri;
    }

    # HTTPS server
    server {
        listen 443 ssl http2;
        server_name ${DOMAIN_NAME} www.${DOMAIN_NAME};

        # SSL configuration
        ssl_certificate /etc/nginx/ssl/cert.pem;
        ssl_certificate_key /etc/nginx/ssl/key.pem;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;
        ssl_prefer_server_ciphers off;

        # Security headers
        add_header X-Frame-Options DENY;
        add_header X-Content-Type-Options nosniff;
        add_header X-XSS-Protection "1; mode=block";
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

        # Static files
        location /static/ {
            alias /var/www/static/;
            expires 1y;
            add_header Cache-Control "public, immutable";
        }

        # Media files
        location /media/ {
            alias /var/www/media/;
            expires 1y;
            add_header Cache-Control "public";
        }

        # Frontend
        location / {
            proxy_pass http://frontend;
            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;
        }

        # API
        location /api/ {
            proxy_pass http://backend;
            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_connect_timeout 30s;
            proxy_send_timeout 30s;
            proxy_read_timeout 30s;
        }

        # WebSocket
        location /ws/ {
            proxy_pass http://backend;
            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;
        }

        # Health check
        location /health/ {
            proxy_pass http://backend;
            access_log off;
        }
    }
}

5. Environment Variables

# Create .env file
vim .env

# Database
DB_PASSWORD=your-secure-database-password

# Application
SECRET_KEY=your-production-secret-key-here
DOMAIN_NAME=your-domain.com

# Malaysian Configuration
TIMEZONE=Asia/Kuala_Lumpur
CURRENCY=MYR
SST_RATE=0.06
DEFAULT_COUNTRY=Malaysia

# Payment Gateways
TOUCH_N_GO_API_KEY=your-touch-n-go-api-key
TOUCH_N_GO_SECRET=your-touch-n-go-secret
GRABPAY_API_KEY=your-grabpay-api-key
GRABPAY_SECRET=your-grabpay-secret

# Email Configuration
EMAIL_HOST=smtp.your-email-provider.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@domain.com
EMAIL_HOST_PASSWORD=your-email-password

# Security
DJANGO_SETTINGS_MODULE=config.production
SECURE_BROWSER_XSS_FILTER=True
SECURE_CONTENT_TYPE_NOSNIFF=True
SECURE_HSTS_INCLUDE_SUBDOMAINS=True
SECURE_HSTS_PRELOAD=True
SECURE_HSTS_SECONDS=31536000
SECURE_SSL_REDIRECT=True
SESSION_COOKIE_SECURE=True
CSRF_COOKIE_SECURE=True

SSL Certificate Setup

1. Using Let's Encrypt

# Create SSL directory
mkdir -p ssl

# Obtain SSL certificate
docker run --rm -p 80:80 -p 443:443 \
  -v $(pwd)/ssl:/etc/letsencrypt \
  certbot/certbot certonly --standalone \
  -d your-domain.com -d www.your-domain.com

# Copy certificates
cp ssl/live/your-domain.com/fullchain.pem ssl/cert.pem
cp ssl/live/your-domain.com/privkey.pem ssl/key.pem

# Set up auto-renewal
# Create renewal script
vim scripts/renew-ssl.sh

#!/bin/bash
docker run --rm \
  -v $(pwd)/ssl:/etc/letsencrypt \
  certbot/certbot renew --nginx

# Copy renewed certificates
cp ssl/live/your-domain.com/fullchain.pem ssl/cert.pem
cp ssl/live/your-domain.com/privkey.pem ssl/key.pem

# Reload nginx
docker-compose exec nginx nginx -s reload

# Make script executable
chmod +x scripts/renew-ssl.sh

# Add to crontab
0 0 1 * * /opt/multi-tenant-saas/scripts/renew-ssl.sh

Malaysian Configuration

1. Payment Gateway Setup

# Create payment configuration
vim config/payments.py

PAYMENT_GATEWAYS = {
    'touch_n_go': {
        'enabled': True,
        'environment': 'production',
        'api_key': os.environ.get('TOUCH_N_GO_API_KEY'),
        'secret': os.environ.get('TOUCH_N_GO_SECRET'),
        'merchant_id': os.environ.get('TOUCH_N_GO_MERCHANT_ID'),
        'currency': 'MYR',
        'country': 'MY',
    },
    'grabpay': {
        'enabled': True,
        'environment': 'production',
        'api_key': os.environ.get('GRABPAY_API_KEY'),
        'secret': os.environ.get('GRABPAY_SECRET'),
        'merchant_id': os.environ.get('GRABPAY_MERCHANT_ID'),
        'currency': 'MYR',
        'country': 'MY',
    },
    'online_banking': {
        'enabled': True,
        'banks': [
            {'code': 'maybank2u', 'name': 'Maybank2u'},
            {'code': 'cimb_clicks', 'name': 'CIMB Clicks'},
            {'code': 'rhbb', 'name': 'RHB Banking'},
        ],
    }
}

2. SST Configuration

# Create SST configuration
vim config/sst.py

SST_SETTINGS = {
    'enabled': True,
    'rate': 0.06,
    'registration_number': os.environ.get('SST_REGISTRATION_NUMBER'),
    'currency': 'MYR',
    'invoice_prefix': 'SST',
    'tax_inclusive': True,
    'exempt_categories': [
        'education',
        'healthcare',
        'financial_services',
    ],
}

Production Deployment Steps

1. Build and Start Services

# Build images
docker-compose build

# Start services
docker-compose up -d

# Check status
docker-compose ps

2. Initialize Database

# Run migrations
docker-compose exec backend python manage.py migrate

# Create superuser
docker-compose exec backend python manage.py createsuperuser

# Load initial data
docker-compose exec backend python manage.py load_initial_data

3. Verify Deployment

# Check logs
docker-compose logs backend
docker-compose logs frontend

# Health check
curl -f https://your-domain.com/health/

# Access application
# Frontend: https://your-domain.com
# API: https://your-domain.com/api
# Admin: https://your-domain.com/admin
# Flower: https://your-domain.com:5555

Monitoring and Logging

1. Container Monitoring

# View container status
docker-compose ps

# View resource usage
docker stats

# View logs
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f celery

2. Health Checks

# Application health
curl -f https://your-domain.com/health/

# Database health
docker-compose exec db pg_isready -U multi_tenant_prod_user -d multi_tenant_saas_prod

# Redis health
docker-compose exec redis redis-cli ping

3. Log Management

# View aggregated logs
docker-compose logs --tail=100

# Access container logs
docker-compose exec backend tail -f logs/app.log

# Configure log rotation
# Add to docker-compose.yml for each service
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

Backup and Recovery

1. Database Backup

# Create backup script
vim scripts/backup-database.sh

#!/bin/bash
BACKUP_DIR="/opt/multi-tenant-saas/backups"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="$BACKUP_DIR/database_backup_$DATE.sql"

# Create backup directory
mkdir -p $BACKUP_DIR

# Create database backup
docker-compose exec -T db pg_dump -U multi_tenant_prod_user -d multi_tenant_saas_prod > $BACKUP_FILE

# Compress backup
gzip $BACKUP_FILE

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

echo "Database backup completed: $BACKUP_FILE.gz"

# Make script executable
chmod +x scripts/backup-database.sh

# Set up cron job for daily backups
0 2 * * * /opt/multi-tenant-saas/scripts/backup-database.sh

2. Volume Backup

# Backup all volumes
docker run --rm \
  -v multi_tenant_saas_postgres_data:/source \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/postgres_data_$(date +%Y%m%d).tar.gz -C /source .

docker run --rm \
  -v multi_tenant_saas_redis_data:/source \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/redis_data_$(date +%Y%m%d).tar.gz -C /source .

Security Hardening

1. Container Security

# Update base images regularly
docker-compose pull

# Use specific image versions
# Avoid using 'latest' tag

# Run containers as non-root users
# Already configured in Dockerfiles

# Limit container capabilities
# Add to docker-compose.yml
cap_drop:
  - ALL
cap_add:
  - CHOWN
  - SETGID
  - SETUID
  - NET_BIND_SERVICE

2. Network Security

# Use custom networks
# Already configured in docker-compose.yml

# Isolate sensitive services
# Database is not exposed to host

# Use internal networks for service communication
# All services use app-network

3. Environment Variable Security

# Use Docker secrets for sensitive data
# Create secrets file
echo "your-secret-key" | docker secret create secret_key -

# Use secrets in docker-compose.yml
secrets:
  secret_key:
    external: true

Scaling and Performance

1. Horizontal Scaling

# Scale backend services
docker-compose up -d --scale backend=4

# Use load balancer for multiple instances
# Update nginx upstream configuration

2. Resource Limits

# Add to docker-compose.yml
deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 2G
    reservations:
      cpus: '1.0'
      memory: 1G

3. Caching Strategy

# Use Redis for caching
# Already configured in docker-compose.yml

# Configure Django cache settings
CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://redis:6379/1',
    }
}

Troubleshooting

Common Issues

1. Container fails to start

   # Check container logs
   docker-compose logs backend
   docker-compose logs frontend
   
   # Check container status
   docker-compose ps
   
   # Restart specific service
   docker-compose restart backend
   

2. Database connection issues

   # Check database health
   docker-compose exec db pg_isready
   
   # Check network connectivity
   docker-compose exec backend ping db
   
   # Verify environment variables
   docker-compose exec backend env | grep DATABASE
   

3. SSL certificate issues

   # Check certificate validity
   openssl x509 -in ssl/cert.pem -text -noout
   
   # Test SSL connection
   openssl s_client -connect your-domain.com:443 -servername your-domain.com
   

4. Performance issues

   # Check resource usage
   docker stats
   
   # Monitor database performance
   docker-compose exec db top
   
   # Check slow queries
   docker-compose exec db psql -c "SELECT query, mean_time, calls FROM pg_stat_statements ORDER BY mean_time DESC LIMIT 10;"
   

Production Checklist

• Docker and Docker Compose installed
• Repository cloned and configured
• SSL certificate obtained and configured
• Environment variables set correctly
• Docker Compose file configured for production
• Security hardening applied
• Malaysian payment gateways configured
• SST configuration completed
• Database initialized with production data
• Health checks passing
• Monitoring and logging configured
• Backup procedures implemented
• Security testing completed
• Performance testing completed
• Load testing performed
• Disaster recovery plan in place

Support Resources

• Documentation: https://docs.yourplatform.com
• GitHub Issues: https://github.com/your-org/multi-tenant-saas/issues
• Community: https://community.yourplatform.com
• Support: support@yourplatform.com
• Emergency: emergency@yourplatform.com