orion/docs/deployment/index.md

Deployment Guide

This guide covers deploying the Wizamart platform to production environments.

Prerequisites

• Python 3.11+
• PostgreSQL 14+ (production) or SQLite (development)
• Redis (optional, for caching/sessions)
• Tailwind CSS CLI (standalone binary)
• uv package manager

Environment Configuration

Required Environment Variables

# Application
APP_ENV=production
SECRET_KEY=<generate-secure-key>
DEBUG=false

# Database
DATABASE_URL=postgresql://user:password@host:5432/wizamart

# Security
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com
CORS_ORIGINS=https://yourdomain.com

# Email
SMTP_HOST=smtp.provider.com
SMTP_PORT=587
SMTP_USER=your-email
SMTP_PASSWORD=your-password
EMAIL_FROM=noreply@yourdomain.com

# Letzshop Integration
LETZSHOP_API_ENDPOINT=https://letzshop.lu/graphql
ENCRYPTION_KEY=<generate-fernet-key>

# Optional: Redis
REDIS_URL=redis://localhost:6379/0

Generating Secrets

# Generate SECRET_KEY
python -c "import secrets; print(secrets.token_urlsafe(64))"

# Generate ENCRYPTION_KEY (Fernet)
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Deployment Steps

1. Clone and Setup

git clone <repository-url>
cd wizamart

# Install dependencies
uv sync --frozen

# Activate virtual environment
source .venv/bin/activate

2. Database Setup

# Run migrations
alembic upgrade head

# Initialize production data
python scripts/init_production.py

3. Static Assets

# Build Tailwind CSS using standalone CLI
# Download from: https://github.com/tailwindlabs/tailwindcss/releases

tailwindcss -i ./static/shared/css/input.css -o ./static/shared/css/tailwind.output.css --minify

# Same for admin and vendor CSS
tailwindcss -i ./static/admin/css/tailwind.css -o ./static/admin/css/tailwind.output.css --minify
tailwindcss -i ./static/vendor/css/tailwind.css -o ./static/vendor/css/tailwind.output.css --minify

4. Run Application

Using Uvicorn (recommended)

uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Using Gunicorn with Uvicorn workers

gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

Reverse Proxy Configuration

Nginx Example

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

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

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.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;
    }

    location /static {
        alias /path/to/app/static;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

Docker Deployment

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# Install uv and download Tailwind CLI
RUN pip install uv && \
    curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64 && \
    chmod +x tailwindcss-linux-x64 && \
    mv tailwindcss-linux-x64 /usr/local/bin/tailwindcss

# Copy dependency files
COPY pyproject.toml uv.lock ./

# Install dependencies
RUN uv sync --frozen --no-dev

# Copy application
COPY . .

# Build static assets
RUN tailwindcss -i ./static/shared/css/input.css -o ./static/shared/css/tailwind.output.css --minify

EXPOSE 8000

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

Docker Compose

version: '3.8'

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/wizamart
    depends_on:
      - db

  db:
    image: postgres:14
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=wizamart
      - POSTGRES_PASSWORD=password

volumes:
  postgres_data:

Health Checks

The application provides health check endpoints:

• GET /health - Basic health check
• GET /health/ready - Readiness check (includes DB)

Monitoring

Logging

Logs are output to stdout in JSON format for production:

# View logs
docker logs -f wizamart-web

# Or with systemd
journalctl -u wizamart -f

Metrics

Consider integrating:

• Prometheus for metrics collection
• Grafana for visualization
• Sentry for error tracking

Backup Strategy

Database Backups

# PostgreSQL backup
pg_dump -U postgres wizamart > backup_$(date +%Y%m%d).sql

# Automated daily backups (cron)
0 2 * * * pg_dump -U postgres wizamart | gzip > /backups/wizamart_$(date +\%Y\%m\%d).sql.gz

Rollback Procedure

# Rollback database migration
alembic downgrade -1

# Rollback to specific revision
alembic downgrade <revision_id>

Troubleshooting

Common Issues

1. Database connection errors

   • Verify DATABASE_URL format
   • Check PostgreSQL is running
   • Verify network connectivity

2. Static files not loading

   • Rebuild Tailwind CSS
   • Check Nginx static file configuration
   • Verify file permissions

3. Email not sending

   • Verify SMTP credentials
   • Check firewall allows outbound SMTP
   • Test with python scripts/test_email.py

Debug Mode

For troubleshooting, temporarily enable debug mode:

DEBUG=true uvicorn app.main:app --reload

Warning: Never use debug mode in production with real traffic.