Deployment Guide: Docker Compose

This guide will walk you through deploying the entire RitualOS ecosystem locally using Docker Compose.

Prerequisites

• Docker 24.0+
• Docker Compose 2.20+
• 8GB RAM minimum
• 20GB disk space
• Node.js 20+ (for local development)

Quick Start

1. Clone Repository

git clone https://github.com/ritualos/ecosystem.git
cd ecosystem

2. Configure Environment Variables

cp .env.example .env

Edit .env with your configuration:

# Database
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_USER=ritualos
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=ritualos

# ID Service
ID_SERVICE_URL=http://id:7000
JWT_SECRET=your-secret-key-min-32-characters
SESSION_SECRET=your-session-secret-min-32-characters
ISSUER_API_KEY=rit_sk_your_secret_issuer_key

# OAuth
OAUTH_REDIRECT_URI=http://localhost:3010/auth/callback

3. Start Services

docker-compose up -d

4. Initialize Databases

# Run migrations for each service
docker-compose exec id npx prisma migrate deploy
docker-compose exec path npx prisma migrate deploy
docker-compose exec scroll npx prisma migrate deploy
docker-compose exec learn npx prisma migrate deploy
docker-compose exec governance npx prisma migrate deploy
docker-compose exec guild npx prisma migrate deploy
docker-compose exec market npx prisma migrate deploy

5. Verify Deployment

# Check all services are running
docker-compose ps

# Test health endpoints
curl http://localhost:7000/api/health
curl http://localhost:3003/api/health
curl http://localhost:3004/api/health

Service Configuration

Port Mapping

Docker Compose Configuration

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ritualos
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ritualos
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ritualos"]
      interval: 10s
      timeout: 5s
      retries: 5

  id:
    build: ./id.ritualos.com
    environment:
      DATABASE_URL: postgresql://ritualos:${POSTGRES_PASSWORD}@postgres:5432/ritualos
      PORT: 7000
      JWT_SECRET: ${JWT_SECRET}
      SESSION_SECRET: ${SESSION_SECRET}
      ISSUER_API_KEY: ${ISSUER_API_KEY}
    ports:
      - "7000:7000"
    depends_on:
      postgres:
        condition: service_healthy

  path:
    build: ./path.ritualos.com
    environment:
      DATABASE_URL: postgresql://ritualos:${POSTGRES_PASSWORD}@postgres:5432/ritualos
      PORT: 3003
      ID_SERVICE_URL: http://id:7000
    ports:
      - "3003:3003"
    depends_on:
      - postgres
      - id

  # ... additional services

volumes:
  postgres_data:

Database Setup

Single Database vs Multiple

The RitualOS ecosystem can use either:

Option 1: Single Database (Recommended for MVP)

• One PostgreSQL instance
• Schema-based separation
• Simpler backup and maintenance

Option 2: Multiple Databases

• Separate database per service
• Better isolation
• More complex management

Schema Creation

-- Create schemas for each service
CREATE SCHEMA IF NOT EXISTS id_service;
CREATE SCHEMA IF NOT EXISTS path_service;
CREATE SCHEMA IF NOT EXISTS scroll_service;
CREATE SCHEMA IF NOT EXISTS learn_service;
CREATE SCHEMA IF NOT EXISTS governance_service;
CREATE SCHEMA IF NOT EXISTS guild_service;
CREATE SCHEMA IF NOT EXISTS market_service;

Health Checks

All services expose a /api/health endpoint:

Logging & Monitoring

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f id

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

Log Aggregation

# Add to docker-compose.yml
services:
  # ... other services
  
  loki:
    image: grafana/loki:latest
    ports:
      - "3100:3100"
    command: -config.file=/etc/loki/local-config.yaml
    
  promtail:
    image: grafana/promtail:latest
    volumes:
      - /var/log:/var/log:ro
      - ./promtail-config.yml:/etc/promtail/config.yml:ro

Troubleshooting

Service Won't Start

# Check logs
docker-compose logs [service-name]

# Rebuild without cache
docker-compose build --no-cache [service-name]

# Reset everything
docker-compose down -v
docker-compose up -d

Database Connection Issues

# Check postgres is running
docker-compose ps postgres

# View postgres logs
docker-compose logs postgres

# Test connection
docker-compose exec postgres psql -U ritualos -d ritualos

Port Conflicts

# Check what's using a port
netstat -tuln | grep :7000

# Or use lsof (macOS)
lsof -i :7000

# Change port in .env
ID_SERVICE_PORT=7001

Production Considerations

Security

1. Change all default passwords
2. Use strong secrets (32+ characters)
3. Enable SSL/TLS for all services
4. Configure firewall rules
5. Regular security updates

Performance

1. Enable connection pooling
2. Configure Redis for caching
3. Use CDN for static assets
4. Enable gzip compression
5. Configure load balancer

Backup Strategy

# Database backup
docker-compose exec postgres pg_dump -U ritualos ritualos > backup.sql

# Automated backups
cat > backup.sh <<'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
docker-compose exec -T postgres pg_dump -U ritualos ritualos > backups/$DATE.sql
# Keep last 7 days
find backups/ -mtime +7 -delete
EOF

chmod +x backup.sh
# Run daily via cron

Monitoring

Install monitoring stack:

services:
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

Scaling

Vertical Scaling

# Add to docker-compose.yml
services:
  id:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
        reservations:
          cpus: '1.0'
          memory: 2G

Horizontal Scaling

# Scale a service
docker-compose up -d --scale path=3

# Requires load balancer

Environment Variables Reference

Complete list in Environment Variables Reference.

Required Variables

# Core
DATABASE_URL=postgresql://user:pass@host:5432/db
JWT_SECRET=secret-min-32-chars
SESSION_SECRET=secret-min-32-chars
ISSUER_API_KEY=rit_sk_secret_key

# OAuth
OAUTH_REDIRECT_URI=https://yourdomain.com/auth/callback

# Optional
REDIS_URL=redis://redis:6379
S3_BUCKET=ritualos-assets

Next Steps

1. Configure OAuth clients for each service
2. Set up SSL certificates (use Let's Encrypt)
3. Configure backup automation
4. Set up monitoring and alerting
5. Review security checklist

Related Documentation

• Environment Variables
• Port Configuration
• Deployment Checklist
• Architecture

---

Deployment Status: ✅ Ready for Production Last Updated: March 10, 2026