docs: [#106] update documentation for centralized variables pattern

Co-authored-by: josecelano <[email protected]>

Author: Copilot

docs/contributing/templates.md

@@ -274,6 +274,72 @@ When adding a static Ansible playbook:
 - [ ] Create application step to execute the playbook
 - [ ] Verify playbook appears in `build/` directory during execution
 
+## 🎯 Using Centralized Variables in Ansible Playbooks
+
+When creating new Ansible playbooks that need dynamic variables (ports, paths, etc.), use the **centralized variables pattern** instead of creating new Tera templates.
+
+### DO ✅
+
+**Add variables to `templates/ansible/variables.yml.tera`:**
+
+```yaml
+# System Configuration
+ssh_port: {{ ssh_port }}
+my_service_port: {{ my_service_port }}  # ← Add your new variable
+```
+
+**Reference variables in static playbook using `vars_files`:**
+
+```yaml
+# templates/ansible/my-new-service.yml (static playbook, no .tera extension)
+---
+- name: Configure My Service
+  hosts: all
+  vars_files:
+    - variables.yml  # Load centralized variables
+  
+  tasks:
+    - name: Configure service port
+      ansible.builtin.lineinfile:
+        path: /etc/myservice/config
+        line: "port={{ my_service_port }}"
+```
+
+**Register playbook in `copy_static_templates()` method:**
+
+```rust
+for playbook in &[
+    "update-apt-cache.yml",
+    "install-docker.yml",
+    "my-new-service.yml",  // ← Add here
+] {
+    // ...
+}
+```
+
+### DON'T ❌
+
+- ❌ Create a new `.tera` template for the playbook
+- ❌ Create a new renderer/wrapper/context for each playbook
+- ❌ Add variables directly in `inventory.yml.tera` (unless inventory-specific)
+
+### Benefits
+
+1. **Minimal Code**: No Rust boilerplate (renderer, wrapper, context) needed
+2. **Centralized Management**: All variables in one place
+3. **Runtime Resolution**: Variables resolved by Ansible, not at template rendering
+4. **Easy Maintenance**: Adding new variables requires minimal changes
+
+### When to Create a New Tera Template
+
+Only create a new `.tera` template if:
+
+1. The file **cannot** use Ansible's `vars_files` directive (e.g., inventory files)
+2. The file requires **complex logic** that Tera provides but Ansible doesn't
+3. The file needs **different variable scopes** than what centralized variables provide
+
+Otherwise, use the centralized variables pattern for simplicity.
+
 ### Related Documentation
 
 - **Architecture**: [`docs/technical/template-system-architecture.md`](../technical/template-system-architecture.md) - Understanding the two-phase template system

docs/technical/template-system-architecture.md

@@ -52,6 +52,50 @@ The system operates through two levels of indirection to balance portability wit
 - **Use Case**: Configuration files requiring runtime parameters (IPs, usernames, paths)
 - **Registration**: Automatically discovered by `.tera` extension
 
+## 🎨 Ansible Variables Pattern
+
+For Ansible templates, the system uses a **hybrid approach** combining static playbooks with centralized variables:
+
+### Tera Templates (2 templates)
+
+1. `inventory.yml.tera` - Inventory requires direct variable substitution (Ansible inventories don't support vars_files)
+2. `variables.yml.tera` - Centralized variables for all playbooks
+
+### Static Playbooks
+
+- All playbooks are static YAML files (no `.tera` extension)
+- Playbooks reference variables via `vars_files: [variables.yml]`
+- Variables are resolved at Ansible runtime, not at template rendering time
+
+### Benefits
+
+- **Reduced Rust Boilerplate**: No per-playbook renderer/wrapper/context needed
+- **Centralized Variable Management**: All playbook variables in one place
+- **Consistency**: Follows the same pattern as OpenTofu's `variables.tfvars.tera`
+- **Maintainability**: Adding new playbooks requires minimal code changes
+
+### Example
+
+```yaml
+# templates/ansible/configure-firewall.yml (static playbook)
+---
+- name: Configure UFW firewall
+  hosts: all
+  vars_files:
+    - variables.yml  # Load centralized variables
+  
+  tasks:
+    - name: Allow SSH access
+      community.general.ufw:
+        port: "{{ ssh_port }}"  # Variable from variables.yml
+```
+
+```yaml
+# templates/ansible/variables.yml.tera (rendered once)
+---
+ssh_port: {{ ssh_port }}
+```
+
 ## 🔧 Key Components
 
 ### Template Manager

templates/ansible/README.md

@@ -28,18 +28,22 @@ This directory contains Ansible playbook templates for the Torrust Tracker Deplo
 
   - Sets up unattended-upgrades for automatic security patches
 
-- **`configure-firewall.yml.tera`** - Configures UFW (Uncomplicated Firewall) with SSH lockout prevention
+- **`configure-firewall.yml`** - Configures UFW (Uncomplicated Firewall) with SSH lockout prevention
 
   - ⚠️ **Critical**: This playbook configures restrictive firewall rules
   - Automatically preserves SSH access on the configured port to prevent lockout
+  - Uses centralized variables from `variables.yml` (loaded via `vars_files`)
   - **Container Limitation**: Requires kernel capabilities (CAP_NET_ADMIN, CAP_NET_RAW) not available in unprivileged containers
   - **Automatic Skip**: Container-based E2E tests automatically skip this step via `TORRUST_TD_SKIP_FIREWALL_IN_CONTAINER` environment variable
     - Accepted values: `"true"` or `"false"` (case-sensitive, lowercase only)
     - Example: `TORRUST_TD_SKIP_FIREWALL_IN_CONTAINER=true`
-  - **VM-only**: This playbook is only executed in VM-based deployments and tests### Configuration Files
+  - **VM-only**: This playbook is only executed in VM-based deployments and tests
 
-- **`ansible.cfg`** - Ansible configuration
+### Configuration Files
+
+- **`ansible.cfg`** - Ansible configuration (static)
 - **`inventory.yml.tera`** - Inventory template file (processed by Tera templating engine)
+- **`variables.yml.tera`** - Centralized variables template (processed by Tera templating engine)
 
 ## Usage Order
 
@@ -50,7 +54,7 @@ For a typical deployment:
 3. **`install-docker.yml`** - Install Docker
 4. **`install-docker-compose.yml`** - Install Docker Compose (optional)
 5. **`configure-security-updates.yml`** - Configure automatic security updates
-6. **`configure-firewall.yml.tera`** - Configure UFW firewall (VM-only, skipped in containers)
+6. **`configure-firewall.yml`** - Configure UFW firewall (VM-only, skipped in containers)
 
 ## CI/Testing Considerations
 
@@ -63,6 +67,23 @@ For a typical deployment:
   - The deployer sets `TORRUST_TD_SKIP_FIREWALL_IN_CONTAINER=true` for container tests (accepts `"true"` or `"false"` only)
   - VM-based tests (LXD) have full kernel access and run the firewall playbook normally
 
+## Variables Pattern
+
+This directory uses a **centralized variables pattern**:
+
+- **`variables.yml.tera`** - Centralized variables (rendered at runtime with Tera)
+- **`inventory.yml.tera`** - Connection variables (rendered at runtime with Tera)
+- **`*.yml`** - Static playbooks that load `variables.yml` via `vars_files` directive
+
+### When Adding New Playbooks
+
+1. **Add variables** to `variables.yml.tera`
+2. **Create static** `.yml` playbook (not `.tera`)
+3. **Add `vars_files: [variables.yml]`** to playbook
+4. **Register** in `copy_static_templates()` if new static playbook
+
+This pattern reduces Rust boilerplate (no per-playbook renderer/wrapper/context needed) while providing centralized variable management.
+
 ## Template Processing
 
-These files are processed by the Tera templating engine and written to the `build/ansible/` directory during the build process.
+Files with `.tera` extension are processed by the Tera templating engine. All files are written to the `build/ansible/` directory during the build process.