Feature Request: Distributed Monitoring

[avargaskun]

Feature Request: Distributed Monitoring (Agent Mode)

Problem Description

Currently, WUD is designed as a standalone application. To monitor containers on multiple different Docker hosts (e.g., in a homelab environment with multiple servers), a user must deploy a full WUD instance on each host.

This approach has several downsides:

1. Security Risks: While WUD can currently monitor remote hosts by connecting to exposed Docker sockets (via TCP/HTTP), these sockets typically lack built-in authentication. Exposing them creates a significant security vulnerability.
2. Fragmented UI: If running separate instances, the user has to check multiple dashboards to get the status of their infrastructure.
3. Redundant Configuration: Notification triggers (e.g., Slack, Email, MQTT) must be configured identically on every instance.
4. Resource Usage: Running full instances with persistence and UI on every edge node is inefficient.

Proposed Solution

I propose introducing a Distributed Architecture ("Agent Mode") to WUD.

This would allow WUD to run in two distinct modes:

1. Controller Node: The central server. It maintains the persistent database, serves the unified Web UI, and executes notification triggers.
2. Agent Node: A lightweight instance running on remote Docker hosts. It performs local container discovery and registry checks, then forwards the results to the Controller.

Architecture & Approach

1. Communication Protocol

The Controller will act as the client, establishing a connection to the Agents.

• Transport: HTTP/HTTPS.
• Real-time Updates: Agents will push state changes (Container Added/Updated/Removed) to the Controller via Server-Sent Events (SSE).
• Security: Authentication via a shared secret header (X-Wud-Agent-Secret).

2. Responsibilities

• Agent:
  • Discovery: Runs local Watchers (e.g., Docker socket) to find containers.
  • Analysis: Performs Registry checks locally. This ensures that the Agent (which likely has the correct network context/credentials) resolves the tags.
  • Stateless: Uses an in-memory store; no persistence to disk required.
• Controller:
  • Aggregation: Receives Container objects from multiple Agents and merges them into its main store.
  • Visualization: Displays the source Agent in the UI.
  • Action: Manages Triggers. Notification triggers run locally on the Controller. Action triggers (like docker.restart) are proxied back to the specific Agent for execution.

3. Configuration Experience

This feature should be purely configuration-driven using environment variables.

Agent:

# Starts in Agent mode
WUD_AGENT_SECRET=mysecret
node index.js --agent

Controller:

# Connects to the agent
WUD_AGENT_NODE1_HOST=192.168.1.50
WUD_AGENT_NODE1_SECRET=mysecret

Benefits

• Single Pane of Glass: One dashboard for all containers across the infrastructure.
• Centralized Notifications: Configure Slack/Gotify once on the Controller; receive alerts for all Agents.
• Scalability: Easier to manage 10+ hosts without juggling 10+ URLs.

[avargaskun]

I've implemented this feature in a fork at: https://github.com/avargaskun/wud/tree/dev commit: a12ba42

You can try it out by pulling WUD from the following: ghcr.io/avargaskun/wud:dev

More info:

• User guide: https://github.com/avargaskun/wud/tree/dev/docs/configuration/agents
• Developer guide: https://github.com/avargaskun/wud/blob/dev/dev/agent-mode.md

@fmartinou - I would love to contribute this feature, but a few PRs would need to be merged first: #893 and #900

[s-b-e-n-s-o-n]

This has been implemented in WUD-CE as of 9.0.0-ce — agent mode with distributed monitoring, remote agent architecture, and SSE-based communication.

[s-b-e-n-s-o-n]

Shipped: Agent mode merged to main (f3cee9b, 00968f3).

[HerrMuellerluedenscheid]

@avargaskun I had the same need to separate the monitoring from the data collection some time ago and didn't find the solution I wanted also because of other constraints (mostly running the agent on a contraint embedded linux which didn't have a lot of resources). So I started hoister. https://github.com/HerrMuellerluedenscheid/hoister It is not as feature complete as WUD but I'm always happy if people give it a try and tell me what feature they are missing.