torrust_tracker_deployer_lib/adapters/docker/
error.rs

1//! Docker-specific error types
2
3use thiserror::Error;
4
5use crate::shared::command::CommandError;
6
7/// Errors that can occur during Docker operations
8#[derive(Debug, Error)]
9pub enum DockerError {
10    /// Docker build command failed
11    #[error(
12        "Docker build failed for image '{image}'
13Tip: Run 'docker build -t {image} <path>' manually to see detailed output"
14    )]
15    BuildFailed {
16        image: String,
17        #[source]
18        source: CommandError,
19    },
20
21    /// Failed to list Docker images
22    #[error(
23        "Failed to list Docker images
24Tip: Verify Docker is installed and running: 'docker ps'"
25    )]
26    ListImagesFailed(#[source] CommandError),
27
28    /// Failed to list Docker containers
29    #[error(
30        "Failed to list Docker containers
31Tip: Verify Docker is installed and running: 'docker ps'"
32    )]
33    ListContainersFailed(#[source] CommandError),
34
35    /// Failed to get container logs
36    #[error(
37        "Failed to get logs for container '{container_id}'
38Tip: Verify the container exists: 'docker ps -a'"
39    )]
40    GetLogsFailed {
41        container_id: String,
42        #[source]
43        source: CommandError,
44    },
45}
46
47impl DockerError {
48    /// Get detailed troubleshooting guidance for this error
49    ///
50    /// This method provides comprehensive troubleshooting steps that can be
51    /// displayed to users when they need more help resolving the error.
52    ///
53    /// # Example
54    ///
55    /// ```rust,no_run
56    /// use torrust_tracker_deployer_lib::adapters::docker::DockerClient;
57    ///
58    /// # fn example() {
59    /// let docker = DockerClient::new();
60    ///
61    /// if let Err(e) = docker.build_image(".", "my-app", "latest") {
62    ///     eprintln!("Error: {e}");
63    ///     eprintln!("\nTroubleshooting:\n{}", e.help());
64    /// }
65    /// # }
66    /// ```
67    #[must_use]
68    pub fn help(&self) -> &'static str {
69        match self {
70            Self::BuildFailed { .. } => {
71                "Docker Build Failed - Detailed Troubleshooting:
72
731. Run the build command manually to see full output:
74   docker build -t <image>:<tag> <path>
75
762. Check Dockerfile syntax and verify base image availability:
77   - Ensure FROM statement uses a valid base image
78   - Check that the base image exists locally or can be pulled
79
803. Verify network connectivity for package downloads:
81   - Test internet connection: ping google.com
82   - Check if corporate proxy is blocking Docker Hub
83   - Try with --network=host if behind firewall
84
854. Check Docker daemon logs for system-level issues:
86   journalctl -u docker  # Linux systemd
87   docker info  # General Docker information
88
895. Try rebuilding without cache to avoid stale layers:
90   docker build --no-cache -t <image>:<tag> <path>
91
926. Verify sufficient disk space:
93   df -h  # Check available space
94   docker system df  # Check Docker disk usage
95   docker system prune  # Clean up unused resources
96
97For more information, see Docker documentation: https://docs.docker.com/engine/reference/commandline/build/"
98            }
99
100            Self::ListImagesFailed(_) | Self::ListContainersFailed(_) => {
101                "Docker List Command Failed - Detailed Troubleshooting:
102
1031. Verify Docker is installed and check version:
104   docker --version
105
1062. Check if Docker daemon is running:
107   docker ps  # Quick check
108   systemctl status docker  # Linux systemd
109   docker info  # Detailed daemon information
110
1113. Verify user permissions (avoid running as root):
112   groups  # Check if user is in 'docker' group
113
114   If not in docker group, add yourself:
115   sudo usermod -aG docker $USER
116   # Log out and log back in for changes to take effect
117
1184. Try with sudo as temporary workaround (not recommended for regular use):
119   sudo docker ps
120
1215. Check Docker socket permissions:
122   ls -la /var/run/docker.sock
123   # Should show: srw-rw---- 1 root docker
124
1256. Restart Docker daemon if needed:
126   sudo systemctl restart docker  # Linux systemd
127
128For more information, see Docker installation guide: https://docs.docker.com/engine/install/"
129            }
130
131            Self::GetLogsFailed { .. } => {
132                "Docker Logs Failed - Detailed Troubleshooting:
133
1341. Verify the container exists:
135   docker ps -a  # List all containers (including stopped)
136
1372. Check if container ID or name is correct:
138   - Container IDs can be abbreviated (first 12 characters)
139   - Container names are case-sensitive
140
1413. Try viewing logs with Docker CLI directly:
142   docker logs <container-id>
143   docker logs --tail 100 <container-id>  # Last 100 lines
144   docker logs --follow <container-id>  # Follow log output
145
1464. Check if container was removed:
147   - Containers may be automatically removed with --rm flag
148   - Check if container exists in stopped state
149
1505. Verify Docker daemon is responsive:
151   docker ps  # Should list running containers
152
153If the container doesn't exist, it may have been removed or never created successfully."
154            }
155        }
156    }
157}
torrust_tracker_deployer_lib/adapters/docker/error.rs

torrust_tracker_deployer_lib/adapters/docker/
error.rs
