|
| 1 | +# Template Documentation |
| 2 | + |
| 3 | +This directory contains documentation about the template system used in the Torrust Tracker Deployer project. |
| 4 | + |
| 5 | +## 📚 Documentation Overview |
| 6 | + |
| 7 | +The template system uses a **double indirection** approach with embedded templates that are extracted and then rendered to build directories. Understanding this system is essential when working with infrastructure configurations. |
| 8 | + |
| 9 | +### Core Documentation |
| 10 | + |
| 11 | +- **[Template System Architecture](template-system-architecture.md)** - **CRITICAL**: Technical architecture overview |
| 12 | + |
| 13 | + - Double indirection pattern (embedded → external → build) |
| 14 | + - Project Generator pattern (Orchestrator/Worker) |
| 15 | + - Two-phase processing (dynamic rendering + static copying) |
| 16 | + - Wrapper types, Renderer types, and Project Generators |
| 17 | + - Read this first to understand the overall system design |
| 18 | + |
| 19 | +- **[Tera Template Syntax](tera.md)** - **CRITICAL**: Working with Tera templates |
| 20 | + |
| 21 | + - Correct Tera variable syntax: `{{ variable }}` not `{ { variable } }` |
| 22 | + - Static vs dynamic playbooks |
| 23 | + - Adding new Ansible playbooks (registration required) |
| 24 | + - Using centralized variables pattern |
| 25 | + - Common mistakes and troubleshooting |
| 26 | + - Read this when creating or modifying `.tera` files |
| 27 | + |
| 28 | +- **[Ansible Templates](ansible.md)** - Ansible-specific documentation |
| 29 | + - Available playbooks and their purpose |
| 30 | + - Usage order for typical deployments |
| 31 | + - CI/Testing considerations (firewall, container limitations) |
| 32 | + - Variables pattern and template processing |
| 33 | + - Read this when working with Ansible infrastructure |
| 34 | + |
| 35 | +## 🎯 Quick Reference |
| 36 | + |
| 37 | +### When to Read What |
| 38 | + |
| 39 | +| Task | Read This | |
| 40 | +| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- | |
| 41 | +| Understanding template architecture | [Template System Architecture](template-system-architecture.md) | |
| 42 | +| Creating/modifying `.tera` files | [Tera Template Syntax](tera.md) | |
| 43 | +| Adding new Ansible playbooks | [Tera Template Syntax](tera.md#-adding-new-ansible-playbooks) | |
| 44 | +| Working with Ansible infrastructure | [Ansible Templates](ansible.md) | |
| 45 | +| Understanding Project Generator pattern | [Template System Architecture](template-system-architecture.md#-project-generator-pattern-orchestratorworker) | |
| 46 | + |
| 47 | +## ⚠️ Critical Rules |
| 48 | + |
| 49 | +### 1. Tera Variable Syntax |
| 50 | + |
| 51 | +Always use correct Tera syntax: |
| 52 | + |
| 53 | +```yaml |
| 54 | +# ✅ CORRECT |
| 55 | +{{ variable_name }} |
| 56 | + |
| 57 | +# ❌ WRONG - Spaces inside braces |
| 58 | +{ { variable_name } } |
| 59 | +``` |
| 60 | + |
| 61 | +### 2. Static Template Registration |
| 62 | + |
| 63 | +Static templates (without `.tera` extension) **MUST be registered** in the Project Generator: |
| 64 | + |
| 65 | +```rust |
| 66 | +// In copy_static_templates() method |
| 67 | +for playbook in &[ |
| 68 | + "install-docker.yml", |
| 69 | + "your-new-playbook.yml", // ← ADD HERE |
| 70 | +] { |
| 71 | + // ... |
| 72 | +} |
| 73 | +``` |
| 74 | + |
| 75 | +**Without registration**: Ansible will fail with "playbook not found" error. |
| 76 | + |
| 77 | +### 3. Centralized Variables Pattern |
| 78 | + |
| 79 | +For Ansible playbooks, prefer the centralized variables pattern: |
| 80 | + |
| 81 | +- Add variables to `templates/ansible/variables.yml.tera` |
| 82 | +- Reference via `vars_files: [variables.yml]` in static playbooks |
| 83 | +- Do NOT create new `.tera` templates unless necessary |
| 84 | + |
| 85 | +## 🏗️ Template Structure |
| 86 | + |
| 87 | +```text |
| 88 | +templates/ |
| 89 | +├── ansible/ Ansible playbooks and configuration |
| 90 | +├── docker-compose/ Docker Compose configurations |
| 91 | +├── grafana/ Grafana monitoring dashboards |
| 92 | +├── prometheus/ Prometheus monitoring configuration |
| 93 | +├── tofu/ OpenTofu (Terraform) infrastructure |
| 94 | +└── tracker/ Torrust Tracker configuration |
| 95 | +``` |
| 96 | + |
| 97 | +## 📦 Template Types |
| 98 | + |
| 99 | +### Dynamic Templates (.tera) |
| 100 | + |
| 101 | +- **Extension**: `.tera` |
| 102 | +- **Processing**: Variable substitution using Tera engine |
| 103 | +- **Examples**: `inventory.yml.tera`, `variables.yml.tera`, `env.tera` |
| 104 | +- **Registration**: Automatic (discovered by extension) |
| 105 | + |
| 106 | +### Static Templates |
| 107 | + |
| 108 | +- **Extension**: `.yml`, `.cfg`, etc. (no `.tera`) |
| 109 | +- **Processing**: Direct file copy |
| 110 | +- **Examples**: `install-docker.yml`, `ansible.cfg`, `docker-compose.yml` |
| 111 | +- **Registration**: **Required** - must be added to Project Generator's copy list |
| 112 | + |
| 113 | +## 🔄 Template Flow |
| 114 | + |
| 115 | +```text |
| 116 | +┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ |
| 117 | +│ Embedded │ │ External │ │ Build │ |
| 118 | +│ Templates │───▶│ Templates │───▶│ Directory │ |
| 119 | +│ (in binary) │ │ (data/templates) │ │ (build/) │ |
| 120 | +└─────────────────┘ └──────────────────┘ └─────────────────┘ |
| 121 | + │ │ │ |
| 122 | + Compile Time Runtime Extraction Runtime Rendering |
| 123 | +``` |
| 124 | + |
| 125 | +## 📝 Related Documentation |
| 126 | + |
| 127 | +- **[DDD Layer Placement](../ddd-layer-placement.md)** - Where template-related code belongs |
| 128 | +- **[Module Organization](../module-organization.md)** - How to organize template code |
| 129 | +- **[E2E Testing](../../e2e-testing/README.md)** - Testing template generation |
| 130 | +- **[AGENTS.md](../../../AGENTS.md)** - AI assistant instructions for templates |
| 131 | + |
| 132 | +## 🎓 Learning Path |
| 133 | + |
| 134 | +For new contributors working with templates: |
| 135 | + |
| 136 | +1. **Start**: Read [Template System Architecture](template-system-architecture.md) for the big picture |
| 137 | +2. **Practice**: Read [Tera Template Syntax](tera.md) and try modifying existing templates |
| 138 | +3. **Apply**: Read [Ansible Templates](ansible.md) when working with infrastructure |
| 139 | +4. **Extend**: Follow the guides to add new templates and playbooks |
| 140 | + |
| 141 | +## 🐛 Common Issues |
| 142 | + |
| 143 | +### Problem: Prettier adds spaces in Tera variables |
| 144 | + |
| 145 | +**Solution**: Add `*.tera` to `.prettierignore` or disable formatting for `.tera` files. |
| 146 | + |
| 147 | +### Problem: Ansible playbook not found error |
| 148 | + |
| 149 | +**Solution**: Static playbooks must be registered in `copy_static_templates()` method. |
| 150 | + |
| 151 | +### Problem: Variables not resolved in output |
| 152 | + |
| 153 | +**Solution**: Use `.tera` extension for files needing variable substitution. |
| 154 | + |
| 155 | +## 📄 Beta Status Notice |
| 156 | + |
| 157 | +The template system is currently in beta. Implementation details, APIs, and internal structure may change. These docs focus on core concepts and best practices rather than specific implementation details that may evolve. |
0 commit comments