As my Docker setup grew, docker ps and Compose files stopped giving me the full picture.
I could see which containers were running, but I could not quickly answer the questions I actually cared about:
- which containers are attached to which networks
- what depends on what
- where volumes are mounted
- what belongs to which Compose project
- what changed after something restarted
- which services are defined but not running yet
I wanted a simple way to see the topology of a Docker host, not just list containers.
So I built DockGraph.
Links: GitHub · Website · Docker image
What DockGraph does
DockGraph connects to the Docker socket and builds a live, interactive view of your Docker infrastructure.
It shows containers, networks, volumes, and their relationships as a graph that updates as your setup changes. Containers are grouped by network, depends_on relationships appear as edges, and named volumes are linked to the containers that mount them.
The goal is not to replace the Docker CLI. The goal is to make the structure of a Docker setup easier to understand at a glance.
The main views
DockGraph currently has three main ways to inspect your setup.
1. Topology graph
This is the main view.
It shows your Docker infrastructure as an interactive graph:
- containers
- networks
- volumes
- dependencies
- volume mounts
- multi-network connections
You can click nodes and edges to highlight related resources and fade unrelated ones, which makes larger setups easier to inspect.
2. Table view
Graphs are useful, but sometimes a table is faster.
The table view gives a more structured overview with sortable columns and grouping by things like Compose project, network and status.
3. Dashboard view
There is also a dashboard with resource charts, top consumers, event timeline, alerts, disk usage, image information, and Compose project overview.
This is useful when you want a broader health/status view instead of only the topology.
Logs without losing the map
One thing I wanted was to inspect logs without constantly jumping between terminal windows.
DockGraph has a global log view that aggregates container logs into one time-ordered stream. You can filter by text, regex, or container, and follow events across multiple services.
You can also open logs for a specific container in a floating pop-out window. These windows can be moved, resized, minimized, searched, and grouped into tabs.
That makes it easier to keep the topology visible while still digging into what one service is doing.
Compose-aware, even before services start
A feature I personally find useful is that DockGraph can parse Compose files, not just running Docker resources.
If you mount a Compose file or a directory containing Compose files, DockGraph can show services that are defined but not currently running.
That means the graph can represent both:
- what is running now
- what is defined in your Compose setup
For example, you can mount a single file:
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- ./compose.yml:/compose/compose.yml:ro
Or mount a directory of stacks:
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- ./stacks:/compose/stacks:ro
DockGraph will auto-detect Compose files from mounted volumes. You can also override that with DG_COMPOSE_PATH if you want to scan only specific files or directories.
Try it
The simplest way to run it is as a single container:
docker run -d \
-p 7800:7800 \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
--label dockgraph.self=true \
dockgraph/dockgraph
Then open:
http://localhost:7800
The dockgraph.self=true label tells DockGraph to hide its own container from the graph.
Docker Compose example
You can also add it to an existing Compose stack:
services:
dockgraph:
image: dockgraph/dockgraph:latest
ports:
- "7800:7800"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- ./compose.yml:/compose/compose.yml:ro
labels:
dockgraph.self: "true"
The Compose file mount is optional, but it enables DockGraph to show services before they are running.
Security notes
DockGraph needs access to the Docker socket so it can read container, network, and volume state.
The socket is mounted read-only in the examples above, and DockGraph itself only observes Docker resources. It does not start, stop, or modify containers.
That said, Docker socket access is still sensitive. If you expose DockGraph outside a trusted local environment, you should put it behind proper protection.
DockGraph supports optional password protection with DG_PASSWORD:
environment:
DG_PASSWORD: "your-secure-password"
You can also bind it to localhost:
environment:
DG_BIND_ADDR: "127.0.0.1"
Environment values with credential-like keys such as PASSWORD, SECRET, KEY, TOKEN, and AUTH are masked before being sent to the browser.
If exposing it beyond a local machine or trusted network, use a reverse proxy such as Caddy, nginx, or Traefik for HTTPS.
Implementation
DockGraph is built as a single Go binary with the frontend embedded.
The production image is distroless, and the app does not need a database or any extra services to run.
Under the hood, it has two collectors:
- a Docker collector that reads Docker state and watches the event stream
- a Compose collector that detects and parses mounted Compose files
The frontend receives the unified graph over WebSocket and renders the topology interactively.
Current state
DockGraph is still early, and I do not consider it fully stable yet.
But it has already been useful for understanding my own Docker setup, especially when several Compose stacks, networks, and volumes are involved.
I would love feedback from people running Docker at home, in homelabs, or on small servers.
What would make a Docker topology view more useful for you?
GitHub: https://github.com/dockgraph/dockgraph
Website: https://dockgraph.dev
License note
DockGraph is currently under the Business Source License 1.1.
You can use, modify, and redistribute it, including in production. The main restriction is offering it as a hosted service or embedding it as a feature in a commercial product. Each version converts to Apache License 2.0 four years after release.
Top comments (3)
It's funny that I am currently learning Docker. Will check it out! Good work Artem! :D
Haha, that’s a lovely coincidence 😄
Thanks a lot, Francis! I really appreciate you taking the time to check out the article. Wishing you the best with your learning, hope it goes smoothly and you get plenty of those nice “aha” moments along the way!
Wow