Deployment Guide

Overview

This guide provides detailed instructions for deploying CreativeDynamics in production environments. The library supports various deployment scenarios, from single-server installations to distributed cloud deployments.

Prerequisites

System Requirements

• Operating System: Linux (Ubuntu 20.04+ recommended), macOS, or Windows Server 2019+
• Python: 3.10 or higher
• Memory: Minimum 4GB RAM, 8GB+ recommended for production workloads
• Storage: 10GB+ depending on data volume
• CPU: 2+ cores recommended for concurrent processing

Software Dependencies

# Core dependencies
python >= 3.10
roughpy >= 0.1.0
numpy >= 1.24.0
pandas >= 2.0.0
fastapi >= 0.100.0
uvicorn >= 0.23.0

Installation Methods

1. Production Installation (Source)

# Create virtual environment
python -m venv creativedynamics-env
source creativedynamics-env/bin/activate  # Linux/macOS
# or
creativedynamics-env\Scripts\activate  # Windows

# Install package
pip install .

# Verify installation
python -c "import creativedynamics; print(creativedynamics.__version__)"

2. Docker Deployment

Create a Dockerfile:

FROM python:3.10-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Copy application and install with dependencies
COPY . .

# Install CreativeDynamics with all dependencies from pyproject.toml
RUN pip install --no-cache-dir -e .

# Expose API port
EXPOSE 5001

# Run API server
CMD ["uvicorn", "creativedynamics.api.main:app", "--host", "0.0.0.0", "--port", "5001"]

Build and run:

docker build -t creativedynamics:latest .
docker run -d -p 5001:5001 --name creativedynamics creativedynamics:latest

3. Kubernetes Deployment

Create creativedynamics-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: creativedynamics
spec:
  replicas: 3
  selector:
    matchLabels:
      app: creativedynamics
  template:
    metadata:
      labels:
        app: creativedynamics
    spec:
      containers:
      - name: creativedynamics
        image: creativedynamics:latest
        ports:
        - containerPort: 5001
        resources:
          requests:
            memory: "2Gi"
            cpu: "1"
          limits:
            memory: "4Gi"
            cpu: "2"
        env:
        - name: WORKERS
          value: "4"
---
apiVersion: v1
kind: Service
metadata:
  name: creativedynamics-service
spec:
  selector:
    app: creativedynamics
  ports:
    - protocol: TCP
      port: 80
      targetPort: 5001
  type: LoadBalancer

Deploy:

kubectl apply -f creativedynamics-deployment.yaml

API Server Configuration

Production Settings

Create production_config.py:

import os
from typing import Optional

class ProductionConfig:
    # API Settings
    API_HOST: str = os.getenv("API_HOST", "0.0.0.0")
    API_PORT: int = int(os.getenv("API_PORT", "5001"))
    WORKERS: int = int(os.getenv("WORKERS", "4"))

    # Security
    API_KEY: Optional[str] = os.getenv("API_KEY")
    CORS_ORIGINS: list = os.getenv("CORS_ORIGINS", "*").split(",")

    # Performance
    MAX_UPLOAD_SIZE: int = int(os.getenv("MAX_UPLOAD_SIZE", "100"))  # MB
    REQUEST_TIMEOUT: int = int(os.getenv("REQUEST_TIMEOUT", "300"))  # seconds

    # Logging
    LOG_LEVEL: str = os.getenv("LOG_LEVEL", "INFO")
    LOG_FILE: str = os.getenv("LOG_FILE", "/var/log/creativedynamics/api.log")

Running with Gunicorn (Production)

pip install gunicorn

# Run with multiple workers
gunicorn creativedynamics.api.main:app \
    --workers 4 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:5001 \
    --timeout 300 \
    --access-logfile /var/log/creativedynamics/access.log \
    --error-logfile /var/log/creativedynamics/error.log

Reverse Proxy Configuration

Nginx Configuration

Create /etc/nginx/sites-available/creativedynamics:

server {
    listen 80;
    server_name api.creativedynamics.example.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.creativedynamics.example.com;

    # SSL certificates
    ssl_certificate /etc/ssl/certs/creativedynamics.crt;
    ssl_certificate_key /etc/ssl/private/creativedynamics.key;

    # SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # Proxy settings
    location / {
        proxy_pass http://localhost:5001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        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;

        # Timeouts
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }

    # API documentation
    location /docs {
        proxy_pass http://localhost:5001/docs;
    }

    location /redoc {
        proxy_pass http://localhost:5001/redoc;
    }

    # File upload limits
    client_max_body_size 100M;
}

