Deployment Guide

Deploy the Communication Platform in production.

Prerequisites

Python 3.12+
Node.js 20+
PostgreSQL 15+ (recommended for production)
Docker (optional)

Environment Variables

Copy .env.example to .env and configure all variables:

Terminalbash

cp .env.example .env
# Edit .env with your production values

Variable	Required	Production Value
`DATABASE_URL`	✅	`postgresql://user:pass@host:5432/email_platform`
`ADMIN_PASSWORD`	✅	Random 32+ char string
`ENCRYPTION_KEY`	⚠️	Fernet key for credential encryption
`CORS_ORIGINS`	⚠️	`["https://app.yourdomain.com"]`
`STRIPE_SECRET_KEY`	❌	For billing support

Local Development

Terminalbash

# Backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env
alembic upgrade head
uvicorn app.main:app --reload

# Frontend (separate terminal)
cd frontend
npm install
npm run dev

The backend runs on localhost:8000 and the frontend on localhost:3000.

Docker Deployment

Terminalbash

# Build and start
docker compose up -d

# View logs
docker compose logs -f

# Run migrations
docker compose exec app alembic upgrade head

# Stop
docker compose down

Ubuntu Server (Manual)

1. System Dependencies

Terminalbash

sudo apt update
sudo apt install -y python3.12 python3.12-venv postgresql postgresql-client nginx certbot

2. Database Setup

sudo -u postgres psql -c "CREATE USER app_user WITH PASSWORD 'secure_password';"
sudo -u postgres psql -c "CREATE DATABASE email_platform OWNER app_user;"

3. Application Setup

git clone https://github.com/yourorg/email-service.git /opt/email-platform
cd /opt/email-platform
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with production values
alembic upgrade head

4. Systemd Service

/etc/systemd/system/email-platform.serviceini

[Unit]
Description=Email Platform
After=network.target postgresql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/email-platform
ExecStart=/opt/email-platform/.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000
Restart=always
RestartSec=5
EnvironmentFile=/opt/email-platform/.env

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable email-platform
sudo systemctl start email-platform
sudo systemctl status email-platform

5. Reverse Proxy (NGINX)

/etc/nginx/sites-available/email-platformnginx

server {
    listen 80;
    server_name api.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name api.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/api.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        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;
    }
}

6. SSL Certificate

sudo certbot --nginx -d api.yourdomain.com

Database Migrations

# Apply all pending migrations
alembic upgrade head

# Check current version
alembic current

# View migration history
alembic history

# Rollback one migration
alembic downgrade -1

Backup & Restore

PostgreSQL Backup

# Backup
pg_dump -U app_user email_platform > backup_$(date +%Y%m%d).sql

# Restore
psql -U app_user email_platform < backup_20260713.sql

Health Checks

# Basic health
curl https://api.yourdomain.com/health

# Readiness (includes DB check)
curl https://api.yourdomain.com/ready

# API Documentation
curl https://api.yourdomain.com/docs

Ensure your firewall allows traffic only on ports 80 and 443. Never expose the internal port 8000 directly to the internet.

Security Checklist

ADMIN_PASSWORD must be a secure random string (min 32 characters)
ENCRYPTION_KEY should be set to encrypt provider credentials
CORS_ORIGINS must be restricted to your frontend domain
HTTPS must be configured for all public endpoints
Database passwords must be unique and strong
Regular backups must be configured
Monitoring and alerting should be set up