storage
Ansible role that provisions my storage server.
7.4 KB•MD
README.md
7.4 KB • 262 lines • markdown
1# Storage Services Role
2
3Comprehensive media automation and backup services role for homelab environments.
4
5## Overview
6
7This role deploys a complete media automation and backup stack including:
8
9- **Jellyfin**: Media server for streaming movies, TV shows, music
10- **Arr Stack**: Automated media acquisition (Sonarr, Radarr, Prowlarr, LazyLibrarian)
11- **Gluetun VPN**: Secure VPN container for Arr stack traffic
12- **Calibre Stack**: Ebook management (Calibre + Calibre-Web)
13- **Restic Server**: Self-hosted backup solution
14
15## Services Included
16
17### Media Server
18- **Jellyfin** (Port 8096): Media streaming server with transcoding support
19
20### Media Automation (Arr Stack)
21- **Sonarr** (Port 8989): TV show automation
22- **Radarr** (Port 7878): Movie automation
23- **Prowlarr** (Port 9696): Indexer management
24- **LazyLibrarian** (Port 5299): Ebook/audiobook automation
25- **Flaresolverr** (Port 8191): Cloudflare bypass for protected indexers
26- **Gluetun**: VPN container for secure traffic routing
27
28### Ebook Management
29- **Calibre Server** (Port 8083): Full-featured ebook management
30- **Calibre-Web** (Port 8084): Web interface for library access
31
32### Backup Solution
33- **Restic Server** (Port 8000): REST-based backup repository server
34
35## Requirements
36
37- Docker and Docker Compose installed
38- Sufficient storage space mounted at `/mnt/rstorage` (default)
39- Network access for media downloads (if using Arr stack)
40- VPN credentials if using Gluetun for secure downloads
41
42## Usage
43
44### Basic Deployment
45
46```yaml
47# In your host variables
48storage_enabled: true
49jellyfin_enabled: true
50arr_stack_enabled: true
51calibre_enabled: true
52restic_backup_server_enabled: true
53```
54
55### Deploy to Storage Servers
56
57```bash
58# Deploy all storage services
59ansible-playbook -i inventory/hosts site.yml --limit storage_servers --tags "core,storage"
60
61# Deploy only specific services
62ansible-playbook -i inventory/hosts site.yml --limit storage_servers --tags "jellyfin"
63ansible-playbook -i inventory/hosts site.yml --limit storage_servers --tags "arr-stack"
64```
65
66## Configuration
67
68### Required Vault Variables
69
70For secure operation, configure these encrypted variables:
71
72```yaml
73# VPN Configuration (for Gluetun)
74vpn_service_provider: "nordvpn" # or "surfshark", "expressvpn", etc.
75wireguard_private_key: "your_wireguard_private_key"
76wireguard_addresses: "10.x.x.x/32"
77
78# Alternative OpenVPN credentials
79openvpn_user: "your_vpn_username"
80openvpn_password: "your_vpn_password"
81
82# Backup Authentication
83restic_backup_username: "backup_user"
84restic_backup_password: "secure_backup_password"
85
86# Optional: Service admin credentials
87jellyfin_admin_username: "admin"
88jellyfin_admin_password: "secure_password"
89calibre_web_admin_username: "admin"
90calibre_web_admin_password: "secure_password"
91```
92
93### Storage Configuration
94
95```yaml
96# Storage paths (customize as needed)
97storage_base_path: "/mnt/rstorage"
98storage_docker_dir: "/docker"
99
100# Media directories will be created automatically:
101# - /mnt/rstorage/media/movies
102# - /mnt/rstorage/media/shows
103# - /mnt/rstorage/media/books
104# - /mnt/rstorage/downloads
105# - /mnt/rstorage/backups
106```
107
108### Service Customization
109
110```yaml
111# Port configuration
112jellyfin_host_port: 8096
113sonarr_host_port: 8989
114radarr_host_port: 7878
115prowlarr_host_port: 9696
116lazylibrarian_host_port: 5299
117calibre_web_host_port: 8084
118restic_backup_host_port: 8000
119
120# Resource limits
121jellyfin_memory_limit: "4g"
122jellyfin_cpu_limit: "4"
123arr_memory_limit: "1g"
124arr_cpu_limit: "1"
125
126# VPN settings
127arr_vpn_enabled: true
128vpn_server_countries: "Netherlands,Switzerland"
129```
130
131## Access URLs
132
133After deployment, services are accessible at:
134
135- Jellyfin: `http://your-server:8096`
136- Sonarr: `http://your-server:8989`
137- Radarr: `http://your-server:7878`
138- Prowlarr: `http://your-server:9696`
139- LazyLibrarian: `http://your-server:5299`
140- Flaresolverr: `http://your-server:8191`
141- Calibre-Web: `http://your-server:8084`
142- Restic Server: `http://your-server:8000`
143
144## Post-Deployment Setup
145
146### 1. Arr Stack Configuration
147
1481. **Prowlarr First**: Configure indexers and connect to other Arr apps
1492. **Quality Profiles**: Set up quality preferences in each Arr app
1503. **Root Folders**: Add media directories (already mounted)
1514. **Download Client**: Configure your preferred download client
152
153### 2. Jellyfin Setup
154
1551. Complete the initial setup wizard
1562. Add media libraries pointing to `/media/movies`, `/media/shows`, etc.
1573. Configure transcoding settings based on your hardware
1584. Set up user accounts and permissions
159
160### 3. Calibre Configuration
161
1621. Access Calibre-Web and complete initial setup
1632. Point to the Calibre library at `/books`
1643. Import existing ebook collection if available
1654. Configure metadata sources and preferences
166
167### 4. Backup Setup
168
1691. Install restic on client machines
1702. Use the generated client script: `/docker/restic-server/client-setup-example.sh`
1713. Initialize repositories and set up automated backups
172
173## Directory Structure
174
175```
176/docker/ # Docker configurations
177âââ jellyfin/
178â âââ config/ # Jellyfin configuration
179â âââ cache/ # Transcoding cache
180â âââ docker-compose.yml
181âââ arr-stack/
182â âââ sonarr/config/ # Sonarr configuration
183â âââ radarr/config/ # Radarr configuration
184â âââ prowlarr/config/ # Prowlarr configuration
185â âââ lazylibrarian/config/ # LazyLibrarian configuration
186â âââ docker-compose.yml
187âââ calibre/
188â âââ server/config/ # Calibre server config
189â âââ web/config/ # Calibre-Web config
190â âââ docker-compose.yml
191âââ restic-server/
192 âââ config/ # Restic configuration
193 âââ docker-compose.yml
194
195/mnt/rstorage/ # Media and data storage
196âââ media/
197â âââ movies/ # Movie files
198â âââ tv/ # TV show files
199â âââ books/ # Ebook library
200â âââ music/ # Music files
201âââ downloads/
202â âââ complete/ # Completed downloads
203â âââ incomplete/ # In-progress downloads
204âââ backups/ # Restic backup data
205```
206
207## Security Considerations
208
209- All sensitive credentials are stored in encrypted vault variables
210- VPN routing protects download traffic when enabled
211- Backup server requires authentication
212- Services run with non-root user permissions
213- Docker network isolation between services
214
215## Troubleshooting
216
217### Health Monitoring
218Health monitoring will be provided by netdata (to be deployed separately)
219
220### Common Issues
221
222**VPN Not Working**: Check Gluetun logs and VPN credentials
223```bash
224docker logs gluetun
225```
226
227**Services Not Accessible**: Verify Docker network and port mappings
228```bash
229docker network ls
230docker compose ps
231```
232
233**Permission Issues**: Check directory ownership
234```bash
235ls -la /docker/
236ls -la /mnt/rstorage/
237```
238
239**Storage Full**: Monitor disk usage
240```bash
241df -h /mnt/rstorage/
242```
243
244## Tags
245
246Use these tags for targeted deployment:
247
248- `storage` - All storage services
249- `jellyfin` - Jellyfin media server only
250- `arr-stack` - All Arr services + VPN
251- `calibre` - Calibre ebook services
252- `restic` - Backup server only
253- `validation` - Health checks and validation
254
255## Dependencies
256
257- `geerlingguy.docker` - Docker installation
258- `community.docker` - Docker Ansible modules
259
260## License
261
262MIT License - See project root for details.