Enable the configuration:

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

Systemd Service

Create /etc/systemd/system/creativedynamics.service:

[Unit]
Description=CreativeDynamics API Server
After=network.target

[Service]
Type=exec
User=creativedynamics
Group=creativedynamics
WorkingDirectory=/opt/creativedynamics
Environment="PATH=/opt/creativedynamics/venv/bin"
ExecStart=/opt/creativedynamics/venv/bin/gunicorn \
    creativedynamics.api.main:app \
    --workers 4 \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind unix:/var/run/creativedynamics/creativedynamics.sock \
    --timeout 300 \
    --access-logfile /var/log/creativedynamics/access.log \
    --error-logfile /var/log/creativedynamics/error.log

Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable creativedynamics
sudo systemctl start creativedynamics
sudo systemctl status creativedynamics

Environment Variables

Required Variables

# .env file
# API Configuration
API_HOST=0.0.0.0
API_PORT=5001
WORKERS=4

# Security
API_KEY=your-secure-api-key-here
CORS_ORIGINS=https://app.example.com,https://dashboard.example.com

# Performance
MAX_UPLOAD_SIZE=100
REQUEST_TIMEOUT=300

# Logging
LOG_LEVEL=INFO
LOG_FILE=/var/log/creativedynamics/api.log

# Data Storage
DATA_PATH=/var/lib/creativedynamics/data
OUTPUT_PATH=/var/lib/creativedynamics/output
TEMP_PATH=/tmp/creativedynamics

Health Checks

Liveness Probe

curl -f http://localhost:5001/health || exit 1

Readiness Probe

# Add to your deployed FastAPI application if you need a separate readiness probe
@app.get("/ready")
async def readiness():
    """Check if the service is ready to handle requests."""
    try:
        # Check database connectivity if applicable
        # Check external service dependencies
        return {"status": "ready", "timestamp": datetime.utcnow()}
    except Exception as e:
        return JSONResponse(
            status_code=503,
            content={"status": "not ready", "error": str(e)}
        )

Backup and Recovery

Data Backup

#!/bin/bash
# backup.sh - Run daily via cron

BACKUP_DIR="/backup/creativedynamics"
DATA_DIR="/var/lib/creativedynamics"
DATE=$(date +%Y%m%d_%H%M%S)

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Backup data and configuration
tar -czf "$BACKUP_DIR/creativedynamics_${DATE}.tar.gz" \
    "$DATA_DIR" \
    "/etc/creativedynamics" \
    "/var/log/creativedynamics"

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

Recovery Procedure

# Restore from backup
BACKUP_FILE="/backup/creativedynamics/creativedynamics_20240101_120000.tar.gz"

# Stop service
sudo systemctl stop creativedynamics

# Extract backup
tar -xzf "$BACKUP_FILE" -C /

# Start service
sudo systemctl start creativedynamics

Troubleshooting

Common Issues

1. Port Already in Use

   # Find process using port 5001
   sudo lsof -i :5001
   # Kill the process if needed
   sudo kill -9 <PID>

2. Permission Denied

   # Fix permissions
   sudo chown -R creativedynamics:creativedynamics /opt/creativedynamics
   sudo chmod -R 755 /opt/creativedynamics

3. Module Import Errors

   # Reinstall dependencies
   pip install --upgrade --force-reinstall creativedynamics

4. Memory Issues

   # Increase system limits
   echo "creativedynamics soft nofile 65536" >> /etc/security/limits.conf
   echo "creativedynamics hard nofile 65536" >> /etc/security/limits.conf

Performance Tuning

API Server Optimisation

# Add to API configuration
from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Enable compression
app.add_middleware(GZipMiddleware, minimum_size=1000)

# Configure CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

System Tuning

# Increase file descriptors
ulimit -n 65536

# Optimise TCP settings
sudo sysctl -w net.core.somaxconn=65535
sudo sysctl -w net.ipv4.tcp_max_syn_backlog=65535
sudo sysctl -w net.ipv4.tcp_tw_reuse=1

Security Considerations

1. Use HTTPS in production
2. Implement API key authentication
3. Set up rate limiting
4. Configure firewall rules
5. Regular security updates
6. Monitor access logs
7. Implement request validation
8. Use secure headers

Next Steps

• Review Monitoring Guide for observability setup
• See Scaling Guide for horizontal scaling strategies
• Check Security Best Practices for hardening recommendations