A comprehensive Ansible-based homelab setup with automated role generation, verification, and deployment capabilities.
- Infrastructure Roles: Network, security, and core services
- Monitoring Stack: Prometheus, Grafana, Loki for comprehensive monitoring
- Storage Solutions: Syncthing, Restic for data management
- Security Layer: Fail2ban, UFW, custom iptables configuration
- Development Tools: Rustdesk, Rustpad, Coolify
- AI Services: Librechat, Ollama, Mistral.rs (High-resource nodes only)
- Hardware: 55GB RAM, Multiple TB Storage
- Services:
- AI Services (Ollama, Librechat)
- Primary Monitoring Stack
- Video Conferencing (Jitsi)
- Primary DNS Controller
- Hardware per Node: 1GB RAM, 16-64GB Storage
- Distributed Services:
- DNS Servers (5 nodes)
- Monitoring Collectors (5 nodes)
- Storage Nodes (4 nodes)
- Edge Nodes (3 nodes)
- General Purpose/Failover (13 nodes)
The homelab integrates with AWS Route53 for domain management using existing AWS profiles:
- Uses existing AWS profiles and credentials
- Supports multiple AWS accounts via profile switching
- Environment variables for credentials:
AWS_PROFILE
: AWS profile name (defaults to 'default')AWS_ACCESS_KEY_ID
: AWS access keyAWS_SECRET_ACCESS_KEY
: AWS secret keyAWS_SESSION_TOKEN
: Optional session token
- Primary zone controller on main server
- Secondary DNS servers on edge nodes
- Support for multiple Route53 zones across accounts
- Automated DNS updates via AWS API
# Example: Running playbook with Route53 zone ID
ansible-playbook site.yml -e "route53_zone_id=Z0123456789ABCDEF"
# Multiple zones example
ansible-playbook site.yml -e '{
"route53_zones": {
"homelab.internal": "Z0123456789ABCDEF",
"prod.example.com": "Z9876543210FEDCBA"
}
}'
Coolify serves as the primary deployment and management platform:
- Environment variables required:
COOLIFY_API_KEY
: API key for Coolify accessCOOLIFY_DOMAIN
: Domain where Coolify is hosted
- Features:
- Centralized dashboard for all services
- Automated deployments
- Resource monitoring
- SSL certificate management
-
Clone the repository:
git clone https://github.com/yourusername/devenv.git cd devenv
-
Install dependencies:
ansible-galaxy install -r requirements.yml
-
Configure your inventory in
inventory/
:all: children: high_resource: hosts: alef: ansible_host: 192.168.1.10 medium_resource: hosts: bet: ansible_host: 192.168.1.11 low_resource: hosts: gimel: ansible_host: 192.168.1.12
-
Run the playbook:
ansible-playbook site.yml
roles/
├── service-template/ # Base template for all roles
│ ├── defaults/
│ │ └── main.yml # Default variables
│ ├── handlers/
│ │ └── main.yml # Service handlers
│ ├── tasks/
│ │ └── main.yml # Tasks with integrated verification
│ └── templates/
│ └── config.yml.j2 # Service configuration template
└── [service_name]/ # Generated service roles
-
Add role definition to
scripts/generate_roles.sh
:["new_service"]="service description;resource_tier;category"
-
Run the role generator:
./scripts/generate_roles.sh
-
Customize the generated role:
- Update
defaults/main.yml
with service-specific variables - Modify
tasks/main.yml
for service installation - Configure
templates/config.yml.j2
for service configuration
- Update
Each role includes automated verification:
- System requirements validation
- Package installation checks
- Service status verification
- Configuration validation
- Port and health endpoint monitoring
- Backup configuration verification
Located in group_vars/
:
all.yml
: Global variableshigh_resource.yml
: High-resource node settingsmedium_resource.yml
: Medium-resource node settingslow_resource.yml
: Low-resource node settings
Located in host_vars/
:
- Individual host configurations
- Node-specific overrides
-
Role Development:
- Always use the role generator for consistency
- Include comprehensive verification steps
- Document all variables in defaults/main.yml
- Test on appropriate resource tier
-
Security:
- Use vault for sensitive data
- Implement least privilege access
- Regular security role updates
- Maintain firewall configurations
-
Monitoring:
- Enable health checks where possible
- Configure appropriate resource limits
- Set up alerting thresholds
- Regular backup verification
-
Maintenance:
- Regular role updates
- Backup verification
- Security patches
- Performance monitoring
- Fork the repository
- Create a feature branch
- Add/modify roles using the generator
- Submit a pull request
MIT
Created for Homelab deployment