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

## 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:

```yaml
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:
```bash
# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in, then verify
docker ps
```

### Bare Metal / systemd
```bash
# 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:
```bash
# 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:

```yaml
# 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
```

## Related Checks
- `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)