fix: [#18] skip firewall configuration in container-based E2E tests

- Remove iptables permission detection fallback from ConfigureFirewallStep
- Add TORRUST_TD_SKIP_FIREWALL_IN_CONTAINER env var to explicitly skip firewall step
- Accepts only "true" or "false" (case-sensitive, lowercase) for type safety
- E2E config tests automatically set the env var to skip firewall playbook
- Update documentation in templates/ansible/README.md

UFW/iptables requires kernel capabilities (CAP_NET_ADMIN, CAP_NET_RAW) not
available in unprivileged Docker containers. Container-based E2E tests now
explicitly skip the firewall configuration step while VM-based tests continue
to run it normally.

Author: josecelano

src/application/command_handlers/configure/handler.rs

@@ -164,9 +164,25 @@ impl ConfigureCommandHandler {
             .map_err(|e| (e.into(), current_step))?;
 
         let current_step = ConfigureStep::ConfigureFirewall;
-        ConfigureFirewallStep::new(Arc::clone(&self.ansible_client))
-            .execute()
-            .map_err(|e| (e.into(), current_step))?;
+        // Allow tests or CI to explicitly skip the firewall configuration step
+        // (useful for container-based test runs where iptables/ufw require
+        // elevated kernel capabilities not available in unprivileged containers).
+        let skip_firewall = std::env::var("TORRUST_TD_SKIP_FIREWALL_IN_CONTAINER")
+            .map(|v| v == "true")
+            .unwrap_or(false);
+
+        if skip_firewall {
+            info!(
+                command = "configure",
+                step = "configure_firewall",
+                status = "skipped",
+                "Skipping UFW firewall configuration due to TORRUST_TD_SKIP_FIREWALL_IN_CONTAINER"
+            );
+        } else {
+            ConfigureFirewallStep::new(Arc::clone(&self.ansible_client))
+                .execute()
+                .map_err(|e| (e.into(), current_step))?;
+        }
 
         // Transition to Configured state
         let configured = environment.clone().configured();

src/application/steps/system/configure_firewall.rs

@@ -99,15 +99,22 @@ impl ConfigureFirewallStep {
         );
 
         // Run Ansible playbook (SSH port already resolved during template rendering)
-        self.ansible_client.run_playbook("configure-firewall")?;
-
-        info!(
-            step = "configure_firewall",
-            status = "success",
-            "UFW firewall configured successfully with SSH access preserved"
-        );
-
-        Ok(())
+        match self.ansible_client.run_playbook("configure-firewall") {
+            Ok(_) => {
+                info!(
+                    step = "configure_firewall",
+                    status = "success",
+                    "UFW firewall configured successfully with SSH access preserved"
+                );
+                Ok(())
+            }
+            Err(e) => {
+                // Propagate errors to the caller. Tests that run in container environments
+                // should explicitly opt-out of running this step (for example via an
+                // environment variable) instead of relying on runtime error detection.
+                Err(e)
+            }
+        }
     }
 }
 

src/bin/e2e_config_tests.rs

@@ -112,6 +112,10 @@ struct CliArgs {
 pub async fn main() -> Result<()> {
     let cli = CliArgs::parse();
 
+    // Set environment variable to skip firewall configuration in container-based tests
+    // UFW/iptables requires kernel capabilities not available in unprivileged containers
+    std::env::set_var("TORRUST_TD_SKIP_FIREWALL_IN_CONTAINER", "true");
+
     // Initialize logging with production log location for E2E tests using the builder pattern
     LoggingBuilder::new(std::path::Path::new("./data/logs"))
         .with_format(cli.log_format.clone())

templates/ansible/README.md

@@ -22,7 +22,21 @@ This directory contains Ansible playbook templates for the Torrust Tracker Deplo
 
 - **`wait-cloud-init.yml`** - Waits for cloud-init to complete on newly provisioned VMs
 
-### Configuration Files
+### System Configuration
+
+- **`configure-security-updates.yml`** - Configures automatic security updates
+
+  - Sets up unattended-upgrades for automatic security patches
+
+- **`configure-firewall.yml.tera`** - 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
+  - **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
 
 - **`ansible.cfg`** - Ansible configuration
 - **`inventory.yml.tera`** - Inventory template file (processed by Tera templating engine)
@@ -35,12 +49,19 @@ For a typical deployment:
 2. **`update-apt-cache.yml`** - Update package cache (if needed, skip in CI)
 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)
 
 ## CI/Testing Considerations
 
 - The `update-apt-cache.yml` playbook is separated from installation playbooks to avoid CI issues
 - In E2E tests, you can skip the cache update step to avoid network timeouts
 - The installation playbooks assume the cache is already up-to-date or will handle missing packages gracefully
+- **Firewall configuration** is automatically skipped in container-based E2E tests because:
+  - UFW/iptables require kernel-level capabilities (`CAP_NET_ADMIN`, `CAP_NET_RAW`)
+  - Docker containers run unprivileged by default and lack these capabilities
+  - 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
 
 ## Template Processing