feat: implement instance name parameterization and enhance template cleanup

- Update E2E tests to use 'torrust-tracker-vm' instead of 'torrust-vm'
- Fix template caching issue by adding templates directory cleanup
- Update OpenTofu template default instance name to 'torrust-tracker-vm'
- Add template system architecture documentation focusing on double indirection pattern
- Create user guide for template customization explaining current limitations
- Enhance preflight cleanup to ensure proper test isolation between runs

This change verifies that instance names are properly parameterized through the
template system and addresses template caching issues that prevented proper
E2E test isolation.

Author: josecelano

docs/technical/template-system-architecture.md

@@ -0,0 +1,106 @@
+# Template System Architecture
+
+Technical documentation for contributors working with the template rendering system.
+
+## 🏗️ System Overview
+
+The template system uses a **double indirection** approach to provide flexible infrastructure deployment while maintaining portability and customizability.
+
+## 📦 Double Indirection Pattern
+
+The system operates through two levels of indirection to balance portability with flexibility:
+
+### Level 1: Embedded → External Extraction
+
+1. **Source**: Templates are compiled into the binary as embedded resources
+2. **Extraction**: On first use, templates are extracted to an external directory (e.g., `data/templates`)
+3. **Benefit**: Enables single binary deployment while allowing runtime customization
+
+### Level 2: Template → Build Directory Rendering
+
+1. **Source**: Templates are read from the external directory
+2. **Processing**: Templates are processed (static copy or dynamic rendering with variables)
+3. **Output**: Final configuration files are written to the build directory
+4. **Benefit**: Separates template definitions from runtime-generated configurations
+
+## 🔄 Template Flow
+
+```text
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│ Embedded        │    │ External         │    │ Build           │
+│ Templates       │───▶│ Templates        │───▶│ Directory       │
+│ (in binary)     │    │ (data/templates) │    │ (build/)        │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+       │                        │                        │
+   Compile Time            Runtime Extraction       Runtime Rendering
+```
+
+## 🎯 Template Types
+
+### Static Templates
+
+- **Processing**: Direct file copy from templates to build directory
+- **Examples**: Infrastructure definitions, playbooks
+- **Use Case**: Configuration files that don't need variable substitution
+
+### Dynamic Templates (Tera)
+
+- **Processing**: Variable substitution using Tera templating engine
+- **File Suffix**: `.tera` extension (e.g., `variables.tfvars.tera`)
+- **Use Case**: Configuration files requiring runtime parameters
+
+## 🔧 Key Components
+
+### Template Manager
+
+- Handles the embedded → external extraction process
+- Manages template source selection (embedded vs external directory)
+- Coordinates template availability and caching
+
+### Template Renderers
+
+- **OpenTofu Renderer**: Processes infrastructure templates
+- **Ansible Renderer**: Processes configuration management templates
+- Handle the template → build directory rendering process
+
+### Template Engine
+
+- Tera-based templating for dynamic content
+- Variable context resolution
+- Template syntax validation and error handling
+
+## ⚠️ Important Behaviors
+
+### Template Persistence
+
+- Once extracted, external templates persist between runs
+- Templates are **not** automatically refreshed from embedded sources
+- This enables template customization but can cause confusion during development
+
+### E2E Test Isolation
+
+- E2E tests clean the templates directory before each run
+- This ensures fresh embedded template extraction for consistent test results
+- Production deployments may use persistent template directories
+
+## 🎯 Design Goals
+
+### Portability
+
+- Single binary contains all necessary templates
+- No external dependencies for basic deployment
+
+### Flexibility
+
+- External templates can be customized without recompilation
+- Support for both static and dynamic template processing
+- CLI option to specify custom template directories
+
+### Test Isolation
+
+- Template cleanup ensures consistent test environments
+- Separation of template sources from generated configurations
+
+## 📋 Beta Status Notice
+
+This system is currently in beta. The implementation details, APIs, and internal structure may change significantly. This document focuses on the core architectural concept rather than specific implementation details that are likely to evolve.

docs/user-guide/template-customization.md

