Network Architecture

Complete network topology for RavenmaskOS.

Overview

RavenmaskOS uses a multi-layer networking approach:

Layer	Technology	Purpose
DNS	AWS Route 53	Public DNS for `*.ravenhelm.dev`
Remote Access	Tailscale	Secure mesh VPN between machines
Edge	Traefik	Reverse proxy, TLS termination
Container	Docker Bridge	Internal service communication
WebRTC	Coturn	TURN relay for voice services

Architecture Diagram

                                    INTERNET
                                        │
                                        ▼
                        ┌───────────────────────────────┐
                        │    Route 53 DNS               │
                        │    *.ravenhelm.dev            │
                        │         │                     │
                        │         ▼                     │
                        │    67.198.117.118             │
                        │    (Public IP)                │
                        └───────────────────────────────┘
                                        │
                                        ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                                   ODIN                                     │
│                          (Mac Mini M4 Pro)                                 │
│                                                                            │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                          Tailscale                                   │  │
│  │                      100.115.101.81                                  │  │
│  │  ┌─────────────────────────────────────────────────────────────┐    │  │
│  │  │ Mesh VPN: ravenmask (100.104.134.77), iphone (100.96.122.61)│    │  │
│  │  └─────────────────────────────────────────────────────────────┘    │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                            │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                          Traefik                                     │  │
│  │                        :80 → :443                                    │  │
│  │                   TLS Termination                                    │  │
│  │           Let's Encrypt via Route 53 DNS-01                          │  │
│  │                                                                      │  │
│  │  Routers: norns.ravenhelm.dev → norns-agent:8000                    │  │
│  │           gitlab.ravenhelm.dev → gitlab:8080                        │  │
│  │           auth.ravenhelm.dev → zitadel:8080                         │  │
│  │           ...                                                        │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                        │                                   │
│                                        ▼                                   │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                      ravenhelm_net                                   │  │
│  │                    (Docker Bridge)                                   │  │
│  │                                                                      │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │  │
│  │  │ postgres │ │  redis   │ │  norns   │ │ livekit  │ │  gitlab  │  │  │
│  │  │  :5432   │ │  :6379   │ │  :8000   │ │  :7880   │ │  :8080   │  │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │  │
│  │  ... (45+ containers)                                               │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                            │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                          Coturn                                      │  │
│  │                     (network_mode: host)                             │  │
│  │         STUN/TURN :3478, Media Relay :49152-49200                   │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                            │
└───────────────────────────────────────────────────────────────────────────┘

DNS Configuration

Route 53

All *.ravenhelm.dev records point to odin's public IP:

Record	Type	Value
`*.ravenhelm.dev`	A	67.198.117.118
`ravenhelm.dev`	A	67.198.117.118

Subdomains

Subdomain	Service	Notes
`auth`	Zitadel	Identity provider
`norns`	Norns Agent	AI platform
`bifrost`	Bifrost Admin	MCP gateway UI
`bifrost-api`	Bifrost API	MCP gateway API
`gitlab`	GitLab CE	Source control
`registry`	GitLab Registry	Container images
`grafana`	Grafana	Observability
`n8n`	n8n	Automation
`voice`	Voice Gateway	Web voice UI
`telephony`	Telephony	Phone voice
`livekit`	LiveKit	WebRTC server
`langfuse`	Langfuse	LLM tracing
`dashboard`	Homepage	Service dashboard
`ha`	Home Assistant	Smart home
`homebridge`	Homebridge	HomeKit bridge
`vault`	OpenBao	Secrets (planned)

TLS Certificates

Traefik automatically obtains and renews certificates via Let's Encrypt DNS-01 challenge:

certificatesResolvers:
  letsencrypt:
    acme:
      email: nate@ravenhelm.dev
      storage: /certs/acme.json
      dnsChallenge:
        provider: route53

Required AWS credentials:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_HOSTED_ZONE_ID

Tailscale Mesh VPN

Secure remote access between machines:

Node	Tailscale IP	OS	Purpose
odin	100.115.101.81	macOS	App server
ravenmask	100.104.134.77	macOS	Workstation
iphone172	100.96.122.61	iOS	Mobile

Access Patterns

