Docker Widget

Lists all Docker containers on the host with their name, image, status, and uptime. Containers can be started, stopped, restarted, and unpaused directly from the dashboard.

Requirements

• Docker must be running on the host
• The server needs a route to the Docker API

Docker socket access

Docker Compose (recommended): reach the daemon through the filtering proxy that ships in docker-compose.yml, rather than mounting the socket into the app container.

environment:
  - DOCKER_HOST=tcp://docker-socket-proxy:2375

The proxy is configured to allow only container listing and the start/stop/restart calls this widget uses. See Docker deployment for the full service definition.

Do not mount the socket into the app container

Access to /var/run/docker.sock is equivalent to root on the host — it permits creating a privileged container that mounts the host filesystem.

Adding :ro does not make this safe. The flag applies to the filesystem entry, not to the API: a read-only socket mount still accepts POST and will happily start, stop and create containers. It is not a permission boundary, and treating it as one is a common and costly mistake.

Manual / development: with no DOCKER_HOST set the server falls back to DOCKER_SOCKET (default /var/run/docker.sock), which is fine on a development machine. Ensure the user running the server is in the docker group:

sudo usermod -aG docker $USER

Container controls

Each container card shows action buttons based on its current state:

Container state	Available actions
Running	Stop, Restart
Paused	Unpause, Stop
Exited / Created / Dead	Start, Restart

Buttons are disabled while an action is in progress. After a successful action the widget refreshes automatically.

Configuration

No API key required. The Docker socket path defaults to /var/run/docker.sock and can be overridden with the DOCKER_SOCKET environment variable.

Key	Type	Default	Description
hideHeader	boolean	false	Hide the widget title bar
defaultCollapsed	boolean	false	Start collapsed

Troubleshooting

No containers shown

• Check the Docker socket is mounted and the path is correct
• Verify the server has permission: ls -la /var/run/docker.sock
• Look for connection errors in the server logs

Controls not working

• Ensure the socket is mounted without :ro
• Check the server logs for Docker API errors