dockprom: A Docker Compose Monitoring Stack You Can Read End to End

What dockprom solves, and for whom

A single Docker host accumulates questions that docker stats cannot answer historically: which container grew its memory over the past week, whether the host is swapping, whether the monitoring agents themselves are still up. dockprom answers those by running the standard Prometheus toolchain as a Compose project. The README describes it as "A monitoring solution for Docker hosts and containers", and the repository ships the Compose file, the Prometheus and AlertManager configuration, and the Grafana dashboards already wired together.

The intended user is someone comfortable with Docker Compose and willing to own the configuration. There is no agent to install on a fleet, no hosted control plane, and no API to integrate against. You clone the repository onto the host, run Compose, and the stack collects from that host and its containers. That scope is the point: the whole system fits in a directory you can read in an afternoon.

How the pieces fit: exporters, Prometheus, AlertManager, Caddy

Two exporters produce metrics. NodeExporter runs with /proc, /sys and / mounted read-only from the host and is started with --path.procfs=/host/proc, --path.rootfs=/rootfs and --path.sysfs=/host/sys, so it reports host CPU, memory, disk and network. cAdvisor runs privileged, with /dev/kmsg mapped in, and collects per-container metrics.

Prometheus scrapes both and stores them locally. Its command line sets --storage.tsdb.path=/prometheus and --storage.tsdb.retention.time=200h, so the default retention window is about eight days. The --web.enable-lifecycle flag is what makes the reload endpoint work. AlertManager reads ./alertmanager and evaluates nothing itself; Prometheus evaluates the rules in prometheus/alert.rules and forwards firing alerts. Grafana is preconfigured with Prometheus as its default data source, named Prometheus, of type Prometheus, pointing at http://prometheus:9090 with proxy access.

Only Grafana is published to the host in the usual reading of the Compose file; Prometheus, AlertManager, NodeExporter and cAdvisor use expose on the monitor-net bridge network. Caddy sits in front as reverse proxy and basic auth provider for Prometheus and AlertManager, which is why the install command requires a password hash rather than a plaintext password.

Installing dockprom and getting the first dashboard

Clone the repository on the Docker host and start the stack. Docker Engine >= 1.13 and Docker Compose >= 1.11 are the stated prerequisites. The README's install command passes the Grafana admin credentials and a Caddy password hash as environment variables:

git clone https://github.com/stefanprodan/dockprom
cd dockprom

ADMIN_USER='admin' ADMIN_PASSWORD='admin' ADMIN_PASSWORD_HASH='$2a$14$1l.IozJx7xQRVmlkEQ32OeEEfP5mRxTpbDTCTcXRqn19gXD8YK1pO' docker-compose up -d

The hash shown corresponds to the password admin, which is a starting point and not a deployment setting. Caddy v2 will not accept a plaintext password, so generate your own before exposing anything:

docker run --rm caddy caddy hash-password --plaintext 'ADMIN_PASSWORD'

Replace ADMIN_PASSWORD with the new plaintext and put the resulting hash into ADMIN_PASSWORD_HASH in docker-compose.yml. Then open Grafana at http://<host-ip>:3000 and log in with admin / admin. Prometheus is at http://<host-ip>:9090, AlertManager at http://<host-ip>:9093, and the push gateway for batch jobs at http://<host-ip>:9091.

Three dashboards ship with the stack: Docker Host, Docker Containers, and Monitor Services. The last one tracks the monitoring stack itself, including Prometheus container uptime, local storage chunks and series, scrape duration and the Prometheus alerts graph. The containers dashboard deliberately excludes the containers that make up the monitoring stack, so the two views do not overlap.

The fstype edit you have to make before trusting the storage graphs

The dashboards are provisioned from JSON files under grafana/provisioning/dashboards, and their storage queries hard-code a filesystem type. In docker_host.json around line 480 the free-space expression is:

"expr": "sum(node_filesystem_free_bytes{fstype=\"btrfs\"})",

The README notes the author works on BTRFS and had to change aufs to btrfs. If your host reports a different fstype, that panel shows nothing or a misleading number, and the same applies to the Storage Load graph in docker_containers.json around line 406. The README's method for finding the right value is to query Prometheus directly at http://<host-ip>:9090 with node_filesystem_free_bytes, and for the containers dashboard also node_filesystem_size_bytes. This is the single most likely reason a fresh install looks broken while every container is healthy.

Alert rules and reloading them without a restart

