Docker Compose files start simple — a web server, a database, maybe a cache. Then requirements grow. You add a message queue, a worker service, a monitoring stack, a reverse proxy. Before you know it, your docker-compose.yml is 200 lines long and nobody on the team can explain how all the services connect.
This article covers practical ways to visualize your Docker Compose setup so you can understand, document, and communicate your container architecture.
Why visualize Docker Compose?
A docker-compose.yml file defines services, networks, volumes, and dependencies — but it does so in a flat YAML structure that doesn't visually convey how things connect. When someone new joins the team and asks "how do these containers talk to each other?", reading 200 lines of YAML isn't the answer.
Diagrams help in three specific situations. During onboarding, a new developer can look at a diagram and understand the service topology in 30 seconds. During debugging, when a service can't connect to another, a diagram shows you which network they're on and what sits between them. During architecture reviews, when you're discussing whether to split a monolith service or add a new dependency, a visual representation makes the conversation concrete.
Example: a typical web application
Let's start with a real-world example — a web application with a React frontend, a Python API, PostgreSQL, Redis, and Nginx as a reverse proxy.
version: "3.8"
services:
nginx:
image: nginx:alpine
ports:
- "80:80"
depends_on:
- frontend
- api
frontend:
build: ./frontend
depends_on:
- api
api:
build: ./api
depends_on:
- postgres
- redis
environment:
DATABASE_URL: postgresql://app:secret@postgres/appdb
postgres:
image: postgres:16
volumes:
- pgdata:/var/lib/postgresql/data
redis:
image: redis:7-alpine
worker:
build: ./worker
depends_on:
- redis
- postgres
volumes:
pgdata:
Reading this YAML, you can piece together the architecture — Nginx sits in front of everything, the frontend talks to the API, the API uses PostgreSQL and Redis, and a worker also connects to both data stores. But it takes a few minutes of careful reading to build that mental model.
Method 1: Use InfraSketch
The quickest approach is to paste your Docker Compose YAML directly into InfraSketch. Select the "Docker Compose" tab, paste your YAML, and click "Generate Diagram." The tool parses service definitions and generates a visual diagram showing each container and its connections.
This takes about 5 seconds and gives you a diagram you can export as PNG or SVG for your project README or documentation. The current version detects services from the YAML structure and shows them as container nodes.
Method 2: docker-compose-viz
The docker-compose-viz tool is a CLI that reads your compose file and generates a graph using Graphviz. It's available as a Docker container itself, which is convenient.
docker run --rm -it \ --name dcv \ -v $(pwd):/input:ro \ pmsipilot/docker-compose-viz \ render -m image docker-compose.yml
This produces a dependency graph showing which services depend on which. It's more detailed than a simple service list because it visualizes the depends_on relationships, links, and shared networks.
The output is functional but not pretty — it uses default Graphviz styling, which means tiny text and cramped layouts for complex setups. For a quick check of your dependency chain, it works. For documentation, you'll want something more polished.
Method 3: Mermaid.js in your README
If you want a diagram that lives in your README and renders automatically on GitHub, Mermaid is a great option. You define the diagram using a simple text syntax that GitHub renders as an image.
```mermaid
graph TB
Client[Browser] --> Nginx
Nginx --> Frontend[React App]
Nginx --> API[Python API]
API --> Postgres[(PostgreSQL)]
API --> Redis[(Redis)]
Worker --> Postgres
Worker --> Redis
```
This renders as a clean flowchart directly in your GitHub README. The advantage is that the diagram is version-controlled alongside your code. When you add a new service, you update the Mermaid block in the same PR.
The limitation is manual maintenance — you need to keep the Mermaid diagram in sync with your actual docker-compose.yml. It's also limited to simple box-and-arrow diagrams without service-specific icons.
Method 4: Draw it manually (when you need polish)
For presentations, documentation sites, or client deliverables, sometimes you need a hand-crafted diagram. Tools like Draw.io, Excalidraw, or Figma give you full control over layout, styling, and annotations.
The key to making manual Docker diagrams useful is to include the right details: service names, exposed ports, volume mounts, and network boundaries. A diagram that just shows boxes with service names isn't much more useful than reading the YAML. A diagram that shows "Nginx (port 80) routes /api/* to API service (port 8000) on backend network" tells a real story.
Best practices for container architecture diagrams
Regardless of which tool you use, effective Docker Compose diagrams share a few characteristics.
First, show network boundaries. If your compose file defines multiple networks (frontend, backend, monitoring), group services by network. This immediately clarifies which services can communicate with each other.
Second, indicate data persistence. Services with volumes are stateful — they hold data that matters. Highlight databases and any service with persistent volumes differently from stateless application containers.
Third, show external access points. Which ports are exposed to the host? Which services are accessible from outside? This is critical for security reviews and debugging network issues.
Fourth, label the connections. Don't just draw arrows — label them with protocol and port. "HTTP :8000" is more useful than a plain line between two boxes.
Advanced Docker Compose patterns that trip up visualizers
Real-world compose files have patterns beyond simple depends_on chains. Here's how to handle the common ones:
Multi-file compose. Production deployments often use multiple compose files — a base docker-compose.yml and an override file for environment-specific settings. docker compose -f docker-compose.yml -f docker-compose.prod.yml config merges them and outputs the combined YAML. Pipe that merged output into InfraSketch for a complete picture of what actually runs in production.
Profiles. Docker Compose supports profiles to activate optional services. Your monitoring stack (Prometheus, Grafana, cAdvisor) might be behind a monitoring profile that doesn't start by default. When diagramming, run docker compose --profile monitoring config to include profiled services in the output, then paste the full config.
Extend and merge. Services using extends inherit from a base service definition. Auto-generated diagrams may not resolve these correctly. The safest approach is again to use docker compose config to get the fully resolved YAML before pasting it into any visualization tool.
# Get fully resolved compose config (merges files, resolves extends, applies env) docker compose config # With profiles docker compose --profile monitoring --profile debug config # Pipe to clipboard (macOS) docker compose config | pbcopy
Network topology: what diagrams often miss
The most important thing a Docker Compose diagram can show — and the thing most tools skip — is network isolation. Docker creates separate virtual networks, and containers on different networks can't communicate by default. Getting this right matters for security.
Consider a three-tier architecture:
services:
nginx:
networks: [frontend]
ports: ["80:80"]
api:
networks: [frontend, backend]
postgres:
networks: [backend]
redis:
networks: [backend]
networks:
frontend:
backend:
internal: true # cannot reach the internet
The backend network here is marked internal: true, which means containers on it have no internet access — they can only communicate with each other. Nginx lives only on the frontend network so it can't reach the database directly. The API bridges both networks and is the only path between them. This is a meaningful security boundary that a flat box-and-arrow diagram won't show unless it groups containers by network.
When diagramming this kind of setup, represent each network as a distinct zone and place containers inside the zones they belong to. Services on multiple networks should visually span zones or appear in a "bridging" position between them.
From Docker Compose to Kubernetes: how diagrams help migration
Many teams start with Docker Compose for local development and smaller deployments, then migrate to Kubernetes as they scale. Diagrams are genuinely useful during this transition because they help you map Compose concepts to Kubernetes equivalents.
In a Compose-to-Kubernetes migration, each service typically becomes a Kubernetes Deployment (or StatefulSet for databases). Each network becomes a Kubernetes Namespace or a set of NetworkPolicy rules. Ports exposed to the host become Services of type NodePort or LoadBalancer. Volumes become PersistentVolumeClaims.
Having a clear diagram of your Compose architecture before starting migration helps you ask the right questions: Which services need persistent storage? Which need public internet access? Which should be isolated from others? Which have hard startup dependencies that need initContainers in Kubernetes?
InfraSketch supports both Docker Compose and Kubernetes YAML. You can diagram your existing Compose setup, plan the migration on paper, then diagram the resulting Kubernetes manifests to verify the topology is equivalent.
Keeping diagrams in sync with your compose file
The biggest problem with any infrastructure diagram is drift. You update the compose file, forget to update the diagram, and two months later the documentation is wrong. Here are three approaches to keeping them synchronized:
Commit-time generation. Add diagram generation to your pre-commit hook or CI pipeline. When any docker-compose*.yml file changes, re-generate the diagram automatically. The InfraSketch CLI (npx infrasketch docker-compose.yml) generates a shareable URL in CI without opening a browser — you can post this link to a PR comment or Slack channel.
Embed in README. Use the InfraSketch <infra-sketch> web component to embed a live diagram in your documentation site. Point it at the raw GitHub URL of your docker-compose.yml. The diagram re-renders from the latest file on every page load — no manual updates needed.
<!-- Embed a live diagram that always reflects the current compose file --> <script src="https://infrasketch.cloud/embed.js"></script> <infra-sketch src="https://raw.githubusercontent.com/myorg/myrepo/main/docker-compose.yml" height="480" ></infra-sketch>
PR-level diagrams. If you use GitHub, the InfraSketch GitHub Action automatically posts a diagram comment on any PR that modifies a compose file. Reviewers see the architecture diagram inline without needing to run anything.
Frequently asked questions
Does InfraSketch support docker-compose.override.yml?
Paste the merged output from docker compose config rather than the individual files. That gives InfraSketch the fully resolved service definitions with overrides applied, which produces a more accurate diagram than pasting just the base file.
What about Docker Swarm configs?
Docker Swarm deploy keys (replicas, placement, resources) are parsed but not visualized separately — all replicas of a service appear as a single node. For diagrams with replica counts, add those annotations manually to the exported SVG in a drawing tool.
Can I diagram a running compose stack instead of the YAML file?
docker compose config reflects what's in your files, not what's currently running. If you want a diagram of what's actually running, docker compose ps --format json gives you the current state, but parsing that into a topology diagram requires manual work. The YAML-based approach is faster for most use cases.
My compose file uses environment variable substitution — will it work?
Run docker compose config first (with your .env file present) to resolve all substitutions. The output will have concrete values. Paste that resolved output into InfraSketch for accurate results.
Keep it simple
The best Docker Compose diagram is one that actually gets created and maintained. A rough auto-generated diagram that you update by re-running a tool is infinitely more valuable than a beautiful hand-drawn diagram from three months ago that no longer reflects reality.
Start with InfraSketch or Mermaid for a quick visualization. If you need more polish, refine it manually. The goal is understanding, not art.
Visualize your Docker Compose
Paste your docker-compose.yml and see your container architecture instantly. Now with an interactive drag-and-drop editor.
Open InfraSketch