runner
5 KB•MD
README.md
5 KB • 178 lines • markdown
1# Runner Services Role
2
3Comprehensive multi-service deployment role that sets up production-ready containerized services with NFS storage integration and proper networking.
4
5## Services Deployed
6
7### CCTV & Security
8- **Frigate** - AI-powered NVR with person/vehicle detection
9 - MQTT integration, RTSP camera feeds
10 - Hardware acceleration support
11 - NFS storage for recordings
12
13### Media & Content
14- **Immich** - High-performance photo management
15 - Multi-container stack (server, ML, Redis, PostgreSQL)
16 - Hardware-accelerated machine learning
17 - NFS storage for photos
18
19- **Ghost CMS** - Headless content management system
20 - MySQL database backend
21 - Mail server integration
22 - Content API for websites
23
24### Development & Documentation
25- **Forgejo** - Self-hosted Git service
26 - SSH and HTTP Git access
27 - Issue tracking and CI/CD
28 - NFS storage for repositories
29
30- **Stirling-PDF** - PDF processing service
31 - OCR, conversion, manipulation
32 - Caddy CORS proxy for API access
33 - REST API for integration
34
35### Productivity
36- **Tandoor** - Recipe management system
37 - Meal planning and shopping lists
38 - Local SQLite storage
39 - Recipe import/export
40
41## Architecture
42
43### Storage Strategy
44- **Local NVMe**: Databases and application configs (fast access)
45- **NFS Mounts**: Bulk data storage (photos, videos, repos)
46- **Automatic Mounting**: systemd mount units with failover
47
48### Network Configuration
49- **Internal Docker Networks**: Service-to-service communication
50- **Host Network Access**: Direct port binding for select services
51- **Reverse Proxy Ready**: Caddy integration for CORS and SSL termination
52- **API Access**: Services accessible both locally and via API endpoints
53
54### Security Features
55- **Vault Integration**: All secrets managed via ansible-vault
56- **Environment Isolation**: Separate .env files per service
57- **Network Segmentation**: Docker networks with controlled access
58
59## Prerequisites
60
61### NFS Server Setup
62- NAS server with exports configured for:
63 - `/mnt/rstorage/cctv-data` â Frigate recordings
64 - `/mnt/rstorage/media/pictures` â Immich photo library
65 - `/mnt/rstorage/code-repo` â Forgejo repositories
66 - `/mnt/rstorage/registry-data` â Harbor registry (manual setup)
67
68### Hardware Requirements
69- **CPU**: 4+ cores recommended (ML workloads for Frigate/Immich)
70- **RAM**: 16GB+ for full stack
71- **Storage**: Fast NVMe for databases, NFS for bulk data
72- **Network**: Gigabit for NFS performance
73
74### Software Dependencies
75- Docker and Docker Compose
76- NFS client utilities
77- systemd for mount management
78
79## Configuration
80
81### Vault Variables
82Store sensitive data in `group_vars/vault.yml`:
83```yaml
84vault_runner:
85 # Database passwords
86 postgres_password: "secure_password"
87 mysql_password: "secure_password"
88 mysql_root_password: "secure_root_password"
89
90 # API keys and tokens
91 frigate_mqtt_password: "mqtt_password"
92
93 # Camera credentials (RTSP)
94 camera_credentials:
95 front_door:
96 username: "camera_user"
97 password: "camera_pass"
98 host: "192.168.1.100"
99```
100
101### Host Variables
102Configure per-host in `host_vars/runner-host.yml`:
103```yaml
104runner_enabled: true
105
106# Network settings
107runner_network_subnet: "192.168.1.0/24"
108runner_nas_host: "192.168.1.200"
109
110# Service configuration
111frigate_cameras:
112 - name: "front_door"
113 host: "{{ vault_runner.camera_credentials.front_door.host }}"
114
115immich_enable_ml: true
116immich_enable_facial_recognition: true
117
118ghost_site_url: "https://blog.example.com"
119```
120
121## Service Details
122
123### Port Allocation
124- **Frigate**: 5000 (Web UI), 1935 (RTMP), 8554 (RTSP)
125- **Immich**: 2283 (Web UI/API), 3001 (Machine Learning)
126- **Forgejo**: 3000 (Web), 2222 (SSH)
127- **Stirling-PDF**: 8080 (App), 8081 (Caddy CORS Proxy)
128- **Tandoor**: 8010 (Web UI)
129- **Ghost**: 2368 (Web/API)
130
131### Data Paths
132- **Local Config**: `/docker/runner/` (service configurations)
133- **Local Data**: `/docker/runner-data/` (databases, caches)
134- **NFS Mounts**: `/mnt/docker/` (bulk data storage)
135
136## Management Commands
137
138Generated scripts for service management:
139- `runner-status.sh` - Check all service status
140- `runner-logs.sh` - View service logs
141- `runner-restart.sh` - Restart all services
142- `runner-update.sh` - Update container images
143
144## Monitoring
145
146### Logging
147- Centralized logging via Docker
148- Log rotation and retention
149- Service-specific log levels
150
151## API Integration
152
153Services designed for integration with website containers:
154- **Ghost CMS**: Content API for blogs/websites
155- **Stirling-PDF**: Document processing API
156- **Immich**: Photo gallery API
157- **Forgejo**: Git webhook integration
158
159## Backup Strategy
160
161### Data Protection
162- Configuration files â managed via Infrastructure as Code
163- Database persistence â local storage with regular snapshots
164- NFS data â handled by NAS backup systems
165
166## Usage Examples
167
168```bash
169# Deploy all services
170ansible-playbook runner.yml -i inventory/hosts
171
172# Deploy specific service
173ansible-playbook runner.yml -i inventory/hosts --tags frigate
174
175# Update service configuration
176ansible-playbook runner.yml -i inventory/hosts --tags config
177
178```