Skip to main content

Infrastructure

Core platform services that form the foundation of RavenmaskOS.

Overview​

The infrastructure layer provides essential services for routing, data persistence, caching, and platform management. Identity and secrets management are documented separately in Identity Management.

┌─────────────────────────────────────────────────────────────────────┐
│                          INFRASTRUCTURE                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │                       Traefik                                │   │
│   │              Reverse Proxy / Load Balancer                   │   │
│   │                 TLS Termination                              │   │
│   └─────────────────────────────────────────────────────────────┘   │
│                              │                                       │
│     ┌────────────────────────┼────────────────────────┐             │
│     ▼                        ▼                        ▼             │
│   ┌──────────────┐   ┌──────────────┐   ┌──────────────────────┐   │
│   │  PostgreSQL  │   │    Redis     │   │      Bifrost         │   │
│   │   Database   │   │    Cache     │   │   MCP Gateway &      │   │
│   │  + pgvector  │   │              │   │   AIOps Platform     │   │
│   └──────────────┘   └──────────────┘   └──────────────────────┘   │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

For Identity & Access Management, see: Identity-Management

Services​

ServicePurposeURL
TraefikReverse proxy, TLS termination, routingtraefik.ravenhelm.dev
PostgreSQLPrimary database (+ pgvector)Internal (5432)
RedisCaching, sessions, rate limitingInternal (6379)
BifrostMCP Gateway, AIOps, CMDB, Admin Portalbifrost.ravenhelm.dev
Docker Socket ProxySecure Docker API accessInternal (2375)
Landing PagePublic landing pageravenhelm.dev

Identity Services: See Identity Management for Zitadel, OAuth2-Proxy, SPIRE, OpenBao, and OpenFGA.

Bifrost Platform​

Bifrost serves as the central control plane providing:

  • MCP Gateway - Tool management and execution routing for AI agents
  • Communications Hub - Slack, email, webhook channel management
  • AIOps Platform - Alert ingestion, CMDB, discovery, incident management
  • Admin Portal - Web UI for agents, tools, and integrations

See [[Infrastructure/Bifrost]] for complete documentation.

Network Topology​

All services run on the ravenhelm_net Docker bridge network:

ravenhelm_net (Docker bridge)
├── traefik        :80, :443 (public)
├── postgres       :5432 (internal)
├── redis          :6379 (internal)
├── bifrost-api    :8000 (internal)
└── bifrost-admin  :3000 (internal)

Service Dependencies​

PostgreSQL ◀─── Used by:
    ├── Zitadel (identity)
    ├── Norns (tasks, projects, memories)
    ├── Bifrost (MCP tools, API keys, CMDB, AIOps)
    ├── GitLab (repositories, CI/CD)
    ├── Grafana (dashboards, alerts)
    ├── Langfuse (LLM traces)
    └── n8n (workflows)

Redis ◀─── Used by:
    ├── Norns (session cache, context)
    ├── Bifrost (permissions cache)
    ├── n8n (queue, cache)
    └── Rate limiting

Traefik ◀─── Routes to:
    └── All web services (*.ravenhelm.dev)

Bifrost ◀─── Integrates with:
    ├── Norns (agent delegation)
    ├── n8n (workflow execution)
    ├── GitLab (incident tracking)
    ├── Docker (container discovery)
    ├── Prometheus (target discovery)
    └── Traefik (service discovery)

Quick Commands​

# Check infrastructure services
for svc in traefik postgres redis bifrost-api bifrost-admin; do
  echo "=== $svc ==="
  docker ps --filter "name=^${svc}$" --format "{{.Names}}: {{.Status}}"
done

# PostgreSQL health
docker exec postgres pg_isready -U ravenhelm

# Redis health
docker exec redis redis-cli PING

# Traefik health
curl -s http://localhost:8080/ping

# Bifrost health
curl -s https://bifrost-api.ravenhelm.dev/health

Data Locations​

ServiceData PathBackup Priority
PostgreSQL~/ravenhelm/data/postgres/Critical
Redis~/ravenhelm/data/docs/infrastructure/redis/High
Traefik~/ravenhelm/data/traefik/High (certs, config)
BifrostDatabase (PostgreSQL)Critical

Secrets Required​

# Core infrastructure secrets in ~/ravenhelm/secrets/.env

# PostgreSQL
POSTGRES_USER=ravenhelm
POSTGRES_PASSWORD=<generated>

# Redis
REDIS_PASSWORD=<generated>

# Traefik (Let's Encrypt DNS-01 via Route 53)
AWS_ACCESS_KEY_ID=<key>
AWS_SECRET_ACCESS_KEY=<secret>
AWS_HOSTED_ZONE_ID=<zone-id>

# Bifrost
BIFROST_API_KEY=<generated>
BIFROST_ZITADEL_CLIENT_ID=<from-zitadel>
BIFROST_ZITADEL_CLIENT_SECRET=<from-zitadel>
AUTH_SECRET=<generated>