add-new-template

name: add-new-template description: Guide for adding new templates to this project. Covers the Project Generator pattern, the difference between dynamic templates (.tera, automatically discovered) and static templates (must be explicitly registered in copy_static_templates()), and the two-level indirection design (embedded binary → external extraction → build directory rendering). Use when adding infrastructure templates, Ansible playbooks, OpenTofu files, or configuration templates. Triggers on "add template", "new template", "static template", "register template", "copy_static_templates", "project generator", or "template system". metadata: author: torrust version: "1.0"

Adding New Templates

Two-Level Template Indirection

Embedded in binary  →  data/templates/  →  build/{env}/
  (compile time)       (extracted once)    (rendered per-run)

Templates live in templates/ in the repo. They are compiled into the binary, extracted to data/templates/ at first use, then rendered into build/ with variables.

Template Types

Adding a Dynamic Template (.tera)

1. Create the file in templates/ with a .tera extension
2. Use {{ variable_name }} syntax for runtime values
3. No additional registration needed — automatically discovered

templates/ansible/new-config.yml.tera

Adding a Static Template

Static templates (Ansible playbooks, fixed YAML, etc.) require explicit registration.

Step 1: Create the file

templates/ansible/my-new-playbook.yml

Step 2: Register in copy_static_templates()

Find the appropriate ProjectGenerator for your template type:

src/infrastructure/external_tools/ansible/template/renderer/project_generator.rs

Add your file to the copy_static_templates() function:

fn copy_static_templates(&self, ...) -> Result<(), Error> {
    // existing registrations...
    self.copy_template("ansible/my-new-playbook.yml", ...)?;
    Ok(())
}

Without this step, the file will never appear in the build directory and won't be available at runtime.

Ansible-Specific: Variables Pattern

For Ansible playbooks, add runtime variables to variables.yml.tera, not the playbook. The playbook loads them via vars_files: [variables.yml].

Checklist

• File placed in templates/ directory
• If .tera: uses correct {{ variable }} syntax
• If static: registered in copy_static_templates() in the project generator
• New variables added to variables.yml.tera (for Ansible) or equivalent context

Reference

Architecture: docs/contributing/templates/template-system-architecture.md Tera syntax: docs/contributing/templates/tera.md Ansible guide: docs/contributing/templates/ansible.md