The homelab management repository serves as the central control system for the entire homelab infrastructure. This repository contains Ansible automation, maintenance scripts, and comprehensive tooling for managing multiple servers, services, and content systems across the distributed homelab environment.
As of June 2025, the homelab uses an advanced git-Ansible coordination system that enables:
- Primary Management: Matthews MacBook Air - infrastructure planning and coordination
- Development Testing: lucille5 - safe testing environment with secondary management
- Future Expansion: Work Mac Studio planned as additional management workstation
- Automated Tracking: Each server maintains a
next-steps.md file for local tasks
- Cross-Server Dependencies: Documented dependencies and coordination requests
- Environment Detection: Claude Code automatically detects context (server vs workstation)
- ADHD-Friendly: Simple, consistent commands across all environments
- 1Password Integration: SSH keys and Ansible vault managed through 1Password CLI
- Workstation Sync: Automated deployment of tools and configurations
- Fallback Networking: All hosts have Tailscale + local IP fallback
- Task Prioritization: Clear next-steps tracking with status updates
- One Command Simplicity: Always run from
/homelab/ directory
- Visual Feedback: Clear progress indicators and status updates
- Graceful Failures: Systems that bend don't break
- Lower Cognitive Load: Automation handles organization, humans handle decisions
- Local-First Operation: Core functions work without internet
- Explicit Over Magical: Show what automation is doing
- Progressive Enhancement: Start simple, add complexity only when stable
- No Fragile Dependencies: Prefer boring, proven technology
- No Training Required: Basic operations are intuitive
- Clear Error Messages: Not silent failures or cryptic logs
- Audit Everything: Know what changed and when
- Permission to Restart: Systems designed for easy recovery
- Ansible Playbooks: Automated server maintenance, updates, and configuration management
- Multi-server Orchestration: Coordinated operations across lucille3, lucille4, loose-seal, and nas02
- Tag-based Maintenance: Granular control over maintenance operations with targeted execution
- Vault Management: Encrypted credential storage for secure automation
- Pre-flight Validation: Server readiness checks before maintenance operations
- Critical Stack Protection: Special handling for mission-critical services
- Error Handling: Robust recovery and reporting for failures
- WikiJS Integration: Comprehensive scripts for content organization and migration
- BookStack Import: Automated migration tools for knowledge base transitions
- Media Migration: Advanced tools for migrating and organizing media content
- Content Reorganization: Automated page structuring and folder organization
- Docker Stack Management: Automated container updates and orchestration
- Service Monitoring: Health checks and verification after maintenance
- Critical Service Protection: Special handling for mission-critical applications
- Backup Coordination: Centralized backup management across all servers
The management hub coordinates operations across four distinct server environments:
-
Linux Servers Group (lucille3, lucille4, loose-seal)
-
NAS Servers Group (nas02)
-
Ubuntu/Linux-based hosts
-
Docker Compose stack management
-
System package updates and maintenance
-
QNAP NAS devices
-
Specialized media and storage management
-
Hardware-specific maintenance routines
- Tag-based Execution: Maintenance operations organized by functional tags
- Pre-flight Validation: System readiness checks before maintenance
- Service Verification: Post-maintenance health validation
- Rollback Capabilities: Safe maintenance with failure recovery
¶ Tag-based Maintenance Script
The server_maintenance.sh script provides flexible maintenance options:
| Option |
Description |
-a, --all |
Run all maintenance tasks (default) |
-p, --preflight |
Run only pre-flight checks |
-s, --system-update |
Run only system updates |
-g, --git |
Run only git repository updates |
-d, --docker |
Run only Docker stack updates |
-m, --monitor |
Display system monitoring info |
-c, --cleanup |
Run Docker cleanup tasks |
-l, --logs |
Run log maintenance tasks |
-b, --backup |
Configure backup tasks |
-v, --verify |
Run verification checks |
## Complete infrastructure maintenance
./server_maintenance.sh -a
## Targeted maintenance operations
./server_maintenance.sh -p -v # Pre-flight and verification
./server_maintenance.sh -d -c # Docker updates and cleanup
./server_maintenance.sh -s -v # System updates and verification
## Just Docker stack updates and cleanup
./server_maintenance.sh -d -c
## WikiJS content organization
uv run python wikijs-reorganize-pages.py
## BookStack to WikiJS migration
uv run python wikijs-import-bookstack.py --token "token" --source bookstack-export
## Media migration automation
uv run python wikijs-migrate-media-automated.py --dry-run
uv run python wikijs-migrate-media-automated.py
## Target specific servers
ansible-playbook -i inventory.yml server_maintenance.yml --limit lucille4
## Install tools across infrastructure
ansible-playbook -i inventory.yml install_tools.yml --ask-vault-pass
- Page Organization: Automated restructuring of content hierarchies
- Media Migration: Complete media asset migration with URL updates
- Content Search: Advanced content analysis and domain reference scanning
- API Integration: Full GraphQL API utilization for content management
- Scan Phase: Identify external media references
- Download Phase: Retrieve media files from external sources
- Upload Phase: Multiple API upload methods with fallback options
- Update Phase: Automatic page content updates with new URLs
- Service Health: Continuous monitoring of critical services
- Performance Metrics: System resource tracking across servers
- Log Aggregation: Centralized logging from all homelab components
- Alert Management: Automated notifications for infrastructure issues
- Synchronized Updates: Coordinated maintenance across all servers
- Dependency Management: Service update ordering based on dependencies
- Network-aware Operations: Understanding of service interconnections
- Data Consistency: Ensuring data integrity during distributed operations
- WikiJS: Primary documentation and knowledge management
- BookStack: Legacy system migration capabilities
- Media Assets: Comprehensive media management and migration
- Search Integration: Advanced search capabilities across content systems
- Ansible Vault: Secure credential management
- API Token Management: Secure handling of service authentication
- Multi-factor Security: Layered security approach across operations
- Configuration Backups: All server configurations backed up
- Content Backups: Documentation and media content protection
- Recovery Procedures: Tested recovery workflows for disaster scenarios
- Ansible 2.10+ installed on control machine (Linux/macOS)
- SSH connectivity to each host (public key authentication recommended)
- Vault configuration:
vault.yml file with encrypted credentials
- Tool installation: Separate playbook for installing required tools
The management system organizes infrastructure into logical groups:
- Ubuntu/Linux-based hosts
- Docker Compose stack management
- System package updates and maintenance
- QNAP NAS devices
- Specialized media and storage management
- Hardware-specific maintenance routines
- Critical Services: paperless, ollama, ghost (require special validation)
- Infrastructure Services: caddy, authentik, monitoring tools
- Media Services: radarr, sonarr, jellyseerr
¶ Maintenance Safety Features
- Pre-flight Checks: Server connectivity, disk space, service availability
- Critical Stack Validation:
.env file checks for mission-critical services
- Service Verification: Post-maintenance health validation
- Error Recovery: Robust failure handling and reporting
- Ansible Vault: Secure credential management with encrypted
vault.yml
- SSH Key Authentication: Recommended over password authentication
- API Token Management: Secure handling of service authentication
- Least Privilege: Minimal sudo access configuration
- Configuration Backups: All server configurations backed up
- Content Backups: Documentation and media content protection
- Weekly Automation: Scheduled backups via resticprofile
- Recovery Procedures: Tested recovery workflows for disaster scenarios
The repository uses UV for Python package management:
## Install dependencies
uv add package_name
## Run scripts with dependency management
uv run python script.py
The management hub provides a framework for extending automation:
- Custom Ansible Modules: Server-specific operations
- Content Processing Scripts: Specialized content manipulation
- Integration APIs: Custom integrations with homelab services
This management hub represents the nerve center of the homelab, providing comprehensive automation, content management, and infrastructure coordination capabilities across the entire distributed system.