Dokploy Monitoring#

dokploy-monitoring is a Go application that collects host system metrics (CPU, memory, disk, network) and per-container metrics from remote servers, stores them in a local SQLite database, and POSTs threshold alerts back to the main Dokploy server. It runs as a Docker container (dokploy/monitoring:latest or :canary) and is deployed once per registered remote server via monitoring-setup.ts.

Configuration#

All configuration is passed as a single JSON blob in the METRICS_CONFIG environment variable 1. The Go app loads it once at startup via GetMetricsConfig(), which uses sync.Once to parse and validate the JSON 1. Fatal errors are raised if token or urlCallback are missing.

The config schema is defined in two places that must stay in sync:

• Go: Config struct in apps/monitoring/config/metrics.go
• TypeScript: metricsConfig jsonb column in packages/server/src/db/schema/server.ts

Key fields 2:

Validation schema (TypeScript/Zod): apiUpdateServerMonitoring — refreshRate min 2, port min 1, retentionDays min 1, cronJob min 1 char, urlCallback must be a valid URL.

Initialization & Startup Sequence#

The main() function boots the application in this order:

1. Load .env — godotenv.Load() (no-op if absent)
2. Parse config — config.GetMetricsConfig() reads METRICS_CONFIG 3
3. Init SQLite — database.InitDB() opens monitoring.db at /app/monitoring.db 4
4. Start cleanup cron — database.StartMetricsCleanup(db, retentionDays, cronExpression) schedules periodic deletion of stale rows 5
5. Start Fiber HTTP server — listens on server.port (default 3001 if 0) 6
6. Start container monitor — containers.NewContainerMonitor(db).Start() begins periodic docker stats collection 7
7. Start server metrics goroutine — ticker fires every refreshRate seconds, calls monitoring.GetServerMetrics(), saves to DB, then calls monitoring.CheckThresholds() 8

HTTP API#

All routes except /health require bearer-token auth via middleware.AuthMiddleware() 9.

Lifecycle Management#

Deployment (Server Setup)#

setupMonitoring(serverId) is called from serverSetup() — currently only in the cloud-hosted path — after generating a fresh auth token and callback URL. It:

1. Creates /etc/dokploy/monitoring/monitoring.db on the remote server via execAsyncRemote 10
2. Pulls dokploy/monitoring:latest (or :canary in dev/non-latest) 11
3. Force-removes any existing dokploy-monitoring container 12
4. Creates and starts a new container with RestartPolicy: always 13

The monitoring container runs with NetworkMode: "host" and these bind mounts 14:

setupWebMonitoring() is a parallel function for the local (web server) monitoring instance, using the same pattern but calling pullImage/execAsync instead of their remote equivalents, and without NetworkMode: "host".

Cleanup / Retention#

StartMetricsCleanup schedules a cron job using github.com/robfig/cron. On each tick, CleanupMetrics deletes rows older than retentionDays from both container_metrics and server_metrics tables using a UTC RFC3339 cutoff timestamp. The cron handle is stopped via defer cleanupCron.Stop() on process exit 15.

Threshold Alerts#

The Go CheckThresholds() function 16 compares live CPU/memory metrics against configured thresholds, then POSTs an AlertPayload to server.urlCallback. The callback target is the tRPC endpoint notification.receiveNotification on the main Dokploy server 17. The Node.js side dispatches the alert to all configured notification channels (Discord, Slack, Teams, Telegram, etc.) via sendServerThresholdNotifications().

Key Source Files#