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:
69
CLAUDE.md
69
CLAUDE.md
@ -27,18 +27,19 @@ ansible-playbook dns.yml -i hosts.yml
|
||||
|
||||
### Service Management
|
||||
```bash
|
||||
# Deploy specific services using tags
|
||||
ansible-playbook site.yml -i hosts.yml --tags caddy --vault-password-file vault_pass
|
||||
ansible-playbook site.yml -i hosts.yml --tags authentik,gitea --vault-password-file vault_pass
|
||||
ansible-playbook site.yml -i hosts.yml --tags docker --vault-password-file vault_pass # all docker services
|
||||
# Deploy specific services using tags (now properly isolated)
|
||||
ansible-playbook site.yml -i hosts.yml --tags caddy --vault-password-file vault_pass --extra-vars "@secrets.enc"
|
||||
ansible-playbook site.yml -i hosts.yml --tags authentik --vault-password-file vault_pass --extra-vars "@secrets.enc"
|
||||
ansible-playbook site.yml -i hosts.yml --tags mmdl --vault-password-file vault_pass --extra-vars "@secrets.enc"
|
||||
ansible-playbook site.yml -i hosts.yml --tags docker --vault-password-file vault_pass --extra-vars "@secrets.enc" # all docker services
|
||||
|
||||
# Deploy services by category (new organized structure)
|
||||
ansible-playbook site.yml -i hosts.yml --tags infrastructure --vault-password-file vault_pass
|
||||
ansible-playbook site.yml -i hosts.yml --tags media,productivity --vault-password-file vault_pass
|
||||
ansible-playbook site.yml -i hosts.yml --tags development,monitoring --vault-password-file vault_pass
|
||||
ansible-playbook site.yml -i hosts.yml --tags infrastructure --vault-password-file vault_pass --extra-vars "@secrets.enc"
|
||||
ansible-playbook site.yml -i hosts.yml --tags media,productivity --vault-password-file vault_pass --extra-vars "@secrets.enc"
|
||||
ansible-playbook site.yml -i hosts.yml --tags development,monitoring --vault-password-file vault_pass --extra-vars "@secrets.enc"
|
||||
|
||||
# Deploy only infrastructure components
|
||||
ansible-playbook site.yml -i hosts.yml --tags common,cron --vault-password-file vault_pass
|
||||
ansible-playbook site.yml -i hosts.yml --tags common,cron --vault-password-file vault_pass --extra-vars "@secrets.enc"
|
||||
```
|
||||
|
||||
## Architecture
|
||||
@ -69,10 +70,21 @@ The docker role is now organized into logical service groups under `roles/docker
|
||||
- **monitoring/**: System monitoring and alerts
|
||||
- Changedetection, Glance dashboard, AppriseAPI
|
||||
|
||||
### Variable Management
|
||||
**Critical**: This infrastructure uses a centralized variable hierarchy in `group_vars/all/`:
|
||||
|
||||
- **domains.yml**: Domain and subdomain mappings (use `{{ subdomains.service }}`)
|
||||
- **infrastructure.yml**: Network configuration, Docker settings (`{{ docker.network_name }}`, `{{ docker.hairpin_ip }}`)
|
||||
- **vault.yml**: Encrypted secrets with `vault_` prefix
|
||||
- **services.yml**: Service-specific configuration and feature flags
|
||||
|
||||
**Important**: All templates use variables instead of hardcoded values. Never hardcode domains, IPs, or secrets.
|
||||
|
||||
### Data Structure
|
||||
- All service data stored in `/opt/stacks/[service-name]/` on docker host
|
||||
- Docker Compose files generated from Jinja2 templates in `roles/docker/templates/`
|
||||
- Environment files templated for services requiring configuration
|
||||
- All configurations use centralized variables for consistency
|
||||
|
||||
## Key Implementation Details
|
||||
|
||||
@ -104,14 +116,45 @@ Services inside Docker containers cannot reach external domains that resolve to
|
||||
|
||||
```yaml
|
||||
extra_hosts:
|
||||
- "auth.thesatelliteoflove.com:172.20.0.5"
|
||||
- "cal.thesatelliteoflove.com:172.20.0.5"
|
||||
- "{{ subdomains.auth }}:{{ docker.hairpin_ip }}"
|
||||
- "{{ subdomains.cal }}:{{ docker.hairpin_ip }}"
|
||||
```
|
||||
|
||||
Common domains requiring hairpinning fixes:
|
||||
- `auth.thesatelliteoflove.com` (Authentik SSO)
|
||||
- `cal.thesatelliteoflove.com` (Baikal CalDAV)
|
||||
- `{{ subdomains.auth }}` (Authentik SSO)
|
||||
- `{{ subdomains.cal }}` (Baikal CalDAV)
|
||||
- Any service domain the container needs to communicate with
|
||||
|
||||
**Note**: Use variables instead of hardcoded values for maintainability.
|
||||
|
||||
### Service-Specific Reference Configurations
|
||||
- **Dawarich**: Based on production compose file at https://github.com/Freika/dawarich/blob/master/docker/docker-compose.production.yml
|
||||
- **Dawarich**: Based on production compose file at https://github.com/Freika/dawarich/blob/master/docker/docker-compose.production.yml
|
||||
|
||||
## Service Memories
|
||||
- pingvin is the service that responds on files.thesatelliteoflove.com
|
||||
|
||||
## Variable Management Implementation Notes
|
||||
**Major Infrastructure Update**: Variable management system was implemented to replace all hardcoded values with centralized variables.
|
||||
|
||||
### Key Changes Made:
|
||||
- Created comprehensive `group_vars/all/` structure
|
||||
- Updated all Docker Compose templates to use variables
|
||||
- Fixed service tag isolation (individual service tags now deploy only that service)
|
||||
- Standardized domain and network configuration
|
||||
- Organized secrets by service with consistent `vault_` prefix
|
||||
|
||||
### Service Tag Fix:
|
||||
**Critical**: Service tags are now properly isolated. `--tags mmdl` deploys only MMDL (5 tasks), not the entire productivity category.
|
||||
|
||||
### Template Pattern:
|
||||
All templates now follow this pattern:
|
||||
```yaml
|
||||
# Use variables, not hardcoded values
|
||||
glance.url: "https://{{ subdomains.service }}/"
|
||||
networks:
|
||||
default:
|
||||
external: true
|
||||
name: "{{ docker.network_name }}"
|
||||
extra_hosts:
|
||||
- "{{ subdomains.auth }}:{{ docker.hairpin_ip }}"
|
||||
```
|
Reference in New Issue
Block a user