When you run Docker on a handful of servers, keeping track of what’s running where is manageable. You SSH in, run docker ps, maybe jot something down. Once you pass five or six hosts with dozens of stacks each, that approach falls apart.
We hit this wall internally. Our infrastructure spans multiple servers, each running anywhere from three to over 40 Docker Compose stacks — reverse proxies, monitoring, documentation platforms, Git hosting, n8n and more. When a reverse proxy went down or DNS stopped resolving, the first question was always the same: which server runs that container, and what port is it on?
We got tired of answering that question manually, so we built a tool to do it for us.
What Docker Infrastructure Mapper does
Docker Infrastructure Mapper is a Python CLI that connects to your servers over SSH, discovers every running Docker container, and generates a visual map of your infrastructure. It’s open-source (MIT license) and available as a standalone binary if you don’t want to install Python.
Here’s what it detects:
- Docker Compose stacks and standalone containers — grouped and labeled separately
- Port mappings — which host port maps to which container port, with clickable links
- Container images — the full image name and tag for each container
Output comes in two formats: Mermaid diagrams for platforms that render them natively (GitHub, GitLab, VS Code, Obsidian) and HTML tables with inline CSS for pasting into documentation platforms that don’t support Mermaid (best fit for HUDU - just paste the HTML code as KB source).
Getting started
On first run, the tool walks you through an interactive setup: server hostnames, SSH credentials, and authentication method. You can save the configuration to ~/.infra-mapper/servers.yaml for quick re-runs or you can let the tool build the template for you (which you fill with your setup and rerun the tool).
Authentication
Three methods are supported:
- SSH key — provide the path to your private key (default:
~/.ssh/id_rsa) - Password — prompted at runtime, never written to disk
- SSH agent — delegates authentication to your system’s SSH agent (ssh-agent, 1Password, Pageant)
Example output
Here’s a sanitized example from one of our actual runs, trimmed to two servers. The tool discovered 7 containers across 5 stacks:
graph LR classDef server fill:#b3d9ff,stroke:#01579b,stroke-width:3px,color:#000 classDef stack fill:#ffe0b2,stroke:#e65100,stroke-width:2px,color:#000 classDef container fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000 classDef port fill:#f8bbd0,stroke:#c2185b,stroke-width:1px,color:#000 s1["192.168.1.10"]:::server s1 --> caddy_s["caddy"]:::stack caddy_s --> caddy_c["caddy<br/><small>caddy:latest</small>"]:::container caddy_c --> caddy_p1["80 → 80/tcp"]:::port caddy_c --> caddy_p2["443 → 443/tcp"]:::port s1 --> bs_s["bookstack"]:::stack bs_s --> bs_app["bookstack<br/><small>linuxserver/bookstack</small>"]:::container bs_app --> bs_p["6875 → 80/tcp"]:::port bs_s --> bs_db["mariadb<br/><small>mariadb:latest</small>"]:::container s1 --> uk_s["uptime"]:::stack uk_s --> uk_c["uptime-kuma<br/><small>louislam/uptime-kuma</small>"]:::container uk_c --> uk_p["3001 → 3001/tcp"]:::port s2["192.168.1.20"]:::server s2 --> graf_s["grafana"]:::stack graf_s --> graf_c["grafana<br/><small>grafana/grafana-enterprise</small>"]:::container graf_c --> graf_p["3000 → 3000/tcp"]:::port s2 --> influx_s["influxdb"]:::stack influx_s --> influx_c["influxdb<br/><small>influxdb:2.7</small>"]:::container influx_c --> influx_p["8086 → 8086/tcp"]:::port
The Mermaid output also includes click directives on port nodes, so in renderers that support it (GitHub, Obsidian, VSCode, etc), clicking a port opens the service directly in your browser.
The HTML output (--format html) generates styled tables with inline CSS — no external stylesheets. Explicit foreground and background colors mean it’s readable on both light and dark themes. Port numbers are clickable links. Copy the HTML source and paste it directly into Hudu, BookStack, Confluence, or any WYSIWYG editor.
Here’s what a single stack looks like in the HTML output:
Every color, font, and border is defined inline — no external CSS dependencies. The output renders identically whether your wiki uses a light or dark theme.
Configuration
Server details are stored at ~/.infra-mapper/servers.yaml:
servers:
- hostname: 192.168.1.10
username: admin
auth_method: key
ssh_key_path: /home/admin/.ssh/id_rsa
port: 22
- hostname: 192.168.1.20
username: deploy
auth_method: agent
port: 22Passwords are never saved — servers using password auth prompt each time. Delete the file to start fresh, or use --config /path/to/other.yaml for a different location or, like mentioned above, let the tool generate it for you.
When to use it
- Infrastructure documentation — generate diagrams on demand instead of maintaining them by hand
- Team onboarding — give new engineers a visual map of what runs where on day one
- Security audits — quick overview of exposed ports across all hosts
- Disaster recovery — when DNS or your reverse proxy is down, you need IP:port access to every service
We run it after any significant deployment change and paste the output into our internal wiki. Takes about 30 seconds to scan all servers and produce an up-to-date map.
What’s next
Docker Infrastructure Mapper is open-source on GitHub under the MIT license. Pre-built binaries are on the Releases page.
Below you can find a convenient way to manage compose servers, automate deployments, or dive into Hudu for a documentation platform.
Managing Docker Across Multiple Servers with Komodo
Deploy Komodo Core with Docker Compose and install Periphery agents on remote servers to manage Docker containers, stacks, and builds from a single dashboard.
Automating Docker with Komodo — Builds, Syncs, and Procedures
Use Komodo's Resource Syncs for GitOps, Procedures for automated workflows, Builds for CI/CD pipelines, and the CLI for headless Docker management.
Self-Hosting Hudu with Docker & Cloudflare Tunnel
A practical guide to installing Hudu with Docker Compose, maintaining it over time, and securely publishing it via Cloudflare Tunnel.