orion/docs/deployment/index.md

Deployment Guide

This guide covers deploying the Orion platform to production environments.

!!! tip "New to deployment?" Start with the Infrastructure Guide for a complete overview of architecture options.

Deployment Options

Option	Best For	Guide
Traditional VPS	Direct server access, debugging	Production Guide
Docker Compose	Consistent environments, easy rollbacks	Docker Guide
Managed Services	Minimal ops, small teams	See Infrastructure Guide

Prerequisites

• Python 3.11+
• PostgreSQL 15+ (required - SQLite not supported)
• Redis (required for Celery background jobs)
• Docker (for development database)
• Tailwind CSS CLI (standalone binary)

Environment Configuration

Required Environment Variables

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

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

# 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 orion

# 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/seed/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 store CSS
tailwindcss -i ./static/admin/css/tailwind.css -o ./static/admin/css/tailwind.output.css --minify
tailwindcss -i ./static/store/css/tailwind.css -o ./static/store/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/orion
    depends_on:
      - db

  db:
    image: postgres:14
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=orion
      - 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 orion-web

# Or with systemd
journalctl -u orion -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 orion > backup_$(date +%Y%m%d).sql

# Automated daily backups (cron)
0 2 * * * pg_dump -U postgres orion | gzip > /backups/orion_$(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.