feat: complete variable management implementation and update documentation

- Update remaining Docker Compose templates with centralized variables
- Fix service tag isolation to deploy individual services only
- Update all README files with variable management architecture
- Document variable hierarchy in DEPLOYMENT_LEARNINGS.md
- Add comprehensive variable usage patterns to CLAUDE.md
- Standardize domain references using {{ subdomains.* }} pattern
- Replace hardcoded network names with {{ docker.network_name }}
- Update hairpinning configuration to use variables

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2025-06-06 15:45:52 -06:00
parent 12582b352c
commit 2e4c096bbe
14 changed files with 110 additions and 87 deletions

View File

@ -6,7 +6,7 @@ Deploys and manages a comprehensive self-hosted infrastructure with 22+ containe
## Architecture Overview
### Network Configuration
- **External Network**: All services connect to shared `lava` network (172.20.0.0/24)
- **External Network**: All services connect to shared Docker network (configurable)
- **Reverse Proxy**: Caddy handles all ingress traffic with automatic HTTPS
- **Service Discovery**: Container-to-container communication using service names
- **Firewall Integration**: UFW-Docker script properly configures firewall rules
@ -16,6 +16,7 @@ Deploys and manages a comprehensive self-hosted infrastructure with 22+ containe
- **Network Isolation**: Services restricted to appropriate network segments
- **Container Hardening**: Non-root users, capability dropping, security options
- **Secret Management**: Ansible vault for sensitive configuration
- **Variable Management**: Centralized variable hierarchy using group_vars structure
## Services Deployed (Organized by Category)
@ -68,7 +69,9 @@ Each service follows a consistent pattern:
### Template System
- **Compose Templates**: `.j2` files in `templates/` for dynamic configuration
- **Environment Templates**: Separate `.env.j2` files for services requiring environment variables
- **Variable Substitution**: Uses Ansible vault variables for secrets and configuration
- **Variable Substitution**: Uses centralized variable hierarchy from group_vars structure
- **Domain Management**: Centralized domain and subdomain configuration
- **Network Configuration**: Standardized Docker network and IP address management
## Shell Environment Setup
The role also configures the shell environment:
@ -161,11 +164,20 @@ ansible-playbook site.yml -i hosts.yml --tags mmdl
## Configuration
### Required Variables (in vault)
- Authentication credentials for various services
### Variable Structure
The role uses a centralized variable hierarchy in `group_vars/all/`:
- **domains.yml**: Domain and subdomain mappings for all services
- **infrastructure.yml**: Network configuration, Docker settings, and system parameters
- **vault.yml**: Encrypted secrets including API keys, passwords, and OAuth credentials
- **services.yml**: Service-specific configuration and feature flags
### Required Variables (in vault.yml)
- Authentication credentials for various services (vault_*)
- API keys for external integrations
- OAuth client secrets for SSO integration
- Database passwords and connection strings
- SMTP credentials for notifications
### Network Configuration
Services expect to be accessible via subdomains of configured domains: