Core Stack Installation

The Core Stack provides the foundational infrastructure that all other RavenmaskOS services depend on. This includes container orchestration, reverse proxy with SSL, database, and caching layers.

Overview

Component	Purpose	Image
Colima	Docker runtime for macOS	N/A (brew install)
Traefik	Reverse proxy with automatic SSL	traefik:v3.2
PostgreSQL	Primary database with vector support	pgvector/pgvector:pg16
Redis	Caching and session storage	redis:7-alpine

Prerequisites

Ensure you have completed all steps in the Prerequisites guide before proceeding.

Step 1: Install and Configure Colima

Colima provides Docker runtime on macOS without Docker Desktop.

Install Colima

brew install colima docker docker-compose

Start Colima

# Start with recommended resources for RavenmaskOS
colima start --cpu 4 --memory 8 --disk 100 --vm-type vz --vz-rosetta

Configure Auto-start

# Create LaunchAgent for auto-start
mkdir -p ~/Library/LaunchAgents

cat > ~/Library/LaunchAgents/com.colima.default.plist << 'PLIST'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.colima.default</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/colima</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <false/>
</dict>
</plist>
PLIST

launchctl load ~/Library/LaunchAgents/com.colima.default.plist

Step 2: Create Docker Network

All services communicate over a shared Docker network.

docker network create ravenhelm_net

Step 3: Set Up Directory Structure

mkdir -p ~/ravenhelm/{services,data,secrets,backups,compose}
mkdir -p ~/ravenhelm/data/{traefik/certs,postgres,redis}

Step 4: Configure Environment Variables

Create the main secrets file:

cat > ~/ravenhelm/secrets/.env << 'ENV'
# PostgreSQL
POSTGRES_USER=ravenhelm
POSTGRES_PASSWORD=<generate-secure-password>
POSTGRES_DB=ravenmaskos

# Redis
REDIS_PASSWORD=<generate-secure-password>

# AWS Route53 (for DNS-01 challenges)
AWS_ACCESS_KEY_ID=<your-aws-access-key>
AWS_SECRET_ACCESS_KEY=<your-aws-secret-key>
AWS_HOSTED_ZONE_ID=<your-hosted-zone-id>

# Domain
DOMAIN=ravenhelm.dev
ENV

chmod 600 ~/ravenhelm/secrets/.env

Generating Secure Passwords

Use openssl rand -base64 32 to generate secure random passwords.

Step 5: Deploy Traefik

Traefik serves as the reverse proxy, handling SSL certificates via Let's Encrypt.

Create Traefik Configuration

mkdir -p ~/ravenhelm/services/traefik

cat > ~/ravenhelm/services/traefik/traefik.yml << 'TRAEFIK'
api:
  dashboard: true
  insecure: false

entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
    network: ravenhelm_net

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@ravenhelm.dev
      storage: /certs/acme.json
      dnsChallenge:
        provider: route53
        delayBeforeCheck: 10s
        resolvers:
          - "1.1.1.1:53"
          - "8.8.8.8:53"
TRAEFIK

Create Docker Compose File

cat > ~/ravenhelm/services/traefik/docker-compose.yml << 'COMPOSE'
services:
  traefik:
    image: traefik:v3.2
    container_name: traefik
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    environment:
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
      - AWS_HOSTED_ZONE_ID=${AWS_HOSTED_ZONE_ID}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik.yml:/etc/traefik/traefik.yml:ro
      - /Users/ravenhelm/ravenhelm/data/traefik/certs:/certs
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.traefik.rule=Host(`traefik.${DOMAIN}`)"
      - "traefik.http.routers.traefik.entrypoints=websecure"
      - "traefik.http.routers.traefik.tls.certresolver=letsencrypt"
      - "traefik.http.routers.traefik.service=api@internal"
      - "traefik.http.routers.traefik.middlewares=auth"
      - "traefik.http.middlewares.auth.basicauth.users=admin:$apr1$..."
    networks:
      - ravenhelm_net

networks:
  ravenhelm_net:
    external: true
COMPOSE

Deploy Traefik

cd ~/ravenhelm/services/traefik
docker compose --env-file ~/ravenhelm/secrets/.env up -d

Verify Deployment

# Check container status
docker ps | grep traefik

# Check logs
docker logs traefik --tail 50

# Verify SSL certificate (after DNS propagation)
curl -I https://traefik.ravenhelm.dev

Step 6: Deploy PostgreSQL

PostgreSQL serves as the primary database with pgvector extension for AI/ML workloads.

Create Docker Compose File

mkdir -p ~/ravenhelm/services/postgres

cat > ~/ravenhelm/services/postgres/docker-compose.yml << 'COMPOSE'
services:
  postgres:
    image: pgvector/pgvector:pg16
    container_name: postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - /Users/ravenhelm/ravenhelm/data/postgres:/var/lib/docs/infrastructure/postgresql/data
    networks:
      - ravenhelm_net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  ravenhelm_net:
    external: true
COMPOSE

Deploy PostgreSQL

cd ~/ravenhelm/services/postgres
docker compose --env-file ~/ravenhelm/secrets/.env up -d

Verify and Initialize

# Check container status
docker ps | grep postgres

# Connect and verify pgvector extension
docker exec -it postgres psql -U ravenhelm -d ravenmaskos -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Verify extension
docker exec -it postgres psql -U ravenhelm -d ravenmaskos -c "SELECT extname FROM pg_extension;"

Step 7: Deploy Redis

Redis provides caching and session storage for various services.

Create Docker Compose File

mkdir -p ~/ravenhelm/services/docs/infrastructure/redis

cat > ~/ravenhelm/services/docs/infrastructure/redis/docker-compose.yml << 'COMPOSE'
services:
  redis:
    image: redis:7-alpine
    container_name: redis
    restart: unless-stopped
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - /Users/ravenhelm/ravenhelm/data/docs/infrastructure/redis:/data
    networks:
      - ravenhelm_net
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  ravenhelm_net:
    external: true
COMPOSE

Deploy Redis

cd ~/ravenhelm/services/docs/infrastructure/redis
docker compose --env-file ~/ravenhelm/secrets/.env up -d

Verify Deployment

# Check container status
docker ps | grep redis

# Test connection
docker exec -it redis redis-cli -a "$REDIS_PASSWORD" ping

Verification

After deploying all core services, verify the entire stack:

# List all running containers
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Expected output should show:
# - traefik (healthy)
# - postgres (healthy)
# - redis (healthy)

# Check network connectivity
docker network inspect ravenhelm_net | grep -A 5 "Containers"

Troubleshooting

Traefik Not Issuing Certificates

1. Verify AWS credentials are correct
2. Check DNS propagation: dig traefik.ravenhelm.dev
3. Review Traefik logs: docker logs traefik | grep -i acme
4. Ensure Route53 hosted zone ID is correct

PostgreSQL Connection Refused

1. Check container is running: docker ps | grep postgres
2. Verify health check: docker inspect postgres | grep -A 10 Health
3. Check logs: docker logs postgres
4. Ensure network connectivity from other containers

Redis Authentication Failed

1. Verify password in .env file
2. Check Redis logs: docker logs redis
3. Test with explicit password: docker exec -it redis redis-cli -a "yourpassword" ping

Next Steps

With the Core Stack deployed, proceed to:

1. Identity Stack - Set up Zitadel for authentication
2. Observability Stack - Deploy monitoring and logging