feat: enhance E2E testing with dynamic port mapping and SSH infrastructure

- Add dynamic port mapping for Docker containers with AnsiblePort type
- Enhance SSH infrastructure to support custom ports (SshConnection, SshClient)
- Improve Docker validation with proper error handling instead of warnings
- Simplify Docker/Docker Compose installation playbooks using Ubuntu repositories
- Update Ansible inventory templates to support custom SSH ports
- Add comprehensive E2E testing for both provision and configuration workflows
- Fix YAML linting issues in Docker Compose templates
- Update project words list for new technical terms

This enables reliable E2E testing with proper port isolation and reduces
network complexity in CI environments. All tests now pass in ~60 seconds
vs previous 8+ minute hangs.

Author: josecelano

.yamllint-ci.yml

@@ -10,5 +10,7 @@ rules:
     allowed-values: ["true", "false", "yes", "no", "on", "off"] # Allow cloud-init and GitHub Actions common values
 
 # Ignore cloud-init files for comment spacing since #cloud-config is a special directive
+# Ignore build directory with generated files
 ignore: |
   **/cloud-init.yml
+  build/**

project-words.txt

@@ -9,6 +9,7 @@ containerd
 cpus
 dearmor
 debootstrap
+distutils
 Dockerfiles
 dtolnay
 ehthumbs

src/application/commands/provision.rs

@@ -150,6 +150,7 @@ impl ProvisionCommand {
             Arc::clone(&self.ansible_template_renderer),
             self.ssh_credentials.clone(),
             instance_ip,
+            22, // Default SSH port for VMs
         )
         .execute()
         .await?;

src/application/steps/rendering/ansible_templates.rs

@@ -28,7 +28,8 @@ use crate::infrastructure::adapters::ssh::credentials::SshCredentials;
 use crate::infrastructure::ansible::template::renderer::ConfigurationTemplateError;
 use crate::infrastructure::ansible::AnsibleTemplateRenderer;
 use crate::infrastructure::template::wrappers::ansible::inventory::{
-    AnsibleHost, InventoryContext, InventoryContextError, SshPrivateKeyFile, SshPrivateKeyFileError,
+    AnsibleHost, AnsiblePort, AnsiblePortError, InventoryContext, InventoryContextError,
+    SshPrivateKeyFile, SshPrivateKeyFileError,
 };
 
 /// Errors that can occur during Ansible template rendering step execution
@@ -38,6 +39,10 @@ pub enum RenderAnsibleTemplatesError {
     #[error("SSH key path parsing failed: {0}")]
     SshKeyPathError(#[from] SshPrivateKeyFileError),
 
+    /// SSH port parsing failed
+    #[error("SSH port parsing failed: {0}")]
+    SshPortError(#[from] AnsiblePortError),
+
     /// Inventory context creation failed
     #[error("Inventory context creation failed: {0}")]
     InventoryContextError(#[from] InventoryContextError),
@@ -52,6 +57,7 @@ pub struct RenderAnsibleTemplatesStep {
     ansible_template_renderer: Arc<AnsibleTemplateRenderer>,
     ssh_credentials: SshCredentials,
     instance_ip: IpAddr,
+    ssh_port: u16,
 }
 
 impl RenderAnsibleTemplatesStep {
@@ -60,11 +66,13 @@ impl RenderAnsibleTemplatesStep {
         ansible_template_renderer: Arc<AnsibleTemplateRenderer>,
         ssh_credentials: SshCredentials,
         instance_ip: IpAddr,
+        ssh_port: u16,
     ) -> Self {
         Self {
             ansible_template_renderer,
             ssh_credentials,
             instance_ip,
+            ssh_port,
         }
     }
 
@@ -112,10 +120,12 @@ impl RenderAnsibleTemplatesStep {
     fn create_inventory_context(&self) -> Result<InventoryContext, RenderAnsibleTemplatesError> {
         let host = AnsibleHost::from(self.instance_ip);
         let ssh_key = SshPrivateKeyFile::new(&self.ssh_credentials.ssh_priv_key_path)?;
+        let ssh_port = AnsiblePort::new(self.ssh_port)?;
 
         InventoryContext::builder()
             .with_host(host)
             .with_ssh_priv_key_path(ssh_key)
+            .with_ssh_port(ssh_port)
             .build()
             .map_err(RenderAnsibleTemplatesError::from)
     }

src/bin/e2e_config_tests.rs

@@ -25,13 +25,12 @@
 
 use anyhow::{Context, Result};
 use clap::Parser;
-use std::net::IpAddr;
 use std::sync::Arc;
 use std::time::Instant;
 use tokio::runtime::Runtime;
 use tracing::{error, info};
 
-use torrust_tracker_deploy::application::commands::{ConfigureCommand, TestCommand};
+use torrust_tracker_deploy::application::commands::ConfigureCommand;
 use torrust_tracker_deploy::config::{Config, InstanceName, SshCredentials};
 use torrust_tracker_deploy::container::Services;
 use torrust_tracker_deploy::e2e::environment::TestEnvironment;
@@ -289,34 +288,25 @@ async fn run_deployment_validation(
         "Running deployment validation on container"
     );
 
-    // NOTE: Similar to configuration, validation needs container-specific setup.
-    // The TestCommand expects standard SSH credentials but needs to connect to
-    // 127.0.0.1:mapped_port instead of the provisioned instance IP.
-    //
-    // For now, we'll demonstrate the validation workflow structure:
-
+    // Now we can use the proper SSH infrastructure with custom port support
     let credentials_result = create_container_ssh_credentials();
     match credentials_result {
         Ok(ssh_credentials) => {
-            let instance_ip: IpAddr = ssh_host
-                .parse()
-                .context("Failed to parse SSH host as IP address")?;
-            let test_command = TestCommand::new(ssh_credentials, instance_ip);
+            // Create SSH connection with the container's dynamic port
+            let host_ip = ssh_host.parse().context("Failed to parse SSH host as IP")?;
 
-            match test_command.execute().await.map_err(anyhow::Error::from) {
+            match validate_container_deployment_with_port(&ssh_credentials, host_ip, ssh_port).await
+            {
                 Ok(()) => {
                     info!(status = "success", "All deployment validations passed");
                 }
                 Err(e) => {
-                    // Expected failure due to SSH connection issues - log and return error
                     info!(
-                        status = "expected_failure",
+                        status = "failed",
                         error = %e,
-                        note = "TestCommand failed as expected - needs container-specific SSH setup"
+                        "Container deployment validation failed"
                     );
-                    return Err(e.context(
-                        "Validation failed (expected - needs container-specific SSH setup)",
-                    ));
+                    return Err(e.context("Container deployment validation failed"));
                 }
             }
         }
@@ -326,8 +316,8 @@ async fn run_deployment_validation(
     }
 
     info!(
-        status = "structural_complete",
-        "Validation workflow structure implemented"
+        status = "success",
+        "Validation workflow completed successfully"
     );
 
     Ok(())
@@ -373,3 +363,35 @@ fn create_container_ssh_credentials() -> Result<SshCredentials> {
 
     Ok(ssh_credentials)
 }
+
+/// Validate container deployment using SSH infrastructure with custom port
+async fn validate_container_deployment_with_port(
+    ssh_credentials: &SshCredentials,
+    host_ip: std::net::IpAddr,
+    ssh_port: u16,
+) -> Result<()> {
+    use torrust_tracker_deploy::infrastructure::remote_actions::{
+        DockerComposeValidator, DockerValidator, RemoteAction,
+    };
+
+    // Create SSH connection with the container's dynamic port using the new port support
+    let ssh_connection = ssh_credentials
+        .clone()
+        .with_host_and_port(host_ip, ssh_port);
+
+    // Validate Docker installation
+    let docker_validator = DockerValidator::new(ssh_connection.clone());
+    docker_validator
+        .execute(&host_ip)
+        .await
+        .context("Docker validation failed")?;
+
+    // Validate Docker Compose installation
+    let compose_validator = DockerComposeValidator::new(ssh_connection);
+    compose_validator
+        .execute(&host_ip)
+        .await
+        .context("Docker Compose validation failed")?;
+
+    Ok(())
+}

src/e2e/provisioned_container.rs

@@ -39,7 +39,7 @@ use std::time::Duration;
 use testcontainers::{
     core::{IntoContainerPort, WaitFor},
     runners::SyncRunner,
-    Container, GenericImage, ImageExt,
+    Container, GenericImage,
 };
 use tracing::info;
 
@@ -91,18 +91,17 @@ impl StoppedProvisionedContainer {
 
         info!("Starting provisioned instance container");
 
-        // Create and start the container with fixed port mapping (22:22)
+        // Create and start the container with automatic port mapping
         let image = GenericImage::new("torrust-provisioned-instance", "latest")
             .with_exposed_port(22.tcp())
             .with_wait_for(WaitFor::message_on_stdout("sshd entered RUNNING state"));
 
-        let container = image
-            .with_mapped_port(22, 22.tcp())
-            .start()
-            .context("Failed to start container")?;
+        let container = image.start().context("Failed to start container")?;
 
-        // Use fixed port 22 since we're mapping 22:22
-        let ssh_port = 22_u16;
+        // Get the actual mapped port from testcontainers
+        let ssh_port = container
+            .get_host_port_ipv4(22.tcp())
+            .context("Failed to get mapped SSH port")?;
 
         info!(
             container_id = %container.id(),

src/e2e/tasks/provision_docker_infrastructure.rs

@@ -57,10 +57,15 @@ pub async fn provision_docker_infrastructure(
 
     // Step 1: Render Ansible templates with container connection details
     info!("Rendering Ansible templates for container");
-    RenderAnsibleTemplatesStep::new(ansible_template_renderer, ssh_credentials, container_ip)
-        .execute()
-        .await
-        .context("Failed to render Ansible templates for container")?;
+    RenderAnsibleTemplatesStep::new(
+        ansible_template_renderer,
+        ssh_credentials,
+        container_ip,
+        ssh_port,
+    )
+    .execute()
+    .await
+    .context("Failed to render Ansible templates for container")?;
 
     // Note: SSH connectivity check is skipped for Docker containers since
     // the container setup process already ensures SSH is ready and accessible

src/infrastructure/adapters/ssh/client.rs

@@ -61,6 +61,8 @@ impl SshClient {
             "StrictHostKeyChecking=no".to_string(),
             "-o".to_string(),
             "UserKnownHostsFile=/dev/null".to_string(),
+            "-p".to_string(),
+            self.ssh_connection.ssh_port().to_string(),
         ];
 
         // Add additional SSH options

src/infrastructure/adapters/ssh/connection.rs

@@ -32,6 +32,12 @@ pub struct SshConnection {
     /// This is the IP address of the remote instance that the SSH client
     /// will connect to.
     pub host_ip: IpAddr,
+
+    /// Port number for SSH connections.
+    ///
+    /// Defaults to 22 (standard SSH port) but can be customized for
+    /// containerized environments or non-standard SSH configurations.
+    pub port: u16,
 }
 
 impl SshConnection {
@@ -49,13 +55,60 @@ impl SshConnection {
     /// let connection = SshConnection::new(
     ///     credentials,
     ///     IpAddr::V4(Ipv4Addr::new(192, 168, 1, 100)),
+    ///     22,
+    /// );
+    /// ```
+    #[must_use]
+    pub fn new(credentials: SshCredentials, host_ip: IpAddr, port: u16) -> Self {
+        Self::new_with_port(credentials, host_ip, port)
+    }
+
+    /// Creates a new SSH connection configuration with the default port (22).
+    ///
+    /// This is a convenience method for when you want to use the standard SSH port.
+    ///
+    /// ```rust
+    /// # use std::net::{IpAddr, Ipv4Addr};
+    /// # use std::path::PathBuf;
+    /// # use torrust_tracker_deploy::infrastructure::adapters::ssh::{SshCredentials, SshConnection};
+    /// let credentials = SshCredentials::new(
+    ///     PathBuf::from("/home/user/.ssh/deploy_key"),
+    ///     PathBuf::from("/home/user/.ssh/deploy_key.pub"),
+    ///     "ubuntu".to_string(),
+    /// );
+    /// let connection = SshConnection::with_default_port(
+    ///     credentials,
+    ///     IpAddr::V4(Ipv4Addr::new(192, 168, 1, 100)),
     /// );
     /// ```
     #[must_use]
-    pub fn new(credentials: SshCredentials, host_ip: IpAddr) -> Self {
+    pub fn with_default_port(credentials: SshCredentials, host_ip: IpAddr) -> Self {
+        Self::new(credentials, host_ip, 22)
+    }
+
+    /// Creates a new SSH connection configuration with a custom port.
+    ///
+    /// ```rust
+    /// # use std::net::{IpAddr, Ipv4Addr};
+    /// # use std::path::PathBuf;
+    /// # use torrust_tracker_deploy::infrastructure::adapters::ssh::{SshCredentials, SshConnection};
+    /// let credentials = SshCredentials::new(
+    ///     PathBuf::from("/home/user/.ssh/deploy_key"),
+    ///     PathBuf::from("/home/user/.ssh/deploy_key.pub"),
+    ///     "ubuntu".to_string(),
+    /// );
+    /// let connection = SshConnection::new_with_port(
+    ///     credentials,
+    ///     IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)),
+    ///     2222,
+    /// );
+    /// ```
+    #[must_use]
+    pub fn new_with_port(credentials: SshCredentials, host_ip: IpAddr, port: u16) -> Self {
         Self {
             credentials,
             host_ip,
+            port,
         }
     }
 
@@ -76,4 +129,10 @@ impl SshConnection {
     pub fn ssh_username(&self) -> &str {
         &self.credentials.ssh_username
     }
+
+    /// Access the SSH port.
+    #[must_use]
+    pub fn ssh_port(&self) -> u16 {
+        self.port
+    }
 }

src/infrastructure/adapters/ssh/credentials.rs

@@ -76,9 +76,12 @@ impl SshCredentials {
     /// with a specific host IP address.
     #[must_use]
     pub fn with_host(self, host_ip: IpAddr) -> SshConnection {
-        SshConnection {
-            credentials: self,
-            host_ip,
-        }
+        SshConnection::with_default_port(self, host_ip)
+    }
+
+    /// Create an SSH connection with a custom port
+    #[must_use]
+    pub fn with_host_and_port(self, host_ip: IpAddr, port: u16) -> SshConnection {
+        SshConnection::new(self, host_ip, port)
     }
 }