Three alert groups live in prometheus/alert.rules: targets for the monitoring services, host for the Docker host, and containers. The targets group fires when an exporter is unreachable, with the README showing:

- alert: monitor_service_down
    expr: up == 0
    for: 30s
    labels:
      severity: critical
    annotations:
      summary: "Monitor service non-operational"
      description: "Service {{ $labels.instance }} is down."

The host group includes high_cpu_load, which triggers when host CPU is under high load for more than 30 seconds. Because Prometheus runs with --web.enable-lifecycle, edited rules can be picked up with a POST rather than a container restart:

curl -X POST http://admin:admin@<host-ip>:9090/-/reload

That URL embeds credentials in the command line, which is convenient on a trusted workstation and a poor habit on a shared machine. AlertManager's own routing configuration lives in ./alertmanager and is mounted read-only into the container; the README does not document where notifications are delivered by default, so treat the receiver setup as something you configure rather than something you inherit.

Where dockprom stops being the right tool

The retention window is the first hard boundary. With --storage.tsdb.retention.time=200h, metrics older than roughly eight days are dropped, and there is no remote write or object storage configured in the Compose file. Capacity planning that needs a quarter of history is out of scope without changing that flag and the storage behind it.

The second boundary is the single-host assumption. NodeExporter and cAdvisor are pinned to the machine running Compose, and the containers dashboard excludes the monitoring stack itself. There is no service discovery for other hosts and no clustering. The related searches people run for this project include Swarmprom, which is the same author's Swarm-oriented variant; if you are on a cluster, that naming is a signal that dockprom is the single-host answer.

The third is operational. A stack that monitors your host is itself a set of containers competing for the same CPU, memory and disk. The Monitor Services dashboard exists precisely because that self-observation matters, but it does not prevent the contention. On a small VPS, the exporters, Prometheus, Grafana, AlertManager and Caddy together are a meaningful share of the machine. And if the host goes down, the alerting goes down with it.

Alternatives and the actual difference

The most direct alternative is to assemble the same components yourself: a Prometheus container, a Grafana container, NodeExporter and cAdvisor, with your own configuration files. The difference is not the software, which is identical, but what you inherit. dockprom gives you three provisioned dashboards, a starter alert rule file, a Caddy basic-auth layer and pinned image tags such as prom/prometheus:v3.10.0 and gcr.io/cadvisor/cadvisor:v0.55.1. Doing it yourself means writing all of that, and also meaning it: your fstype values, your retention, your alert receivers.

A second alternative is a managed monitoring service that runs an agent on the host and stores metrics remotely. That removes the retention ceiling and the host-is-down-so-alerting-is-down problem, at the cost of a subscription and shipping your metrics off the machine. dockprom keeps everything local, which is the reason to choose it and also the reason it cannot alert you about a dead host.

A third is the broader Prometheus ecosystem of exporters and dashboards. dockprom is a curated subset, not a framework. If you need application-level instrumentation, you add it to prometheus/prometheus.yml yourself; the README does not describe that workflow.

Maintenance, licensing, and what upgrading costs

dockprom is MIT licensed, which permits commercial use and modification with the licence and copyright notice retained. That is the licence text in the repository; it is not legal advice, and if you redistribute the stack inside a product you should read LICENSE yourself.

The maintenance model is version pinning. The Compose file names exact tags, and the release history shows the project moving to v9.2.0 on 2026-03-06, with the last push to the repository also on 2026-03-06. Upgrades therefore mean editing image tags and checking whether the provisioned dashboards and alert rules still match the new Prometheus and Grafana versions. The Grafana section of the README already shows a version-specific example with grafana/grafana:7.2.0, while the Compose file in the repository is the authority for what actually runs.

One documented trap: to change the Grafana admin password after first start, you have to remove the grafana_data volume entry, otherwise the change will not take effect. That is a data-loss-shaped operation, since the volume also holds Grafana state. Plan the credentials before the first Compose up rather than after.

Editorial conclusion

Adopt dockprom if you run a small number of Docker hosts, want the whole configuration in your own repository, and are willing to edit the provisioning files. Skip it if you need multi-host discovery, long-term metric storage, or a stack you never touch. Before trusting a dashboard, run node_filesystem_free_bytes in Prometheus and change the fstype in grafana/provisioning/dashboards/docker_host.json and docker_containers.json to the value your host actually reports.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. stefanprodan/dockprom on GitHub