Skip to content

Architecture

Jump to bottom
DockMon Bot edited this page Apr 30, 2026 · 2 revisions

DockMon Architecture

This page provides an overview of DockMon's system architecture, technology stack, and how the various components work together.

System Overview

DockMon is a self-hosted Docker container monitoring and management platform. It runs as a single all-in-one Docker container that includes everything needed to monitor and manage your Docker infrastructure.

Key Capabilities:

  • Monitor containers across unlimited Docker hosts (local, remote via mTLS, or agent-based)
  • Real-time dashboard with WebSocket updates (CPU, memory, network stats)
  • Intelligent auto-restart with configurable retry logic
  • Container updates with multiple strategies (exact, patch, minor, latest tags)
  • Advanced alerting (Discord, Slack, Telegram, Pushover, Gotify, ntfy, SMTP)
  • Container deployments (Docker Run or Docker Compose with templates)
  • HTTP/HTTPS health checks with auto-restart on failure
  • Container tagging and bulk operations

High-Level Architecture

┌────────────────────────────────────────────────────────────────┐
│ DockMon Container                                              │
│                                                                │
│  ┌──────────────┐                                              │
│  │ Nginx :443   │ ← TLS termination, serves React SPA         │
│  └──────┬───────┘                                              │
│         │                                                       │
│         ├─→ Static files (React frontend)                      │
│         └─→ /api/* → Python backend                            │
│                                                                │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │ Python Backend (FastAPI)                                │  │
│  │                                                          │  │
│  │  • REST API for all operations                          │  │
│  │  • WebSocket for real-time updates                      │  │
│  │  • Docker SDK for container management                  │  │
│  │  • Alert evaluation and notification dispatch           │  │
│  │  • Event logging and audit trail                        │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                                │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │ Go Stats Service                                        │  │
│  │                                                          │  │
│  │  • Collects real-time container stats (CPU, mem, net)   │  │
│  │  • WebSocket broadcaster for live metrics               │  │
│  │  • Event aggregation and caching                        │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                                │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │ SQLite Database                                         │  │
│  │                                                          │  │
│  │  • Hosts, containers, events, settings                  │  │
│  │  • Alert rules and notification configs                 │  │
│  │  • Deployment templates                                 │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                                │
│  (All processes managed by Supervisor)                        │
└────────────────────────────────────────────────────────────────┘
         │                                    │
         ▼                                    ▼
┌──────────────────┐              ┌──────────────────────┐
│ Local Docker     │              │ Remote Docker Hosts  │
│ Socket           │              │                      │
│                  │              │ • mTLS connection    │
│                  │              │ • DockMon Agent      │
└──────────────────┘              └──────────────────────┘

Component Communication

Connection Purpose
Frontend ↔ Backend REST API for operations, WebSocket for real-time updates
Frontend ↔ Stats Service WebSocket for live CPU/memory/network metrics
Backend ↔ Docker Python Docker SDK (local socket or mTLS for remote)
Backend ↔ Agent WebSocket for agent-based remote hosts

Multi-Host Architecture

DockMon supports three methods for connecting to Docker hosts:

1. Local Docker Host

Direct connection to the Docker socket mounted into the container.

DockMon Container
    │
    └─→ /var/run/docker.sock

Best for: The host where DockMon itself is running.

2. Remote Docker Host (mTLS)

Secure TLS connection directly to a remote Docker daemon.

DockMon Container
    │
    └─→ TCP :2376 (mTLS) ─→ Remote Docker Daemon

Best for: Servers where you can configure Docker to accept remote connections.

Requirements:

  • Docker daemon configured with TLS
  • CA certificate, client certificate, and client key
  • Network access to port 2376

3. Remote Docker Host (Agent)

Lightweight Go agent that runs on the remote host and connects back to DockMon.

DockMon Container                    Remote Host
    │                                    │
    │ ←──── WebSocket ────────────────── │
    │                                    │
    │                            ┌───────┴───────┐
    │                            │ DockMon Agent │
    │                            │       │       │
    │                            │       ▼       │
    │                            │ Docker Socket │
    │                            └───────────────┘

Best for:

  • Hosts behind firewalls (agent connects outbound)
  • Environments where exposing Docker remotely isn't possible
  • Simpler setup (no mTLS certificates to manage)

Agent deployment options:

  • Docker container (recommended)
  • System service (systemd)

Technology Stack

Backend

Component Technology
Framework Python FastAPI (async)
Database SQLite with SQLAlchemy
Migrations Alembic
Docker Integration Python Docker SDK
Authentication Session-based with bcrypt
Encryption Fernet (for stored credentials)

Frontend

Component Technology
Framework React 18 with TypeScript
Build Tool Vite
Routing React Router
Server State TanStack Query (React Query)
UI Components shadcn/ui (Radix primitives)
Styling Tailwind CSS
Tables TanStack Table
Dashboard Layout React Grid Layout

Go Services

Service Purpose
Stats Service Real-time metrics collection, WebSocket broadcasting, and (optional) historical stats persistence with cascade-tier downsampling
Compose Service Docker Compose deployment, image pull progress, port-conflict validation
Agent Remote host monitoring with Docker access; dual-sends stats to backend (live) and stats-service (historical)

Infrastructure

Component Technology
Container Base Alpine Linux
Web Server Nginx (TLS termination, reverse proxy)
Process Manager Supervisor
TLS OpenSSL 3.x

Data Storage

DockMon uses SQLite for all persistent data storage. The database is stored at /app/data/dockmon.db inside the container (mapped to your data volume).

What's Stored

Data Type Description
Hosts Docker host configurations and connection details
Containers Container metadata, state history, configuration
Events Comprehensive audit trail of all actions
Alert Rules Alert conditions and thresholds
Notifications Notification channel configurations
Settings Global and per-container settings
Deployments Deployment history and templates
Users User accounts and sessions
Stats History Time-series CPU/memory/network metrics (host and container), in cascade tiers — only populated when historical stats persistence is enabled in Settings

Data Persistence

All data is stored in the /app/data volume:

  • dockmon.db - SQLite database
  • certificates/ - TLS certificates for remote hosts
  • logs/ - Application logs (if file logging enabled)

Backup: Simply backup the data volume to preserve all DockMon data.

Real-Time Updates

DockMon uses WebSocket connections for real-time updates:

Stats WebSocket (/ws/stats)

Provides live container metrics:

  • CPU usage percentage
  • Memory usage and limits
  • Network I/O (bytes in/out)
  • Block I/O (read/write)

Updates are pushed every few seconds for active containers.

When historical stats persistence is enabled in Settings, the same stats are also written to the stats-service's persistence layer in the background, in cascade tiers (most recent at full resolution, older data progressively downsampled). The host and container modals query this history via a separate HTTP endpoint to render charts at user-selected time ranges (5m to 90d).

Client WebSocket (/ws/client)

Provides real-time event notifications:

  • Container state changes (start, stop, die, etc.)
  • Update progress
  • Alert triggers
  • System events

Security Model

Authentication

  • Session-based authentication with secure cookies
  • Passwords hashed with bcrypt
  • Rate limiting on login attempts

Network Security

  • All connections use TLS (HTTPS)
  • mTLS for remote Docker connections
  • Agent connections use secure WebSocket (WSS)

Data Security

  • Sensitive data (passwords, API keys) encrypted at rest with Fernet
  • Certificates stored encrypted in database
  • No plaintext secrets in logs

Container Access

  • Read-only Docker socket mount (recommended)
  • Principle of least privilege for operations

Scalability Considerations

DockMon is designed for small to medium deployments:

Metric Tested Capacity
Docker Hosts 50+ hosts
Containers 500+ containers
Concurrent Users 20+ users

Performance Features

  • Efficient WebSocket broadcasting
  • In-memory caching for frequently accessed data
  • Lazy loading of container details
  • Virtual scrolling for large container lists
  • Optimized database queries with indexes

Resource Usage

DockMon itself is lightweight:

  • ~100-200MB memory typical
  • Minimal CPU when idle
  • Database grows with event history (configurable retention)

Related Documentation

Last updated: December 2024

Getting Started

User Guide

Configuration

Remote Monitoring

Access Control

Advanced

Development

Help

Clone this wiki locally