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](infrastructure.md) for a complete overview of architecture options.

## Deployment Options

| Option | Best For | Guide |
|--------|----------|-------|
| **Traditional VPS** | Direct server access, debugging | [Production Guide](production.md) |
| **Docker Compose** | Consistent environments, easy rollbacks | [Docker Guide](docker.md) |
| **Managed Services** | Minimal ops, small teams | See [Infrastructure Guide](infrastructure.md#option-3-managed-services-minimal-ops) |

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

```bash
# 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

```bash
# 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

```bash
git clone <repository-url>
cd orion

# Install dependencies
uv sync --frozen

# Activate virtual environment
source .venv/bin/activate
```

### 2. Database Setup

```bash
# Run migrations
alembic upgrade head

# Initialize production data
python scripts/seed/init_production.py
```

### 3. Static Assets

```bash
# 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)

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

#### Using Gunicorn with Uvicorn workers

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

## Reverse Proxy Configuration

### Nginx Example

```nginx
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

```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

```yaml
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:

```bash
# 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

```bash
# 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

```bash
# 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:

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

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