Verifying Your Docker Setup: Diagnostics, Architecture & hello-world

After installing Docker Engine or Docker Desktop on a new machine or cloud server, verifying daemon connectivity, user socket permissions, and storage drivers is a critical diagnostic step.

In this guide, we walk through running diagnostic checks, understanding the hello-world test container, and fixing common socket permission errors.

Step 1: Running the hello-world Verification Container

The official hello-world image is a lightweight (~13KB) binary designed to test the entire container lifecycle:

docker run --rm hello-world

When you execute this command, Docker performs five sequential steps:

1. Daemon Contact: The Docker client connects to the Docker daemon UNIX socket (/var/run/docker.sock).
2. Image Pull: The daemon checks local image cache. If missing, it pulls hello-world:latest from Docker Hub.
3. Container Creation: The daemon creates a new container instance from the downloaded image.
4. Execution: The container executes a small binary that streams the “Hello from Docker!” message back to your terminal STDOUT.
5. Auto-Cleanup: Because --rm was specified, the container filesystem is removed immediately upon exiting.

[Docker Client] ---> UNIX Socket ---> [Docker Daemon] ---> Docker Hub (Pull Image)
                                           |
                                  Create & Run Container
                                           |
                                  Print "Hello from Docker!"

Step 2: System Diagnostics with docker info

To inspect the underlying system host driver details, run docker info:

docker info

Key diagnostic fields to audit include:

• Server Version: Confirms installed Docker Engine release.
• Storage Driver: Confirms overlay2 storage driver (standard for Linux).
• Cgroup Driver: Confirms systemd cgroup management.
• Architecture: Confirms CPU architecture (x86_64 or aarch64).

Step 3: Troubleshooting Common Socket Permission Errors

If executing docker run returns the error:

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

This indicates your Linux user account lacks permission to communicate with the privileged Docker socket.

Resolution Steps

# 1. Create the docker group if it doesn't exist
sudo groupadd docker

# 2. Add your user account to the docker group
sudo usermod -aG docker $USER

# 3. Apply group membership to current shell session
newgrp docker

# 4. Verify socket connection without sudo
docker ps

Summary

Executing hello-world and checking docker info verifies that your Docker daemon, network interfaces, and socket permissions are correctly configured.

References & Further Reading

• Official Docker Troubleshooting Guide
• Docker CLI Reference: docker info