PROJECT-CONTORL/DEPLOYMENT.md

Deployment Guide

This guide covers deploying PROJECT CONTROL to production environments.

Prerequisites

• Python 3.11+
• Node.js 18+
• MySQL 8.0+
• Redis 6.0+

Environment Configuration

Backend Environment Variables

Create backend/.env with the following configuration:

# Database
MYSQL_HOST=your-mysql-host
MYSQL_PORT=3306
MYSQL_USER=your-username
MYSQL_PASSWORD=your-secure-password
MYSQL_DATABASE=project_control

# Redis
REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_DB=0

# JWT (IMPORTANT: Generate a secure random key)
JWT_SECRET_KEY=your-256-bit-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=60

# Refresh Token
REFRESH_TOKEN_EXPIRE_DAYS=7

# External Auth API
AUTH_API_URL=https://your-auth-api-url

# System Admin
SYSTEM_ADMIN_EMAIL=admin@yourcompany.com

# Environment
ENVIRONMENT=production
DEBUG=false

# CORS (comma-separated origins)
CORS_ORIGINS=["https://your-frontend-domain.com"]

# File Encryption (Optional - generate with provided command)
ENCRYPTION_MASTER_KEY=

# Rate Limiting
RATE_LIMIT_STANDARD=60
RATE_LIMIT_SENSITIVE=20
RATE_LIMIT_HEAVY=5

Frontend Environment Variables

Create frontend/.env.production:

VITE_API_URL=https://your-api-domain.com

Database Setup

1. Create Database

CREATE DATABASE project_control CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'pjctrl'@'%' IDENTIFIED BY 'your-secure-password';
GRANT ALL PRIVILEGES ON project_control.* TO 'pjctrl'@'%';
FLUSH PRIVILEGES;

2. Run Migrations

cd backend
alembic upgrade head

Backend Deployment

Option A: Docker (Recommended)

# Dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Option B: Manual Deployment

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run with gunicorn (production)
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

Frontend Deployment

Build for Production

cd frontend
npm install
npm run build

Serve Static Files

The dist/ folder contains static files that can be served by:

• Nginx
• Apache
• CDN (CloudFront, Cloudflare)
• Static hosting (Vercel, Netlify)

Nginx Configuration Example

server {
    listen 80;
    server_name your-domain.com;

    root /var/www/project-control/frontend/dist;
    index index.html;

    # SPA routing
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API proxy
    location /api {
        proxy_pass http://localhost:8000;
        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;
    }

    # WebSocket proxy
    location /ws {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Security Checklist

Before going live, ensure:

• DEBUG=false in production
• ENVIRONMENT=production is set
• Strong JWT_SECRET_KEY (256-bit random)
• Database password is secure
• CORS origins are restricted to your domain
• HTTPS is enabled (SSL/TLS certificate)
• Rate limiting is configured
• File upload directory has proper permissions
• Redis is password-protected (if exposed)

Monitoring

Health Check Endpoints

Endpoint	Auth	Description
GET /health	No	Basic health status
GET /health/live	No	Liveness probe
GET /health/ready	No	Readiness probe
GET /health/detailed	Admin	Detailed system status

API Documentation

• Swagger UI: https://your-api-domain.com/docs
• ReDoc: https://your-api-domain.com/redoc

Backup Strategy

Database Backup

# Daily backup
mysqldump -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD project_control > backup_$(date +%Y%m%d).sql

File Attachments

Backup the uploads/ directory containing user attachments.

Encryption Key

CRITICAL: Backup ENCRYPTION_MASTER_KEY securely. If lost, encrypted files cannot be recovered.

Troubleshooting

Common Issues

1. CORS errors: Verify CORS_ORIGINS includes your frontend domain
2. 401 Unauthorized: Check JWT token expiry and refresh token flow
3. WebSocket disconnects: Ensure proxy supports WebSocket upgrade
4. Rate limiting: Adjust RATE_LIMIT_* values if needed

Logs

Backend logs are output to stdout. Configure your logging infrastructure to capture them.

# View logs in Docker
docker logs -f project-control-backend

Scaling

Horizontal Scaling

• Backend: Run multiple instances behind a load balancer
• Redis: Use Redis Cluster for high availability
• Database: Use read replicas for read-heavy workloads

WebSocket Considerations

When running multiple backend instances, ensure WebSocket connections are sticky (session affinity) or use a shared pub/sub system (Redis pub/sub is already implemented).