Enabling Docker Integration

Overview

The PatchMon agent includes an optional Docker integration that discovers containers, images, volumes, and networks on the host and reports them to the PatchMon server. When enabled, the agent also subscribes to the Docker event stream and relays container lifecycle events (start, stop, die, pause, unpause, kill, destroy) as status updates, keeping the fleet-wide Docker inventory broadly in sync with what is running.

This page covers what the integration does, how to enable it per host from the PatchMon UI, what the agent needs on the host, how config.yml reflects the toggle, and what to check when the integration doesn't report.

Module gate: The Docker views (/docker/* routes, Docker tabs on Host Detail) require the docker module to be enabled on your plan. Plans without the module show a tier badge on the Docker tab and an upgrade prompt when you navigate to /docker.

Permission required: can_manage_hosts to toggle the integration; can_view_hosts to see the resulting inventory.

What the Integration Does

When enabled on a host, the agent:

1. Discovers inventory on each report: lists all containers (running and stopped), images (including intermediate layers PatchMon elects to ignore), volumes (local / NFS / custom driver), and networks (bridge / host / overlay / macvlan / user-defined).
2. Streams container events in real time: subscribes to the Docker daemon's event bus. Each relevant event (start, stop, die, pause, unpause, kill, destroy) is translated into a container_start / container_stop / container_die / container_pause / container_unpause / container_kill / container_destroy status event and pushed to the server over the agent's WebSocket.
3. Resolves image provenance: for each image, PatchMon attempts to attribute it to a registry (Docker Hub, GHCR, GitLab, Quay, ECR, ACR, GCR, local, private) and makes the registry entry clickable when possible.
4. Tracks available updates: compares the running image tag against available tags in the registry (where the registry allows it) and flags images with newer versions.
5. Feeds the Compliance module: if compliance scanning is also enabled for the host, Docker Bench for Security can run as an additional scanner (see the Compliance chapter).

The resulting data powers two places in the UI:

• The Docker Inventory page at /docker: fleet-wide view across all hosts. See Docker Inventory Tour.
• The Docker tab on the Host Detail page: the same data filtered to one host.

Agent Prerequisites on the Host

The Docker integration talks directly to the Docker daemon through the Unix socket. What the agent needs on the host:

The Docker binary (docker) is not required on the PATH. The agent uses the Docker Engine API directly via the socket, so the CLI is optional. You can verify the socket path and daemon version from the host with a quick command:

ls -l /var/run/docker.sock
docker version   # if the CLI is installed

Windows hosts: The agent's Docker integration is Linux / FreeBSD only. Windows hosts do not surface the Docker tab regardless of whether Docker Desktop is installed.

Enabling the Integration from the UI

There are two places to switch it on:

On a new host during enrolment

On step 2 of the Add Host wizard (Host details), the Integrations section has a Docker toggle. Tick it before clicking Next. When the agent first connects, it will already have docker: true in its config.yml and start collecting data on the first report.

See Adding a Host.

On an existing host

1. Open Hosts → click the host's friendly name to open its Host Detail page.
2. Click the Integrations tab.
3. Find the Docker panel.
4. Click the toggle at the right of the panel to set it to Enabled.
5. A yellow banner appears at the top of the tab and the page header: Pending configuration changes.
6. Click Apply in the page header to push the change to the agent over the WebSocket.

The agent then:

• Updates config.yml to set integrations.docker: true.
• Re-initialises its integration manager.
• Starts collecting Docker inventory on the next reporting cycle (typically within one report interval; the default is 60 minutes, but the initial report after enabling is sent immediately).
• Begins streaming container events.

What "Pending configuration changes" means

The toggle on the UI writes the desired state to the PatchMon server. The change is only actually sent to the agent when you click Apply, which broadcasts the new config over the WebSocket. If the agent is offline, Apply is disabled and the banner tells you so. The change waits in pending state until the agent reconnects.

You'll see integrations.docker change in the agent's config.yml shortly after Apply is clicked, without needing to restart the service (the update interval and integration toggles are synced at runtime).

Disabling the Integration

From the same Integrations tab on the host:

1. Click the Docker toggle to Disabled.
2. Click Apply in the page header.

After the change is applied:

• The agent stops discovering Docker inventory.
• Existing inventory records remain in PatchMon (so historical queries and event history are preserved), but the agent will no longer refresh them.
• Container event streaming is stopped.

Disabling does not remove Docker from the host or stop containers; it only instructs the agent to stop monitoring.

How It Looks in config.yml

The agent config file is located at:

• Linux / FreeBSD: /etc/patchmon/config.yml
• Windows: C:\ProgramData\PatchMon\config.yml

The integrations block contains the Docker toggle:

integrations:
  docker: true          # Enabled by the UI toggle
  compliance:
    enabled: false
    on_demand_only: true
    openscap_enabled: true
    docker_bench_enabled: false

See Agent Config YML Reference for the full schema and how each field behaves.

You can enable Docker integration by editing the config file directly, but using the UI toggle is strongly preferred: it keeps the server's view of the host in sync with the config and prevents a subsequent Apply from silently overwriting your edit.

When Docker Integration Doesn't Report

Symptoms you might see:

• The Docker tab never appears on the Host Detail page, even after enabling the integration and clicking Apply.
• The host enabled Docker, but no containers or images appear at /docker.
• Real-time status (container start / stop) doesn't update.

Work through the checks below in order.

1. Confirm the server saw the toggle

On the Host Detail page, open the Integrations tab. The Docker panel should show Enabled with a green badge. If it shows Disabled: the change was not saved. Toggle again and click Apply.

2. Confirm the agent received the config

On the host:

sudo grep -A 4 '^integrations:' /etc/patchmon/config.yml

Expect:

integrations:
  docker: true
  ...

If the file still shows docker: false, the Apply button wasn't clicked or the agent's WebSocket wasn't connected at the time. Back in the UI, look at the page header. If the Apply button is still visible, click it again (the agent must be connected).

3. Confirm the Docker socket is accessible

ls -l /var/run/docker.sock
sudo docker ps        # agent runs as root, so sudo mimics its view

If the socket is missing, Docker isn't installed or isn't running. Install / start Docker and watch the next report.

4. Look at the agent's log for Docker errors

sudo tail -n 50 /etc/patchmon/logs/patchmon-agent.log | grep -i docker

Typical messages:

• Docker socket not found: Docker isn't installed, or the socket has a non-standard path.
• Failed to create Docker client: the socket exists but the agent can't open a client; check permissions.
• Docker container event: confirms the event stream is active and receiving events.
• Docker daemon ping failed, retrying: Docker is installed but unresponsive. The agent will keep retrying.

For the full logging reference, see Managing the PatchMon Agent.

5. Force a report and recheck

Back in the UI, on the Host Detail page, click Fetch Report. The agent collects a fresh inventory (including Docker) and reports immediately. Watch the Docker tab count badges update.

6. Refresh integration status

On the Integrations tab, the Refresh Status button asks the agent to report its current integration readiness state. Useful after installing Docker, fixing socket permissions, or starting the Docker service.

7. Module gate

If the Docker tab shows a tier badge instead of content, the docker module is not enabled on your plan. Contact your PatchMon administrator to enable it on the subscription plan.

Related Pages

• Docker Inventory Tour: what the inventory looks like once the integration is working.
• Host Detail Page: where the Integrations tab lives and how Apply works.
• Adding a Host: enable Docker at enrolment time.
• Agent Config YML Reference: every field in config.yml, including the integrations block.
• Managing the PatchMon Agent: agent logs, diagnostics, and service management.