Runner Services Role

Comprehensive multi-service deployment role that sets up production-ready containerized services with NFS storage integration and proper networking.

Services Deployed

CCTV & Security

• Frigate - AI-powered NVR with person/vehicle detection
  • MQTT integration, RTSP camera feeds
  • Hardware acceleration support
  • NFS storage for recordings

Media & Content

• Immich - High-performance photo management

  • Multi-container stack (server, ML, Redis, PostgreSQL)
  • Hardware-accelerated machine learning
  • NFS storage for photos

• Ghost CMS - Headless content management system

  • MySQL database backend
  • Mail server integration
  • Content API for websites

Development & Documentation

• Forgejo - Self-hosted Git service

  • SSH and HTTP Git access
  • Issue tracking and CI/CD
  • NFS storage for repositories

• Stirling-PDF - PDF processing service

  • OCR, conversion, manipulation
  • Caddy CORS proxy for API access
  • REST API for integration

Productivity

• Tandoor - Recipe management system
  • Meal planning and shopping lists
  • Local SQLite storage
  • Recipe import/export

Architecture

Storage Strategy

• Local NVMe: Databases and application configs (fast access)
• NFS Mounts: Bulk data storage (photos, videos, repos)
• Automatic Mounting: systemd mount units with failover

Network Configuration

• Internal Docker Networks: Service-to-service communication
• Host Network Access: Direct port binding for select services
• Reverse Proxy Ready: Caddy integration for CORS and SSL termination
• API Access: Services accessible both locally and via API endpoints

Security Features

• Vault Integration: All secrets managed via ansible-vault
• Environment Isolation: Separate .env files per service
• Network Segmentation: Docker networks with controlled access

Prerequisites

NFS Server Setup

• NAS server with exports configured for:
  • /mnt/rstorage/cctv-data → Frigate recordings
  • /mnt/rstorage/media/pictures → Immich photo library
  • /mnt/rstorage/code-repo → Forgejo repositories
  • /mnt/rstorage/registry-data → Harbor registry (manual setup)

Hardware Requirements

• CPU: 4+ cores recommended (ML workloads for Frigate/Immich)
• RAM: 16GB+ for full stack
• Storage: Fast NVMe for databases, NFS for bulk data
• Network: Gigabit for NFS performance

Software Dependencies

• Docker and Docker Compose
• NFS client utilities
• systemd for mount management

Configuration

Vault Variables

Store sensitive data in group_vars/vault.yml:

vault_runner:
  # Database passwords
  postgres_password: "secure_password"
  mysql_password: "secure_password"
  mysql_root_password: "secure_root_password"
  
  # API keys and tokens
  frigate_mqtt_password: "mqtt_password"
  
  # Camera credentials (RTSP)
  camera_credentials:
    front_door:
      username: "camera_user"
      password: "camera_pass"
      host: "192.168.1.100"

Host Variables

Configure per-host in host_vars/runner-host.yml:

runner_enabled: true

# Network settings
runner_network_subnet: "192.168.1.0/24"
runner_nas_host: "192.168.1.200"

# Service configuration
frigate_cameras:
  - name: "front_door"
    host: "{{ vault_runner.camera_credentials.front_door.host }}"
    
immich_enable_ml: true
immich_enable_facial_recognition: true

ghost_site_url: "https://blog.example.com"

Service Details

Port Allocation

• Frigate: 5000 (Web UI), 1935 (RTMP), 8554 (RTSP)
• Immich: 2283 (Web UI/API), 3001 (Machine Learning)
• Forgejo: 3000 (Web), 2222 (SSH)
• Stirling-PDF: 8080 (App), 8081 (Caddy CORS Proxy)
• Tandoor: 8010 (Web UI)
• Ghost: 2368 (Web/API)

Data Paths

• Local Config: /docker/runner/ (service configurations)
• Local Data: /docker/runner-data/ (databases, caches)
• NFS Mounts: /mnt/docker/ (bulk data storage)

Management Commands

Generated scripts for service management:

• runner-status.sh - Check all service status
• runner-logs.sh - View service logs
• runner-restart.sh - Restart all services
• runner-update.sh - Update container images

Monitoring

Logging

• Centralized logging via Docker
• Log rotation and retention
• Service-specific log levels

API Integration

Services designed for integration with website containers:

• Ghost CMS: Content API for blogs/websites
• Stirling-PDF: Document processing API
• Immich: Photo gallery API
• Forgejo: Git webhook integration

Backup Strategy

Data Protection

• Configuration files → managed via Infrastructure as Code
• Database persistence → local storage with regular snapshots
• NFS data → handled by NAS backup systems

Usage Examples

# Deploy all services
ansible-playbook runner.yml -i inventory/hosts

# Deploy specific service
ansible-playbook runner.yml -i inventory/hosts --tags frigate

# Update service configuration
ansible-playbook runner.yml -i inventory/hosts --tags config