Docker Stats Dashboard

NOTE: Full coding for this project was completed entirely by AI CODEX under OpenSpec guidance.

A lightweight, two-piece monitoring stack for real-time Docker container metrics. The Go agent streams stats straight from each host, while the SvelteKit dashboard fans them into a single Server-Sent Events (SSE) feed for the browser. Deployment stays simple—no external queues, databases, or heavyweight dependencies required.

Table of contents

1. Why this project?
2. Architecture at a glance
3. Repository layout
4. Quick start
5. Configuration reference
6. Development scripts
7. Continuous integration
8. Production notes
9. Roadmap ideas

Why this project?

• Minimal footprint. The agent is a stateless Go binary that runs alongside workloads without resource contention. The dashboard is a SvelteKit app that streams metrics over SSE; you deploy a single lean Node process per environment.
• Simple operations. Discover hosts, track connection state, and surface per-container CPU/memory stats without provisioning extra infrastructure.
• Frictionless deployment. Run the agent as a Docker container or binary, point the dashboard at your agent URLs via one environment variable, and you are operational in minutes.

Architecture at a glance

Docker Host(s)             Dashboard Host
--------------             ---------------
[docker-agent] --WS-->  ┐  SvelteKit server --SSE--> Browser UI
[docker-agent] --WS-->  ┘

1. Each Docker host runs docker-agent, a Go service that polls the Docker Engine and publishes structured metrics over WebSocket.
2. The dashboard’s Node runtime maintains outbound WebSocket connections to every configured agent.
3. Metrics and status updates are multiplexed into a single SSE stream (/stream/agents), which the browser consumes.

Repository layout

Quick start

1. Run an agent on a Docker host

cd agent
make run     # or: go run .

Default listen address: ws://localhost:8080/ws. Provide a friendly label with AGENT_HOST_LABEL="host-a" if desired.

To containerize instead:

cd agent
docker build -t docker-agent:dev .
docker run --rm \
  -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker-agent:dev

2. Configure and start the dashboard

cd web
cp .env.local.example .env.local
# Edit AGENT_ENDPOINTS, e.g.
# AGENT_ENDPOINTS=ws://host-a:8080/ws;ws://host-b:8080/ws
pnpm install
pnpm dev

Open http://localhost:5173 to view live metrics. The development server fans in all agents and exposes /stream/agents for the UI.

3. Optional: docker-compose for local demo

docker-compose:
  services:
    agent:
      build: ./agent
      environment:
        AGENT_HOST_LABEL: lab-node-1
      volumes:
        - /var/run/docker.sock:/var/run/docker.sock
    dashboard:
      build: ./web
      environment:
        AGENT_ENDPOINTS: ws://agent:8080/ws
      ports:
        - "5173:5173"

The dashboard only needs network access to each agent URL; no shared state is required.

Configuration reference

Agent (agent/)

Dashboard (web/)

Development scripts

Continuous integration

Production notes

• Prefer @sveltejs/adapter-node when deploying the dashboard so the SSE endpoint runs in a long-lived Node process.
• Reverse proxies (Nginx, Caddy, Traefik) can forward /stream/agents like any HTTP request; keep Content-Type: text/event-stream intact.
• Horizontal scale is as simple as running multiple dashboard instances pointing at the same agents. If you need shared history, plug a message bus (Redis, NATS, etc.) behind the hub later.

Roadmap ideas

• In-memory history buffers for sparkline charts.
• Token-based auth on the SSE endpoint.
• Optional WebSocket frontend for command/control (pause or filter streams).

This repository—and every line of code within—was implemented by AI CODEX following the OpenSpec workflow. Contributions are welcome via pull requests.