Docker Swarm Visualizer: A Read-Only Map of Your Swarm, With Caveats

What It Solves and Who It Is For

Docker Swarm Visualizer addresses a narrow problem: showing what is running on a Docker swarm mode cluster in a single diagram. It is not a metrics dashboard, not a log viewer, and not a management console. It draws nodes as circles and tasks as smaller circles attached to them, updating live as services start, stop, or fail. The intended audience is people learning Docker swarm mode, or developers who want a quick visual confirmation that their services are distributed as expected. The README is explicit: this is a sample app meant for learning Docker. It was originally built for the 2015 DockerCon EU keynote and adapted for the 2016 DockerCon US keynote. That origin explains both its simplicity and its limitations.

How It Works: Remote API Polling and D3 Rendering

The visualizer connects to a Docker daemon through the Docker Remote API. It reads the state of the swarm, including nodes and tasks, and renders that state as a D3 diagram in the browser. The README describes the data flow in behavioral terms: each node shows all tasks running on it. When a service goes down, it is removed from the diagram. When a node goes down, the circle at the top turns red, and the tasks are removed. The node itself stays visible, presumably to indicate that the node exists but is unhealthy. The README also notes that the Remote API can occasionally return incomplete data, such as a node missing its name. The visualizer handles this by waiting for the next poll and updating the name when it arrives. That is a pragmatic approach, but it means the diagram can briefly show incomplete information.

Running It: The One-Line Container Command

The simplest way to run it is a single docker run command that mounts the Docker socket. The README gives: docker run -it -d -p 8080:8080 -v /var/run/docker.sock:/var/run/docker.sock dockersamples/visualizer. If port 8080 is taken, you can map a different host port, for example -p 5000:8080. For running behind a load balancer, you can set the context root with an environment variable: -e CTX_ROOT=/visualizer. To run it as a service in a swarm, the README provides a docker service create command with a constraint that it runs on a manager node, since only managers have access to the swarm's control plane: --constraint=node.role==manager. That is the entire setup. No configuration file, no API keys, no database. The container itself does the work.

The Security Problem Is Not Hidden

The README states plainly: "Running this app in production is insecure and should be avoided." That is not a minor caveat. The container mounts /var/run/docker.sock into the container, which gives the container full control over the Docker daemon. Any vulnerability in the visualizer, or any way an attacker can reach the container's HTTP interface, becomes a path to root on the host. The README's only advice is to protect the Docker daemon socket with SSL, referencing Docker's official documentation on that topic. But even with SSL, the visualizer is a read-only tool that exposes swarm state over HTTP. If you expose it beyond localhost, you are giving anyone who can reach it a live map of your cluster. For a learning environment, that is fine. For anything else, it is a serious risk. This is a case where the project's own documentation is more honest than many production tools.

Architecture Coverage and Custom Builds

The main image, dockersamples/visualizer, supports linux/amd64 only. That is a real constraint if you run ARM-based nodes, which is common for Raspberry Pi clusters. The README points to a third-party image, alexellis2/visualizer-arm:latest, for ARMv6 or ARMv7 devices. For Windows, there is a separate Dockerfile.windows and an image by stefanscherer/visualizer-windows:latest. Windows has an extra complication: you cannot bind-mount the named pipe, so the Docker engine must listen on a TCP port, and you set the DOCKER_HOST environment variable. The README gives a PowerShell snippet to find the correct IP address. If your architecture is not covered, you can build a custom image from source using docker build -t visualizer-custom:latest. The README says the base image node:8-alpine supports amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, and s390x. That gives you a path, but it means you are responsible for maintaining the image yourself.

Limitations: Stale Data, CSS, and Missing Tests

The README's TODO list is unusually candid. It includes taking out or fixing how dist works, commenting more extensively, creating tests and making them work better, and making the CSS more elastic. That last item is telling: the README says the CSS is "currently optimized for 3 nodes on a big screen." So if you have more than three nodes, or a small screen, the diagram may not display well. The stale-data issue is also worth noting: the visualizer polls the Remote API, and the README says incomplete data can appear temporarily. There is no indication of how often it polls, and no way to configure the interval. For a demo, that is acceptable. For a monitoring tool, you would want control over the refresh rate and a way to handle partial data gracefully.

Maintenance and Upgrade Cost

The repository has no recent releases listed, and the last push date is unknown from the material. The README mentions community contributions, but the project appears to be in maintenance mode rather than active development. The base image is node:8-alpine, which is old. Node 8 reached end-of-life years ago, so the container likely contains unpatched dependencies. If you use the pre-built image, you are inheriting that risk. If you build your own, you can update the base image, but you are then maintaining a fork. The license is Apache-2.0, which permits modification and redistribution, so forking is legally straightforward. But the cost is yours: you will need to update the Dockerfile, test the image, and track upstream changes. The README's TODO list suggests that even the original authors consider the project unfinished.

Alternatives: What Else Can You Use?

The obvious alternative is the Docker CLI itself. Commands like docker service ls and docker node ps give you the same information in text form, without exposing the Docker socket to a web service. That is the safest and most direct way to inspect swarm state. Another alternative is a general-purpose monitoring tool like Prometheus with the Docker exporter, which scrapes the Docker API over a secure connection and stores metrics. That approach gives you historical data, alerting, and a dashboard, but it is far more complex to set up. The visualizer's advantage is that it is a single command and gives you a live, spatial view. The alternative's advantage is that it does not require mounting the Docker socket into a web server. If you only need to see what is running, the CLI is hard to beat. If you need a visual for a presentation or a learning exercise, the visualizer is fine.

Editorial conclusion

Adopt Docker Swarm Visualizer if you are learning swarm mode or need a quick, read-only visual check on a test cluster. Do not use it in production: the README explicitly warns that running it in production is insecure and should be avoided. Before adopting, verify that you can protect the Docker daemon socket with SSL, as the README directs, and confirm that your architecture (linux/amd64, armhf, or Windows) has a pre-built image or that you can build one. If you need production-grade monitoring, look elsewhere.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. README
4. Releases