Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• docker-compose.production.yml
• kubernetes/production/deployment.yaml
• vercel.json
• scripts/deploy.sh
• DOCKER_CLOUD_DEPLOYMENT.md
• DOCKER_MCP_DEPLOYMENT.md
• VERCEL_DEPLOYMENT_FIXED.md

The DevSkyy platform is designed for flexible deployment across various environments, including containerized setups with Docker, scalable clusters with Kubernetes, and serverless platforms like Vercel. This guide outlines the architecture and procedures for each supported deployment target, based on the configurations defined within the repository. The system supports everything from a simple local Docker run to a production-grade, zero-downtime Blue-Green deployment on Kubernetes.

Each deployment method leverages specific configuration files and scripts to automate and standardize the process. For a comprehensive pre-deployment checklist, refer to the Production Checklist.

Docker Deployment

The project provides robust support for containerized deployments using Docker and Docker Compose, suitable for both local development and single-server production environments. There are configurations for a standard API deployment and a more complex multi-server MCP (Model Context Protocol) infrastructure.

Sources: docker-compose.production.yml, DOCKER_MCP_DEPLOYMENT.md, scripts/deploy.sh

Docker Compose Services

The DOCKER_MCP_DEPLOYMENT.md outlines a multi-service architecture managed by Docker Compose, which includes the main API, an MCP Gateway, a database, and a cache.

The diagram below shows the services defined in the Docker Compose configuration.

The services include:

• devskyy-api: The main FastAPI application.
• mcp-gateway: Routes MCP requests to various backend servers.
• mcp-server: A stdio-based server for direct integration with tools like Claude Desktop.
• postgres: A PostgreSQL 15 database for data persistence.
• redis: A Redis 7 instance for caching and session storage.

Sources: DOCKER_MCP_DEPLOYMENT.md, artifacts/COMPLIANCE_REFACTORING_REPORT.md

Deployment Script (scripts/deploy.sh)

The repository includes a shell script to automate local Docker deployments. This script handles validation, building the image, managing containers, and performing health checks.

The script's execution flow is as follows:

Key steps in the script:

1. Validate Environment: Checks for the existence and completeness of the .env file.
2. Verify Syntax: Compiles Python files to check for syntax errors.
3. Build Image: Builds the Docker image using the Dockerfile.
4. Manage Container: Stops and removes any existing container with the same name before starting a new one.
5. Health Check: Polls a health check endpoint (/health) until the application is responsive or a timeout is reached.

Sources: scripts/deploy.sh:18-112

A snippet for the health check loop:

# scripts/deploy.sh:91-105
ATTEMPT=0
while [ $ATTEMPT -lt $MAX_HEALTH_CHECK_ATTEMPTS ]; do
    if curl -f -s ${HEALTH_CHECK_URL} > /dev/null 2>&1; then
        echo -e "${GREEN}✅ Application is healthy${NC}"
        break
    fi
    ATTEMPT=$((ATTEMPT + 1))
    echo -n "."
    sleep ${HEALTH_CHECK_INTERVAL}
done

if [ $ATTEMPT -eq $MAX_HEALTH_CHECK_ATTEMPTS ]; then
    echo -e "${RED}❌ Health check failed after ${MAX_HEALTH_CHECK_ATTEMPTS} attempts${NC}"
    echo "Container logs:"
    docker logs ${CONTAINER_NAME}
    exit 1
fi

Sources: scripts/deploy.sh:91-105

Kubernetes Deployment

For scalable, production-grade deployments, the project provides Kubernetes manifests supporting a Blue-Green deployment strategy to ensure zero downtime during updates.

Sources: kubernetes/production/deployment.yaml, DOCKER_CLOUD_DEPLOYMENT.md

Blue-Green Architecture

The Blue-Green strategy involves maintaining two identical production environments, "Blue" (active) and "Green" (standby). The load balancer directs traffic to the Blue environment. When a new version is deployed, it's deployed to the Green environment. After verification, the load balancer is switched to route traffic to Green, making it the new active environment.

This architecture is defined in kubernetes/production/deployment.yaml and DOCKER_CLOUD_DEPLOYMENT.md.

The diagram below illustrates the Kubernetes Blue-Green deployment architecture.

Key Kubernetes Components

Component	Description	Source File
Namespace	Isolates the production environment (production).	DOCKER_CLOUD_DEPLOYMENT.md
Deployments	Manages two sets of pods: devskyy-blue and devskyy-green, each with 3 replicas.	kubernetes/production/deployment.yaml
Service	A LoadBalancer service that uses a selector (version: blue or version: green) to direct traffic.	kubernetes/production/deployment.yaml
HPA	Horizontal Pod Autoscaler to scale pods between 3 and 10 based on CPU/memory usage.	DOCKER_CLOUD_DEPLOYMENT.md
Probes	Liveness and Readiness probes are configured to use the /api/v1/monitoring/health endpoint.	DOCKER_CLOUD_DEPLOYMENT.md
Resources	CPU and memory requests/limits are defined to ensure resource allocation.	DOCKER_CLOUD_DEPLOYMENT.md

Health Probes

The deployment utilizes liveness and readiness probes to manage pod health and traffic routing.

# kubernetes/production/deployment.yaml (example from DOCKER_CLOUD_DEPLOYMENT.md)
livenessProbe:
  httpGet:
    path: /api/v1/monitoring/health
    port: 8000
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /api/v1/monitoring/health
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 5

Sources: DOCKER_CLOUD_DEPLOYMENT.md

Vercel Deployment

The project also supports serverless deployment on the Vercel platform, optimized for fast cold starts and scalability.

Sources: vercel.json, VERCEL_DEPLOYMENT_FIXED.md

Vercel Configuration

The vercel.json file defines the build process and runtime environment for Vercel.

Key configurations include:

• Python Runtime: Specifies the use of Python 3.11.
• Build Command: Installs dependencies from a Vercel-specific requirements file, requirements.vercel.txt, using --no-cache-dir for reliable builds.
• Entrypoint: The main application file is main.py.

{
  "builds": [
    {
      "src": "main.py",
      "use": "@vercel/python",
      "config": {
        "runtime": "python3.11",
        "maxLambdaSize": "15mb"
      }
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "main.py"
    }
  ]
}

Sources: vercel.json, VERCEL_DEPLOYMENT_FIXED.md

Vercel Deployment Flow

The deployment to Vercel is a streamlined process handled by the Vercel platform.

The VERCEL_DEPLOYMENT_FIXED.md file indicates that a dedicated vercel_startup.py script is used for environment-specific initialization and dependency validation to ensure smooth deployments.

Sources: VERCEL_DEPLOYMENT_FIXED.md

CI/CD Pipeline

The repository is configured for Continuous Integration and Continuous Deployment, automating the testing, security scanning, building, and deployment processes.

The diagram below shows the CI/CD pipeline stages.

This automated pipeline ensures that every change is tested and scanned before being deployed, reducing the risk of introducing bugs or vulnerabilities into production.

Sources: DOCKER_CLOUD_DEPLOYMENT.md, GITHUB_SETUP_GUIDE.md