Container Management

Standardized patterns for deploying and managing Docker containers in RavenmaskOS.

Directory Structure

~/ravenhelm/
├── services/           # Docker compose files per service
│   ├── _template/      # Base template for new services
│   ├── norns/
│   ├── bifrost/
│   ├── livekit/
│   └── ...
├── data/              # Persistent volumes
│   ├── postgres/
│   ├── redis/
│   └── ...
├── secrets/           # Centralized secrets
│   └── .env           # Master environment file
├── scripts/           # Management scripts
│   ├── backup/
│   ├── deploy/
│   ├── maintenance/
│   └── utils/
└── backups/           # Backup storage
    └── daily/

Service Template

All services follow this standard pattern:

version: "3.9"

services:
  service-name:
    image: image:tag
    container_name: service-name
    restart: unless-stopped
    networks:
      - ravenhelm_net
    environment:
      - TZ=America/Chicago
    env_file:
      - .env    # Symlinked to ../../secrets/.env
    volumes:
      - ../../data/service-name:/data
    labels:
      - "com.ravenhelm.service=service-name"
      - "traefik.enable=true"
      - "traefik.http.routers.service-name.rule=Host(\`service-name.ravenhelm.dev\`)"
      - "traefik.http.routers.service-name.entrypoints=websecure"
      - "traefik.http.routers.service-name.tls.certresolver=letsencrypt"

networks:
  ravenhelm_net:
    external: true

Key patterns:

• Network: All services join ravenhelm_net
• Secrets: Symlink .env to central secrets file
• Data: Volumes in ../../data/service-name
• Labels: Custom label + Traefik routing

Deployment Scripts

Deploy a Service

# Usage: ./scripts/deploy/deploy-service.sh <service-name>

# Example
./scripts/deploy/deploy-service.sh norns

The script:

1. Validates service directory exists
2. Creates data directory if needed
3. Creates secrets symlink if missing
4. Pulls latest images
5. Starts containers
6. Shows status

Update All Services

./scripts/deploy/update-all.sh

Backup Scripts

Full Backup

./scripts/backup/backup-all.sh

Creates a timestamped backup including:

• Data volumes (excluding logs)
• Secrets directory
• Service configurations
• PostgreSQL database dump
• Backup manifest

Backups stored in ~/ravenhelm/backups/daily/. Keeps last 7 days.

PostgreSQL Backup

./scripts/backup/backup-postgres.sh

Volume Backup

./scripts/backup/backup-volumes.sh

Common Operations

Start/Stop Services

# Start a service
cd ~/ravenhelm/docs/AI-ML-Platform/norns-agent
docker-compose up -d

# Stop a service
docker-compose down

# View logs
docker-compose logs -f

# Restart
docker-compose restart

View Container Status

# All containers
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

# Specific service
docker-compose ps

# Resource usage
docker stats --no-stream

Access Container Shell

# Execute command
docker exec -it postgres psql -U ravenhelm -d ravenmaskos

# Interactive shell
docker exec -it norns-agent /bin/bash

Network Inspection

# List networks
docker network ls

# Inspect ravenhelm_net
docker network inspect ravenhelm_net

# Find container IP
docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' container_name

Creating New Services

1. Copy template:

   cp -r ~/ravenhelm/services/_template ~/ravenhelm/services/newservice

2. Edit docker-compose.yml:

   • Update image, container_name
   • Configure volumes, ports
   • Set Traefik labels

3. Link secrets:

   ln -s ../../secrets/.env ~/ravenhelm/services/newservice/.env

4. Deploy:

   ./scripts/deploy/deploy-service.sh newservice

Running Containers

Current service inventory (45+ containers):

Category	Services
Core	traefik, postgres, redis
Identity	zitadel, oauth2-proxy, openbao, spire-server
AI/ML	norns-agent, langgraph, ollama
Bifrost	bifrost-api, bifrost-admin
Voice	livekit, voice-api, voice-agent, voice-frontend, piper, whisper, coturn
Telephony	telephony
Observability	grafana, loki, tempo, alloy, langfuse
Automation	n8n, gitlab
Smart Home	homebridge, homeassistant, grocy
Utility	homepage, landing, uptime-kuma

Troubleshooting

Container Won't Start

# Check logs
docker-compose logs --tail=100

# Check for port conflicts
docker ps --format '{{.Names}}: {{.Ports}}'
lsof -i :PORT

# Verify network exists
docker network ls | grep ravenhelm_net

Out of Disk Space

# Check disk usage
df -h

# Docker disk usage
docker system df

# Cleanup unused resources
docker system prune -a --volumes

Container OOM Killed

# Check events
docker events --since 24h --filter 'type=container'

# Check container memory limit
docker inspect -f '{{.HostConfig.Memory}}' container_name

# Increase in compose file
services:
  myservice:
    deploy:
      resources:
        limits:
          memory: 4G

See Also

• [[Docker-Colima]] - Container runtime configuration
• [[GitLab]] - CI/CD integration
• [[../Operations/Backup]] - Backup procedures
• [[../Operations/Deployment]] - Deployment procedures