Dockman — container monitoring

Dockman is StatusOwl's container monitoring agent. You run it as a container on each Docker host you want to monitor, and it reports per-container status, CPU, memory, image tag, uptime, and restart count back to your StatusOwl dashboard. It's the Docker-side counterpart to Watch Owl, which monitors the host itself.

What Dockman is

Dockman is a small Python container that talks to your local Docker socket and posts container stats to nest.statusowl.net over HTTPS every 60 seconds. It runs alongside your application containers — one Dockman per Docker host — and it has no external dependencies beyond the Docker socket itself.

A single Dockman instance reports on every container running on its host, including stopped or exited ones. Containers don't need to be configured in StatusOwl ahead of time; new ones appear in the dashboard on the next 60-second poll after they start.

Plan availability

Container monitoring is gated per plan via the max_container_nodes allotment. The Free tier does not include container monitoring — see the pricing page for which plans include it and the per-plan host limit.

Metrics collected

For each container Dockman reports, on every 60-second poll:

The dashboard renders this as:

• Per-host summary: total containers, running count, stopped count, average CPU, total memory.
• Per-container row: name, image, status badge, uptime, restart count (highlighted yellow if > 0), CPU %, memory MB.
• Filter and search by container name, image, or short ID.

How it works

1. You create a container host in the dashboard. The system mints an API key and node UUID and shows them once.
2. You run Dockman with those credentials as environment variables. It connects to your local Docker socket, polls container stats every 60 seconds, and POSTs them to nest.statusowl.net/node/ingest.
3. The dashboard renders live data on the Containers page within a few seconds of each poll.

The agent communicates outbound only during normal operation — it opens an HTTPS connection to nest.statusowl.net:443 and that's it. No inbound port is required for monitoring.

Adding a container host

1. In the dashboard, go to Containers → Add Container Host.
2. Give the host a label (e.g. prod-web-01, staging-api).
3. Click Create. The dashboard shows:
   • Node UUID — a UUID identifying this host.
   • API key — a long, opaque secret. Shown once; copy it immediately.
   • The full docker run snippet pre-populated with both values.

Running Dockman

The dashboard generates a ready-to-paste docker run command, but for reference the canonical form is:

docker run -d \
  --name dockman \
  --restart unless-stopped \
  -e NODE_API_KEY=wo_xxxxxxxxxxxxxxxxxxxx \
  -e NODE_UUID=00000000-0000-0000-0000-000000000000 \
  -e API_BASE=https://nest.statusowl.net/node/ingest \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /opt/statusowl/dockman/data:/opt/statusowl/dockman/data \
  -p 9934:9934 \
  ghcr.io/statusowl/dockman:latest

Within 60 seconds, the host appears in Containers → [host label] with a live container list.

Environment variables

Volumes

• /var/run/docker.sock — the Docker socket. Read-only is enough for metrics; mount it read-write only if you've enabled remote control.
• /opt/statusowl/dockman/data — persistent log directory.

Ports

• 9934 — Dockman's local HTTP server. Used for the container's own health check; also the listener for inbound remote-control calls when REMOTE_CONTROL=true is set. Bind to localhost in production unless you specifically need control from outside the host.

docker-compose

services:
  dockman:
    image: ghcr.io/statusowl/dockman:latest
    container_name: dockman
    restart: unless-stopped
    environment:
      NODE_API_KEY: ${DOCKMAN_NODE_API_KEY}
      NODE_UUID:    ${DOCKMAN_NODE_UUID}
      API_BASE:     https://nest.statusowl.net/node/ingest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /opt/statusowl/dockman/data:/opt/statusowl/dockman/data
    ports:
      - "127.0.0.1:9934:9934"

Verifying

# Container running?
docker ps --filter name=dockman

# Recent logs
docker logs -f dockman

# Health endpoint
curl http://localhost:9934/
# → "StatusOwl Dockman is running"

In the dashboard, the host row should show a green heartbeat indicator (updated within the last 120 seconds) and a non-zero container count.

Container vs HTTP monitoring — when to use which

A typical setup runs both: Dockman watches the container, and an HTTP monitor watches the public service the container serves. When the HTTP monitor goes red but Dockman shows the container is healthy, you've got a service-internal problem; when Dockman shows the container exited but HTTP is still passing, your traffic is hitting a load balancer that hasn't deregistered the dead host yet.

Multi-host fleets

Each Docker host runs its own Dockman with its own node UUID and API key. The dashboard's main Containers page aggregates every host in your organization — you can filter by health (Healthy / Warning / Down) and search by host name. Drill into a single host to see its container list.

There is no "fleet config" — one Dockman per host, one host per node record. To spin up a new host: create a new container host in the dashboard, copy the credentials, run Dockman with them.

Remote control (advanced)

Dockman optionally exposes a control endpoint for start / stop / restart / pause / unpause of individual containers. Disabled by default; enable it by setting REMOTE_CONTROL=true and granting the container read-write access to the Docker socket.

When enabled:

• Dockman listens on port 9934 for POST /control/{container_id}.
• The endpoint requires the same API key in an x-api-key header.
• Allowed actions: start, stop, restart, pause, unpause.
• StatusOwl's backend calls this endpoint outbound from nest.statusowl.net when an authorized user triggers an action.

The backend API exists today; user-facing Start / Stop / Restart buttons in the dashboard ship in a follow-up release. Until then, treat remote control as an opt-in API surface for future use.

Heartbeat and offline detection

Dockman sends a stats payload every 60 seconds. The dashboard considers a host down if the last heartbeat is older than 120 seconds. A host that's intentionally retired stays in the dashboard with a stale heartbeat — delete the host from the dashboard to clear it. Container data is retained on the time-series side per your plan's retention window even after the host is removed.

Uninstall

docker stop dockman
docker rm dockman

To also clean up the credential and log directory:

sudo rm -rf /opt/statusowl/dockman

In the dashboard, open Containers → [host] and delete the host. The container's API key is invalidated on delete.

Troubleshooting

Dockman starts but the host doesn't show up in the dashboard. Check docker logs -f dockman for HTTP errors. Most common causes: wrong NODE_API_KEY, wrong NODE_UUID, or no outbound HTTPS to nest.statusowl.net:443 from the host.

Containers show CPU at 0% across the board. The Docker stats API needs a moment to warm up — Dockman's first poll often shows zero CPU. Wait two intervals (~2 minutes) and refresh.

Container status flips between running and exited repeatedly. That's the restarts counter in motion. Look for the underlying crash loop — Dockman is reporting Docker's reality, not causing it.

Permission denied accessing /var/run/docker.sock. SELinux on RHEL-family hosts requires the :Z mount option, or the container's user must be in the docker group on the host. Inspect the agent logs and pass --privileged only as a last resort — read-only socket mounting is the secure default.

See also

• Watch Owl overview — Linux host metrics (CPU / memory / disk / network).
• Watch Owl alert rules — threshold alerting on host metrics. Container-level alerting is on the roadmap.
• HTTP monitor — pair with Dockman to watch the service inside the container from the outside.