# Deployment Documentation

> Docker, production setup, and deployment strategies

## 📋 Overview

This section covers deploying Izri to production environments, including Docker configuration, environment setup, and deployment best practices.

## 🎯 Deployment Options

- **Docker Compose**: Complete multi-service setup
- **Containerized Deployment**: Individual service containers
- **Cloud Platforms**: AWS, Google Cloud, Azure, etc.
- **Platform-as-a-Service**: Railway, Render, Fly.io, etc.

## 📚 Documentation Pages

### [Docker Setup](./docker.md)

**Docker configuration and best practices**

- Dockerfile structure
- Multi-stage builds
- Image optimization
- Container networking
- Volume management
- Health checks

### [Docker Compose](./docker-compose.md)

**Multi-service orchestration**

- Service definitions
- Network configuration
- Volume management
- Environment variables
- Scaling services
- Development vs production

### [Environment Setup](./environment-setup.md)

**Production environment configuration**

- Environment variables
- Secrets management
- Configuration strategies
- External services
- Monitoring setup
- Logging configuration

### [Production Deployment](./production.md)

**Deploying to production**

- Pre-deployment checklist
- Deployment strategies
- Zero-downtime deployment
- Rollback procedures
- Health monitoring
- Backup and recovery

### [Runner Provisioning](./runner.md)

**Standing up the `apps/runner` service on Railway**

- Minting the `runner:write` API token
- Required env vars and where they come from
- Verifying the BRPOP loop after deploy
- Docker daemon caveat (#271 follow-up)
- Re-provisioning checklist for sibling environments

### [GitHub App: Staging vs Prod Split](./github-app.md)

**Plan for the two-App pattern + Marketplace listing**

- Why two apps (`izri-staging` + `izri`)
- Target App configuration table
- Production cutover steps (zero-downtime)
- Marketplace + brand asset deferrals
- Local-dev tunnelling notes

### [Stripe Billing Go-Live](./stripe-billing.md)

**Turning on paid subscriptions (#251)**

- Live products + prices (the `izri_<tier>_<interval>` lookup keys)
- Customer Portal activation
- Env vars (`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `ENFORCE_RUN_QUOTA`)
- Webhook endpoint + events
- Migrations (`0021`, `0022`)
- Test-mode dry run with `stripe listen`
- Behaviours, rollback

## 🐳 Docker Architecture

```
┌─────────────────────────────────────────────┐
│              Docker Network                 │
│                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐ │
│  │   Web    │  │   API    │  │    AI    │ │
│  │ (5173)   │  │  (4000)  │  │  (8000)  │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘ │
│       │             │              │       │
│       └─────────────┼──────────────┘       │
│                     │                      │
│            ┌────────▼────────┐             │
│            │   PostgreSQL    │             │
│            │     (5432)      │             │
│            └─────────────────┘             │
│                     │                      │
│            ┌────────▼────────┐             │
│            │      Redis      │             │
│            │     (6380)      │             │
│            └─────────────────┘             │
└─────────────────────────────────────────────┘
```

## 🚀 Quick Deployment

### Development Environment

```bash
# Start all services
pnpm docker:up

# View logs
pnpm docker:logs

# Stop services
pnpm docker:down
```

### Production Build

```bash
# Build all production images
docker compose -f docker-compose.yml build

# Start in production mode
docker compose up -d

# Check status
docker compose ps
```

## 📦 Docker Services

### Service Configuration

| Service | Image | Port(s) | Purpose |
|---------|-------|---------|---------|
| postgres | postgres:15 | 5432 (5433 external) | Database |
| redis | redis:7-alpine | 6380 | Cache |
| api | custom | 4000 | Backend API |
| web | custom | 3000 | Frontend app |
| ai-service | custom | 8000 | AI service |

### Volume Configuration

| Volume | Mount Point | Purpose |
|--------|-------------|---------|
| postgres_data | /var/lib/postgresql/data | Database persistence |
| redis_data | /data | Cache persistence |

## 🔧 Environment Variables

### Required for Production

```bash
# Database
DATABASE_URL="postgresql://user:password@postgres:5432/izri"

# API
API_PORT=4000
NODE_ENV=production
LOG_LEVEL=info

# Web
VITE_API_URL="https://api.yourdomain.com"

# Authentication
GITHUB_CLIENT_ID="your-client-id"
GITHUB_CLIENT_SECRET="your-client-secret"
JWT_SECRET="your-secure-secret"

# AI Service
OPENAI_API_KEY="your-openai-key"
```

### Optional

```bash
# Redis
REDIS_URL="redis://redis:6379"

# OpenTelemetry
OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector:4318"

# Monitoring
SENTRY_DSN="your-sentry-dsn"
```

## 📊 Deployment Checklist

### Pre-Deployment

- [ ] Environment variables configured
- [ ] Secrets properly managed
- [ ] Database migrations ready
- [ ] Production build tested locally
- [ ] Health checks configured
- [ ] Monitoring set up
- [ ] Backup strategy in place

### Deployment

- [ ] Build Docker images
- [ ] Push images to registry
- [ ] Apply database migrations
- [ ] Deploy services
- [ ] Verify health checks
- [ ] Test critical paths
- [ ] Monitor logs

### Post-Deployment

- [ ] Verify all services running
- [ ] Check application functionality
- [ ] Monitor performance metrics
- [ ] Review error logs
- [ ] Update documentation
- [ ] Notify team

## 🏗️ CI/CD Integration

### GitHub Actions (Example)

```yaml
# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Build images
        run: docker compose build
      
      - name: Push to registry
        run: docker compose push
      
      - name: Deploy
        run: |
          ssh user@server "cd /app && docker compose pull && docker compose up -d"
```

## 🔐 Security Best Practices

### Docker Security

```dockerfile
# Use non-root user
USER node

# Scan for vulnerabilities
RUN npm audit

# Minimize layers
RUN apt-get update && apt-get install -y \
    package1 \
    package2 \
    && rm -rf /var/lib/apt/lists/*
```

### Environment Security

- Store secrets in secure vaults (AWS Secrets Manager, etc.)
- Use HTTPS everywhere
- Implement rate limiting
- Regular security updates
- Monitor for vulnerabilities

## 📈 Monitoring & Logging

### Health Checks

```yaml
# docker-compose.yml
services:
  api:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
```

### Logging

```bash
# View logs
docker compose logs -f

# Filter by service
docker compose logs api

# Last 100 lines
docker compose logs --tail=100
```

## 🔗 Platform-Specific Guides

### Railway

See [`railway.md`](./railway.md) for the full walkthrough: project layout, the three per-service config files (`railway.api.json`, `railway.web.json`, `railway.ai-service.json`), managed Postgres + Redis plugins, env-var wiring, and migration steps.

### Render

```yaml
# render.yaml
services:
  - type: web
    name: izri-api
    env: docker
    dockerfilePath: ./docker/api/Dockerfile
```

### Fly.io

```bash
# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Launch app
fly launch

# Deploy
fly deploy
```

## 🔗 Related Documentation

- **Architecture**: [System Overview](../architecture/overview.md)
- **Development**: [Development Guide](../development/README.md)
- **Backend**: [Backend Documentation](../backend/README.md)

---

*Ready to deploy? Start with [Docker Setup](./docker.md) →*