Merge #132: feat: Add Docker test infrastructure for dependency-installer CLI

0b0beda test: [#116] rename tests to follow it_should pattern and reveal intentions (Jose Celano)
194ce60 refactor: [#116] apply module organization conventions to dependency-installer package (Jose Celano)
3572826 refactor: [#116] improve structured logging with consistent status field (Jose Celano)
7d9fefb feat: [#116] add --log-level CLI option to control logging output (Jose Celano)
6c62e5f refactor: [#116] simplify dependency-installer output to use structured logging only (Jose Celano)
1a7c639 refactor: [#116] normalize 'tool' to 'dependency' terminology and use Dependency enum in error types (Jose Celano)
2268d4b refactor: [#116] use Dependency enum for type-safe dependency references (Jose Celano)
7bc0b8f refactor: [#116] eliminate map_err calls using From trait implementations (Jose Celano)
36f9627 refactor: [#116] replace Box<dyn Error> with concrete error enums in dependency-installer (Jose Celano)
7e461ed refactor: [#116] extract handlers module with check and list submodules (Jose Celano)
7da8994 refactor: [#116] extract logging into dedicated module (Jose Celano)
8048ea8 refactor: [#116] introduce ExitCode type alias (Jose Celano)
98b1b9c refactor: [#116] introduce CommandOutput type for container execution (Jose Celano)
41690ea refactor: [#116] improve container test utilities structure (Jose Celano)
a3b70c4 fix: [#116] address clippy linting errors (copilot-swe-agent[bot])
7432591 refactor: [#116] address code review feedback (copilot-swe-agent[bot])
2040c38 style: [#116] fix rustfmt formatting issues (copilot-swe-agent[bot])
b5af2fc feat: [#116] add Docker test infrastructure for CLI (copilot-swe-agent[bot])
c302577 Initial plan (copilot-swe-agent[bot])

Pull request description:

  Create Docker Test Infrastructure for CLI Binary Testing

  This PR implements Docker-based testing infrastructure to verify the CLI binary works correctly in a clean Ubuntu 24.04 environment.

  **Implementation Plan:**
  - [x] Create Dockerfile for Ubuntu 24.04 testing environment
  - [x] Create Docker README documentation
  - [x] Add testcontainers dependency to Cargo.toml
  - [x] Create container helper modules (ubuntu.rs, helpers.rs, mod.rs)
  - [x] Create integration test file (docker_check_command.rs)
  - [x] Implement test for checking missing dependencies
  - [x] Implement test for checking specific tools
  - [x] Implement test for list command
  - [x] Implement test for verbose output
  - [x] Manual verification of all tests (all 4 tests passing)
  - [x] Run pre-commit checks and fix any issues
  - [x] Address code review feedback
  - [x] Fix all linting errors

  **Linting Fixes (commit hash pending):**
  - Fixed `uninlined_format_args` warnings - updated all format strings to use inline syntax
  - Fixed `doc_markdown` warnings - added backticks to `code()`, `CARGO_MANIFEST_DIR`, etc.
  - Fixed `unused_self` warning - added `#[allow(clippy::unused_self)]` to fluent builder method
  - Fixed `unnecessary_debug_formatting` - changed `{:?}` to `Display` formatting with `.display()`

  **All Linters Passing:**
  - ✅ Markdown linting
  - ✅ YAML linting
  - ✅ TOML linting
  - ✅ Spell checking (cspell)
  - ✅ Clippy (Rust linting)
  - ✅ Rustfmt (code formatting)
  - ✅ ShellCheck

  **Test Results:**
  ```
  running 4 tests
  test test_check_all_reports_missing_dependencies ... ok
  test test_check_specific_tool ... ok
  test test_list_command ... ok
  test test_verbose_output ... ok

  test result: ok. 4 passed; 0 failed; 0 ignored
  ```

  <!-- START COPILOT CODING AGENT SUFFIX -->

  <details>

  <summary>Original prompt</summary>

  >
  > ----
  >
  > *This section details on the original issue you should resolve*
  >
  > <issue_title>Create Docker Test Infrastructure</issue_title>
  > <issue_description>**Parent Issue**: #113 - Create Dependency Installation Package for E2E Tests
  > **Depends On**: #115 - Create CLI Binary with Check Command (Issue 1-1-2)
  > **Epic**: #112 - Refactor and Improve E2E Test Execution
  >
  > ## Overview
  >
  > Create Docker-based testing infrastructure to verify the CLI binary works correctly in a clean Ubuntu environment. This ensures the binary can detect missing dependencies and provides confidence before implementing installation logic.
  >
  > This is **Phase 3 of 4** for building the dependency installation package.
  >
  > ## Objectives
  >
  > - Create Dockerfile based on ubuntu:24.04
  > - Set up container helpers for file operations
  > - Write Docker-based tests for the CLI binary
  > - Test detection of missing and installed tools
  > - Verify exit codes and error messages
  >
  > ## Key Components
  >
  > **Dockerfile**:
  > - Base: ubuntu:24.04
  > - Installs: build-essential, curl
  > - Does NOT install: cargo-machete, OpenTofu, Ansible, LXD (tests detection of missing deps)
  >
  > **Container Helpers**:
  > - Copy existing helpers from `src/testing/e2e/containers/`
  > - `copy_file_to_container()` - Copy binary to container
  > - Container startup and cleanup utilities
  >
  > **Tests**:
  > - Test binary detects missing dependencies correctly
  > - Test binary reports installed dependencies correctly
  > - Verify exit codes (0 for all present, 1 for missing deps)
  >
  > ## Acceptance Criteria
  >
  > - Pre-commit checks pass
  > - Dockerfile builds successfully
  > - Docker tests run and pass
  > - CLI binary correctly detects missing tools
  > - Exit codes are correct in all scenarios
  > - Tests are documented and maintainable
  >
  > ## Time Estimate
  >
  > 2-3 hours
  >
  > ## Related Documentation
  >
  > - Full specification: [docs/issues/116-1-1-3-create-docker-test-infrastructure.md](https://github.com/torrust/torrust-tracker-deployer/blob/main/docs/issues/116-1-1-3-create-docker-test-infrastructure.md)
  > - Issue 1-1-2: CLI binary being tested</issue_description>
  >
  > ## Comments on the Issue (you are @copilot in this section)
  >
  > <comments>
  > </comments>
  >

  </details>

  - Fixes #116

  <!-- START COPILOT CODING AGENT TIPS -->
  ---

  💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.

ACKs for top commit:
  josecelano:
    ACK 0b0beda

Tree-SHA512: 74d1a3bf8dda5271f3c84b2f4792dcef886977efeb8509d11c2f84c6a8c4477034df8cee4160c31f289d444058ce3eb686c6df84edfb8f0dbb37f3861549873e

Author: josecelano

packages/dependency-installer/Cargo.toml

@@ -18,3 +18,11 @@ clap = { version = "4.0", features = [ "derive" ] }
 thiserror = "1.0"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = [ "env-filter" ] }
+
+[dev-dependencies]
+testcontainers = "0.25"
+tokio = { version = "1.0", features = [ "full" ] }
+
+[[test]]
+name = "docker_check_command"
+path = "tests/docker_check_command.rs"

packages/dependency-installer/README.md

@@ -2,14 +2,28 @@
 
 This package provides dependency detection and installation utilities for the Torrust Tracker Deployer project.
 
+## Design Philosophy
+
+**This is an internal automation tool** - Its primary purpose is to check dependencies in CI/CD pipelines and automated workflows. As such, it uses **structured logging only** (via the `tracing` crate) rather than user-facing console output.
+
+This design choice offers several benefits:
+
+- **Automation-friendly**: Structured logs are easy to parse and filter programmatically
+- **Consistent**: Same output format as the rest of the Torrust ecosystem
+- **Simple**: The tool is straightforward enough that logging output is sufficient even for manual use
+- **Observable**: Rich contextual information through structured fields
+
+For manual usage, you can control log verbosity with the `--verbose` flag or `RUST_LOG` environment variable.
+
 ## Features
 
-- **Tool Detection**: Check if required development tools are installed
-- **Extensible**: Easy to add new tool detectors
-- **Logging**: Built-in tracing support for observability
+- **Dependency Detection**: Check if required development tools are installed
+- **Extensible**: Easy to add new dependency detectors
+- **Structured Logging**: Built-in tracing support for observability and automation
+- **Type-Safe**: Uses strongly-typed enums for dependencies
 - **Error Handling**: Clear, actionable error messages
 
-## Required Tools
+## Supported Dependencies
 
 This package can detect the following development dependencies:
 
@@ -25,16 +39,20 @@ This package can detect the following development dependencies:
 The package provides a `dependency-installer` binary for command-line usage:
 
 ```bash
-# Check all dependencies
+# Check all dependencies (default: info log level)
 dependency-installer check
 
-# Check specific tool
-dependency-installer check --tool opentofu
+# Check specific dependency
+dependency-installer check --dependency opentofu
 
-# List all tools with status
+# List all dependencies with status
 dependency-installer list
 
-# Enable verbose logging
+# Control log level (off, error, warn, info, debug, trace)
+dependency-installer check --log-level debug
+dependency-installer check --log-level off   # Disable all logging
+
+# Enable verbose logging (equivalent to --log-level debug)
 dependency-installer check --verbose
 
 # Get help
@@ -49,42 +67,49 @@ dependency-installer check --help
 - **2**: Invalid arguments
 - **3**: Internal error
 
-#### Examples
+#### Output Format
+
+The tool uses structured logging (via `tracing`) instead of plain text output:
 
 ```bash
-# Check all dependencies
+# Check all dependencies (default log level shows INFO and above)
 $ dependency-installer check
-Checking dependencies...
-
-✓ cargo-machete: installed
-✗ OpenTofu: not installed
-✗ Ansible: not installed
-✓ LXD: installed
-
-Missing 2 out of 4 required dependencies
-
-# Check specific tool (with aliases)
-$ dependency-installer check --tool tofu
-✗ OpenTofu: not installed
-
-# List all tools
+2025-11-04T17:33:20.959847Z  INFO torrust_dependency_installer::handlers::check: Checking all dependencies
+2025-11-04T17:33:20.960126Z  INFO torrust_dependency_installer::handlers::check: Dependency check result dependency="cargo-machete" status="installed"
+2025-11-04T17:33:20.960131Z  INFO torrust_dependency_installer::handlers::check: Dependency check result dependency="OpenTofu" status="not installed"
+2025-11-04T17:33:20.960136Z  INFO torrust_dependency_installer::handlers::check: Dependency check result dependency="Ansible" status="not installed"
+2025-11-04T17:33:20.960139Z  INFO torrust_dependency_installer::handlers::check: Dependency check result dependency="LXD" status="installed"
+2025-11-04T17:33:20.960144Z  INFO torrust_dependency_installer::handlers::check: Missing dependencies missing_count=2 total_count=4
+Error: Check command failed: Failed to check all dependencies: Missing 2 out of 4 required dependencies
+
+# Check specific dependency
+$ dependency-installer check --dependency opentofu
+2025-11-04T17:33:20.959855Z  INFO torrust_dependency_installer::handlers::check: Checking specific dependency dependency=opentofu
+2025-11-04T17:33:20.960473Z  INFO torrust_dependency_installer::detector::opentofu: OpenTofu is not installed dependency="opentofu"
+2025-11-04T17:33:20.960482Z  INFO torrust_dependency_installer::handlers::check: Dependency is not installed dependency="OpenTofu" status="not installed"
+Error: Check command failed: Failed to check specific dependency: opentofu: not installed
+
+# List all dependencies
 $ dependency-installer list
-Available tools:
-
-- cargo-machete (installed)
-- OpenTofu (not installed)
-- Ansible (not installed)
-- LXD (installed)
+2025-11-04T17:33:20.960482Z  INFO torrust_dependency_installer::handlers::list: Available dependency dependency="cargo-machete" status="installed"
+2025-11-04T17:33:20.960494Z  INFO torrust_dependency_installer::handlers::list: Available dependency dependency="OpenTofu" status="not installed"
+2025-11-04T17:33:20.960962Z  INFO torrust_dependency_installer::handlers::list: Available dependency dependency="Ansible" status="not installed"
+2025-11-04T17:33:20.961521Z  INFO torrust_dependency_installer::handlers::list: Available dependency dependency="LXD" status="installed"
+
+# Enable verbose logging (includes DEBUG level)
+$ dependency-installer check --verbose
+2025-11-04T17:33:20.959872Z DEBUG torrust_dependency_installer::detector::cargo_machete: Checking if cargo-machete is installed dependency="cargo-machete"
+...
 ```
 
-#### Tool Aliases
+#### Dependency Names
 
-The CLI accepts multiple aliases for tools:
+The CLI accepts the following dependency names:
 
-- `cargo-machete` or `machete`
-- `opentofu` or `tofu`
-- `ansible`
-- `lxd`
+- `cargo-machete` - Rust dependency analyzer
+- `opentofu` - Infrastructure provisioning tool
+- `ansible` - Configuration management tool
+- `lxd` - Lightweight VM manager
 
 ### Library Usage
 
@@ -94,33 +119,44 @@ The CLI accepts multiple aliases for tools:
 use torrust_dependency_installer::DependencyManager;
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Initialize tracing for structured logging
+    tracing_subscriber::fmt::init();
+
     let manager = DependencyManager::new();
-    
+
     // Check all dependencies
     let results = manager.check_all()?;
-    
+
     for result in results {
-        println!("{}: {}", result.tool, if result.installed { "✓" } else { "✗" });
+        let detector = manager.get_detector(result.dependency);
+        tracing::info!(
+            dependency = detector.name(),
+            installed = result.installed,
+            "Dependency status"
+        );
     }
-    
+
     Ok(())
 }
 ```
 
 #### Using Individual Detectors
 
 ```rust
-use torrust_dependency_installer::{ToolDetector, OpenTofuDetector};
+use torrust_dependency_installer::{DependencyDetector, Dependency, DependencyManager};
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let detector = OpenTofuDetector;
-    
+    tracing_subscriber::fmt::init();
+
+    let manager = DependencyManager::new();
+    let detector = manager.get_detector(Dependency::OpenTofu);
+
     if detector.is_installed()? {
-        println!("{} is installed", detector.name());
+        tracing::info!(dependency = detector.name(), "Dependency is installed");
     } else {
-        println!("{} is not installed", detector.name());
+        tracing::warn!(dependency = detector.name(), "Dependency is not installed");
     }
-    
+
     Ok(())
 }
 ```

packages/dependency-installer/docker/README.md

@@ -0,0 +1,60 @@
+# Docker Testing Infrastructure
+
+This directory contains Docker configurations for testing the dependency-installer CLI.
+
+## Images
+
+### ubuntu-24.04.Dockerfile
+
+Base Ubuntu 24.04 image for testing the CLI binary in a clean environment.
+
+**Purpose**: Verify that the `dependency-installer check` command correctly detects missing tools.
+
+**Usage in tests**:
+
+```rust
+let image = GenericImage::new("ubuntu", "24.04")
+    .with_wait_for(WaitFor::message_on_stdout("Ready"));
+```
+
+## Testing Strategy
+
+1. Build the binary: `cargo build --bin dependency-installer`
+2. Copy binary into container using testcontainers
+3. Run `check` command in container
+4. Verify it correctly reports missing tools
+5. (Phase 4) Install tools and verify installation
+
+## Building Images
+
+```bash
+cd packages/dependency-installer
+docker build -f docker/ubuntu-24.04.Dockerfile -t dependency-installer-test:ubuntu-24.04 .
+```
+
+## Running Tests
+
+```bash
+# Run all Docker-based integration tests
+cd packages/dependency-installer
+cargo test --test docker_check_command
+
+# Run a specific test
+cargo test --test docker_check_command test_check_all_reports_missing_dependencies
+```
+
+## Container Architecture
+
+The tests use testcontainers to:
+
+- Automatically start and stop Docker containers
+- Copy the compiled binary into containers
+- Execute commands and capture output
+- Verify exit codes and output messages
+
+This ensures tests run in isolated, reproducible environments.
+
+## Related
+
+- `tests/docker_check_command.rs` - Integration tests using this infrastructure
+- `tests/containers/` - Container helper utilities

packages/dependency-installer/docker/ubuntu-24.04.Dockerfile

@@ -0,0 +1,30 @@
+# Dockerfile for Testing the Dependency Installer CLI
+# 
+# This minimal Ubuntu 24.04 image is used for integration testing of the
+# dependency-installer CLI binary. It intentionally does NOT include the
+# tools we need to detect (cargo-machete, OpenTofu, Ansible, LXD) so we
+# can verify that the CLI correctly identifies missing dependencies.
+
+FROM ubuntu:24.04
+
+# Metadata
+LABEL description="Ubuntu 24.04 testing environment for dependency-installer CLI"
+LABEL maintainer="Torrust Development Team"
+LABEL version="1.0.0"
+LABEL purpose="dependency-installer-integration-testing"
+
+# Install minimal dependencies needed for running the binary
+# Note: We intentionally do NOT install the tools we're testing for
+RUN apt-get update && \
+    apt-get install -y \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# The binary will be copied by testcontainers at runtime
+# No need to copy it here - testcontainers handles that dynamically
+
+# Default command - keeps container running for test execution
+CMD ["/bin/bash", "-c", "while true; do sleep 1000; done"]

packages/dependency-installer/examples/check_dependencies.rs

@@ -8,8 +8,8 @@
 use torrust_dependency_installer::{init_tracing, DependencyManager};
 
 fn main() {
-    // Initialize tracing for structured logging
-    init_tracing();
+    // Initialize tracing for structured logging with INFO level
+    init_tracing(Some(tracing::Level::INFO));
 
     println!("Checking development dependencies...\n");
 
@@ -23,14 +23,16 @@ fn main() {
             println!("{}", "=".repeat(40));
 
             for result in &results {
+                let detector = manager.get_detector(result.dependency);
+                let name = detector.name();
                 let status = if result.installed { "✓" } else { "✗" };
                 let status_text = if result.installed {
                     "Installed"
                 } else {
                     "Not Installed"
                 };
 
-                println!("{} {:20} {}", status, result.tool, status_text);
+                println!("{status} {name:20} {status_text}");
             }
 
             println!("\n{} dependencies checked", results.len());