Deployment Documentation

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

🚀 Quick Deployment

Development Environment

# Start all services
pnpm docker:up

# View logs
pnpm docker:logs

# Stop services
pnpm docker:down

Production Build

# 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

# 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

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

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

# 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

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

Logging

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

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

Fly.io

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

# Launch app
fly launch

# Deploy
fly deploy

🔗 Related Documentation

Architecture: System Overview
Development: Development Guide
Backend: Backend Documentation

Ready to deploy? Start with Docker Setup →