checkId: check.docker.socket plugin: stellaops.doctor.docker severity: fail tags: [docker, socket, permissions]

Docker Socket

Doctor check check.docker.socket — for operators and DevOps engineers confirming that the Docker socket exists and has the right permissions for Stella Ops services that manage containers (e.g., the scanner and job engine).

What It Checks

Validates that the Docker socket exists and is accessible with correct permissions. The check behavior differs by platform:

Linux / Unix

Checks the Unix socket at the path extracted from Docker:Host (default: /var/run/docker.sock):

Condition	Result
Socket does not exist + running inside a container	`pass` — socket mount is optional for most services
Socket does not exist + not inside a container	`warn`
Socket exists but not readable or writable	`warn` — insufficient permissions
Socket exists and is readable + writable	`pass`

The check detects whether the process is running inside a Docker container by checking for /.dockerenv or /proc/1/cgroup. When running inside a container without a mounted socket, this is considered normal for services that don’t need direct Docker access.

Windows

On Windows, the check verifies that the named pipe path is configured (default: npipe://./pipe/docker_engine). The actual connectivity is deferred to the daemon check since named pipe access testing differs from Unix sockets.

Evidence collected includes: socket path, existence, readability, writability, and whether the process is running inside a container.

Why It Matters

The Docker socket is the communication channel between clients (CLI, SDKs, Stella Ops services) and the Docker daemon. Without socket access:

Docker CLI commands fail.
Services that manage containers (scanner, job engine) cannot create or inspect containers.
Docker Compose operations fail.
Health checks that query Docker state cannot run.

Note that most Stella Ops services do NOT need direct Docker socket access. Only services that manage containers (e.g., scanner, job engine) require the socket to be mounted.

Common Causes

Docker socket not found at the expected path
Docker not installed or daemon not running
Insufficient permissions on the socket file (user not in docker group)
Docker socket not mounted into the container (for containerized services that need it)
SELinux or AppArmor blocking socket access

How to Fix

Docker Compose

Mount the Docker socket for services that need container management:

services:
  scanner:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

  # Most services do NOT need the socket:
  platform:
    # No socket mount needed

Fix socket permissions on the host:

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

# Log out and back in, then verify
docker ps

Bare Metal / systemd

# Check if Docker is installed
which docker

# Check socket existence
ls -la /var/run/docker.sock

# Check socket permissions
stat /var/run/docker.sock

# Add user to docker group
sudo usermod -aG docker $USER
logout  # Must log out and back in

# If socket is missing, start Docker
sudo systemctl start docker

# Verify
docker ps

If SELinux is blocking access:

# Check SELinux denials
sudo ausearch -m avc -ts recent | grep docker

# Allow Docker socket access (create a policy module)
sudo setsebool -P container_manage_cgroup on

Kubernetes / Helm

In Kubernetes, the Docker socket is typically not available. Use the container runtime socket instead:

# For containerd
volumes:
  - name: containerd-sock
    hostPath:
      path: /run/containerd/containerd.sock
      type: Socket

Most Stella Ops services should NOT mount any runtime socket in Kubernetes. Only the scanner or job engine may need it for container-in-container operations.

Verification

stella doctor run --check check.docker.socket

check.docker.daemon— verifies the Docker daemon is running and responsive (uses the socket)
check.docker.apiversion— verifies Docker API version compatibility (requires socket access)
check.docker.network— verifies Docker networks (requires socket access)
check.docker.storage— verifies Docker storage (requires socket access)

See the Doctor reference for the full check catalog, CLI usage, and export bundles.