# SSH to odin via Tailscale
ssh ravenhelm@100.115.101.81

# SSH via hostname (if MagicDNS enabled)
ssh ravenhelm@odin

MagicDNS

Tailscale provides automatic DNS for connected devices at *.ravenhelm.ts.net.

Docker Networking

ravenhelm_net

All containers run on a shared bridge network:

# Create network (one-time)
docker network create ravenhelm_net

# List connected containers
docker network inspect ravenhelm_net | jq '.[0].Containers | keys[]'

Container DNS

Containers can reach each other by name:

# From any container
curl http://docs/AI-ML-Platform/norns-agent:8000/health
curl http://postgres:5432
curl http://docs/infrastructure/redis:6379

Port Exposure

Most services are internal-only, accessed via Traefik. Key external ports:

Port	Service	Protocol
80	Traefik	HTTP (redirects to 443)
443	Traefik	HTTPS
2222	GitLab SSH	SSH
3478	Coturn	STUN/TURN
5349	Coturn	TURNS (TLS)
7881	LiveKit	WebRTC TCP
50000-50100	LiveKit	WebRTC UDP
49152-49200	Coturn	TURN relay UDP

Routing Rules

Traefik Router Pattern

Services are exposed via Docker labels:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.myservice.rule=Host(\`myservice.ravenhelm.dev\`)"
  - "traefik.http.routers.myservice.entrypoints=websecure"
  - "traefik.http.routers.myservice.tls.certresolver=letsencrypt"
  - "traefik.http.services.myservice.loadbalancer.server.port=8000"

Path-Based Routing

Some services use path prefixes:

# Voice Platform
- "traefik.http.routers.voice-api.rule=Host(\`voice.ravenhelm.dev\`) && PathPrefix(\`/api\`)"
- "traefik.http.routers.voice-frontend.rule=Host(\`voice.ravenhelm.dev\`)"

Dynamic Configuration

For services that need special handling (h2c, headers):

# ~/ravenhelm/data/traefik/config/dynamic/zitadel.yml
http:
  routers:
    zitadel:
      rule: "Host(\`auth.ravenhelm.dev\`)"
      service: zitadel
      tls:
        certResolver: letsencrypt

  services:
    zitadel:
      loadBalancer:
        passHostHeader: true
        servers:
          - url: "h2c://zitadel:8080"  # gRPC-web support

Firewall

macOS Firewall (Odin)

# Allow incoming connections for key services
# Managed via System Preferences > Security > Firewall

Router Port Forwarding

External Port	Internal Port	Service
80	80	Traefik HTTP
443	443	Traefik HTTPS
2222	2222	GitLab SSH
3478	3478	Coturn STUN
7881	7881	LiveKit TCP
50000-50100	50000-50100	LiveKit UDP

Troubleshooting

DNS Resolution

# Check public DNS
dig +short norns.ravenhelm.dev

# Check from container
docker exec traefik nslookup norns-agent

TLS Issues

# Check certificate
echo | openssl s_client -servername norns.ravenhelm.dev \
  -connect norns.ravenhelm.dev:443 2>/dev/null | \
  openssl x509 -noout -dates

# View ACME log
docker logs traefik 2>&1 | grep -i acme

Container Connectivity

# Test internal DNS
docker exec norns-agent nslookup postgres

# Test internal connectivity
docker exec norns-agent curl -f http://postgres:5432 || echo "No HTTP (expected)"

# Verify network membership
docker network inspect ravenhelm_net | jq '.[0].Containers'

Tailscale Connectivity

# Check status
tailscale status

# Ping remote node
tailscale ping odin

# Debug connectivity
tailscale netcheck

Overview​

Architecture Diagram​

DNS Configuration​

Route 53​

Subdomains​

TLS Certificates​

Tailscale Mesh VPN​

Access Patterns​

MagicDNS​

Docker Networking​

ravenhelm_net​

Container DNS​

Port Exposure​

Routing Rules​

Traefik Router Pattern​

Path-Based Routing​

Dynamic Configuration​

Firewall​

macOS Firewall (Odin)​

Router Port Forwarding​

Troubleshooting​

DNS Resolution​

TLS Issues​

Container Connectivity​

Tailscale Connectivity​

See Also​