composegraph

README

composegraph

Render a docker-compose.yml service dependency graph to SVG — in pure Go, via go-mermaid. No headless browser, no Node.js, no Graphviz. Just a library and a single static binary.

Why

docker-compose.yml encodes a real dependency graph (depends_on, networks, volumes_from) that's easy to lose track of once a stack grows past a handful of services. composegraph turns it into a picture, without shelling out to anything.

Install

Library:

go get github.com/zkrebbekx/composegraph

CLI:

go install github.com/zkrebbekx/composegraph/cmd/composegraph@latest

Homebrew:

brew install zkrebbekx/tap/composegraph

Docker:

docker run -i --rm -v "$PWD":/work ghcr.io/zkrebbekx/composegraph /work/docker-compose.yml > graph.svg

Prebuilt binaries for Linux/macOS/Windows (amd64/arm64) are attached to each GitHub release.

Usage

composegraph docker-compose.yml > graph.svg
composegraph -format mmd -o graph.mmd docker-compose.yml   # raw Mermaid source
composegraph -format png -scale 2 -o graph.png docker-compose.yml
composegraph a/docker-compose.yml b/docker-compose.yml     # batch: writes a.svg, b.svg
echo "$(cat docker-compose.yml)" | composegraph > graph.svg

Library:

package main

import (
	"os"

	"github.com/zkrebbekx/composegraph"
)

func main() {
	src, _ := os.ReadFile("docker-compose.yml")
	svg, err := composegraph.Render(src)
	if err != nil {
		panic(err)
	}
	os.WriteFile("graph.svg", svg, 0o644)
}

Render accepts the same functional options as go-mermaid.Render (theme, spacing, ...): composegraph.Render(src, mermaid.WithTheme(mermaid.Dark)).

Need just the Mermaid source (e.g. to paste into another tool)? composegraph.ToMermaid(src) returns the flowchart text without rendering it.

How it maps

compose	diagram
each service	a node — stadium-shaped (([name])) if it has a healthcheck, rectangle otherwise
depends_on	a directed edge; a non-default condition (service_healthy, service_completed_successfully) becomes an edge label
volumes_from	a directed edge labeled volumes
networks	services sharing a network are grouped into a subgraph titled after it (a service in several networks is grouped under the first, alphabetically)

If the compose file never uses networks: at all, the diagram is left flat (no subgraphs) — there'd be nothing to cluster by.

Roadmap

• docker-compose.yml: services, depends_on, networks, volumes_from
• SVG / Mermaid source / PNG output, batch mode, stdin
• Distribution: prebuilt binaries, Homebrew cask, ghcr.io Docker image
• Kubernetes manifests: Deployment/Service/Ingress/StatefulSet, edges from ownerReferences and Service-selector → Deployment-label matching, Ingress → Service → Deployment chains
• docker-compose.override.yml multi-file merge

Develop

make test
make lint
make build

License

MIT

Documentation

Overview

Package composegraph renders a docker-compose file's service dependency graph as a Mermaid flowchart, then hands that off to go-mermaid for SVG/PNG rendering — no headless browser, no Node, no Graphviz.

svg, err := composegraph.Render(composeYAML)

Nodes are services; edges come from `depends_on` (labeled with any non-default condition) and `volumes_from`. Services sharing a `networks:` entry are grouped into a subgraph, so the diagram clusters visually by network.

Index

• func Render(src []byte, opts ...mermaid.Option) ([]byte, error)
• func ToMermaid(src []byte) (string, error)
• type Edge
• type EdgeKind
• type Graph
• type Node

Functions

func Render

func Render(src []byte, opts ...mermaid.Option) ([]byte, error)

Render parses a docker-compose YAML document and renders its dependency graph straight to SVG via go-mermaid. opts are passed through to mermaid.Render (theme, padding, spacing, ...).

func ToMermaid

func ToMermaid(src []byte) (string, error)

ToMermaid parses a docker-compose YAML document and returns the equivalent Mermaid flowchart source.

Types

type Edge

type Edge struct {
	From, To string
	Kind     EdgeKind
	// Label is shown on the edge; empty for a plain dependency.
	Label string
}

Edge is a directed relationship between two services.

type EdgeKind

type EdgeKind int

EdgeKind distinguishes the compose relationship an Edge represents.

const (
	// DependsOn is a `depends_on` relationship.
	DependsOn EdgeKind = iota
	// VolumesFrom is a `volumes_from` relationship.
	VolumesFrom
)

type Graph

type Graph struct {
	Nodes []Node
	Edges []Edge
}

Graph is the dependency graph extracted from a compose file. Nodes and Edges are sorted for deterministic output.

type Node

type Node struct {
	// Name is the service name (the map key under `services:`).
	Name string
	// Group is the subgraph this node is clustered under (its first network,
	// alphabetically, or "default" if it declares none). Empty when the
	// compose file uses no `networks:` keys at all, so no grouping applies.
	Group string
	// HasHealthCheck reports whether the service declares a healthcheck.
	HasHealthCheck bool
}

Node is one service in the compose file.