@@ -0,0 +1,80 @@
+# Template System Overview
+
+This document explains how the template system works in the Torrust Tracker Deploy tool.
+
+## 📋 Overview
+
+The deployment tool uses templates to generate configuration files for infrastructure provisioning (OpenTofu) and software configuration (Ansible). Currently, templates are embedded in the binary for production use.
+
+## 🗂️ Template Structure
+
+Templates are organized in the following structure:
+
+```text
+templates/
+├── ansible/           # Ansible playbooks and inventory templates
+│   ├── inventory.yml.tera
+│   ├── install-docker.yml
+│   └── ...
+└── tofu/             # OpenTofu infrastructure templates
+    └── lxd/          # LXD provider templates
+        ├── main.tf
+        ├── variables.tfvars.tera
+        └── cloud-init.yml.tera
+```
+
+## 🚀 Current Template System
+
+### Embedded Templates (Production)
+
+- Templates are embedded in the binary during compilation
+- No external files required for deployment
+- Provides consistent, tested deployment configurations
+- Templates are automatically extracted to build directory during deployment
+
+## 🎛️ Template Types
+
+### Static Templates
+
+- Files copied as-is to the build directory
+- Examples: `main.tf`, `install-docker.yml`
+- No variable substitution
+
+### Dynamic Templates (`.tera` extension)
+
+- Use Tera templating engine for variable substitution
+- Examples: `variables.tfvars.tera`, `inventory.yml.tera`
+- Support runtime variables like `{{ instance_name }}`
+
+## � Template Variables
+
+Common variables available in templates:
+
+| Variable              | Description       | Example              |
+| --------------------- | ----------------- | -------------------- |
+| `instance_name`       | VM/container name | `torrust-tracker-vm` |
+| `ansible_host`        | Target server IP  | `10.140.190.11`      |
+| `ssh_pub_key_content` | SSH public key    | `ssh-rsa AAAA...`    |
+
+## 🔄 Template Processing Flow
+
+1. **Template Loading**: Load embedded templates from binary
+2. **Extraction**: Copy templates to build directory
+3. **Variable Resolution**: Render `.tera` templates with runtime values
+4. **Deployment**: Use generated files for infrastructure provisioning
+
+## ⚠️ Important Notes
+
+- Templates are currently embedded and cannot be customized in production deployments
+- All template modifications require recompilation of the binary
+- Templates are tested as part of the CI/CD pipeline to ensure reliability
+
+## 🛠️ Development & Testing
+
+For development and testing purposes only, the system supports external template directories through the `--templates-dir` CLI argument. This is used internally for:
+
+- E2E testing with fresh template states
+- Development and debugging of template rendering
+- Template validation during CI/CD
+
+**Note**: This functionality is not available in production builds and is reserved for development and testing workflows.

src/bin/e2e_tests.rs

@@ -86,7 +86,7 @@ pub async fn main() -> Result<()> {
 
     // Instance name for the test environment - not user configurable for now
     let instance_name =
-        InstanceName::new("torrust-vm".to_string()).expect("Valid hardcoded instance name");
+        InstanceName::new("torrust-tracker-vm".to_string()).expect("Valid hardcoded instance name");
 
     let env = TestEnvironment::new(cli.keep, cli.templates_dir, instance_name)?;
 

src/e2e/tasks/preflight_cleanup.rs

@@ -86,6 +86,9 @@ pub fn cleanup_lingering_resources(env: &TestEnvironment) -> Result<(), Prefligh
     // Clean the build directory to ensure fresh template state for E2E tests
     cleanup_build_directory(env)?;
 
+    // Clean the templates directory to ensure fresh embedded template extraction for E2E tests
+    cleanup_templates_directory(env)?;
+
     // Clean any existing OpenTofu infrastructure from previous test runs
     cleanup_opentofu_infrastructure(env)?;
 
@@ -171,6 +174,78 @@ fn cleanup_build_directory(env: &TestEnvironment) -> Result<(), PreflightCleanup
     }
 }
 
+/// Cleans the templates directory to ensure fresh embedded template extraction for E2E tests
+///
+/// This function removes the templates directory if it exists, ensuring that
+/// E2E tests start with fresh embedded templates and don't use stale cached template files.
+/// This is critical for testing template changes and instance name parameterization.
+///
+/// # Safety
+///
+/// This function is only intended for E2E test environments and should never
+/// be called in production code paths. It's designed to provide test isolation
+/// by ensuring fresh template extraction for each test run.
+///
+/// # Arguments
+///
+/// * `env` - The test environment containing configuration paths
+///
+/// # Returns
+///
+/// Returns `Ok(())` if cleanup succeeds or if the templates directory doesn't exist.
+///
+/// # Errors
+///
+/// Returns a `PreflightCleanupError::ResourceConflicts` error if the templates directory
+/// cannot be removed due to permission issues or file locks.
+fn cleanup_templates_directory(env: &TestEnvironment) -> Result<(), PreflightCleanupError> {
+    let templates_dir = std::path::Path::new(&env.config.templates_dir);
+
+    if !templates_dir.exists() {
+        info!(
+            operation = "templates_directory_cleanup",
+            status = "clean",
+            path = %templates_dir.display(),
+            "Templates directory doesn't exist, skipping cleanup"
+        );
+        return Ok(());
+    }
+
+    info!(
+        operation = "templates_directory_cleanup",
+        path = %templates_dir.display(),
+        "Cleaning templates directory to ensure fresh embedded template extraction"
+    );
+
+    match std::fs::remove_dir_all(templates_dir) {
+        Ok(()) => {
+            info!(
+                operation = "templates_directory_cleanup",
+                status = "success",
+                path = %templates_dir.display(),
+                "Templates directory cleaned successfully"
+            );
+            Ok(())
+        }
+        Err(e) => {
+            warn!(
+                operation = "templates_directory_cleanup",
+                status = "failed",
+                path = %templates_dir.display(),
+                error = %e,
+                "Failed to clean templates directory"
+            );
+            Err(PreflightCleanupError::ResourceConflicts {
+                details: format!(
+                    "Failed to clean templates directory '{}': {}",
+                    templates_dir.display(),
+                    e
+                ),
+            })
+        }
+    }
+}
+
 /// Cleans any existing `OpenTofu` infrastructure from previous test runs
 ///
 /// This function attempts to destroy `OpenTofu` infrastructure that might remain from

templates/tofu/lxd/main.tf

@@ -17,7 +17,7 @@ provider "lxd" {
 variable "instance_name" {
   description = "Name of the LXD instance"
   type        = string
-  default     = "torrust-vm"
+  default     = "torrust-tracker-vm"
 }
 
 variable "image" {