docker-compose-field-guide
UniversalSyntropy/docker-compose-field-guide
A hardened Docker Compose reference for homelabs — best practices, security defaults, recipes, troubleshooting, MCP server for AI agents, and a working quickstart stack.
Instalação
npx convez-ai UniversalSyntropy/docker-compose-field-guide1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Docker Compose Field Guide
A reference for building Docker Compose stacks that are well-structured, security-hardened, and straightforward to maintain. Aimed at homelabs and self-hosted setups.
It serves two readers: people, through the guides and recipes, and AI coding agents, through machine-readable standards (CLAUDE.md, AGENTS.md) and an MCP server that exposes the guide as callable tools. The second part is what sets it apart — your tools follow the same standards you do.
Requires: Docker Engine 24+ with Docker Compose v2 (
docker composeplugin).Scope: Homelab / self-hosted / LAN-facing services. If you're exposing services to the internet, this is a reasonable starting point — but you'll also need a reverse proxy with TLS, rate limiting, and stricter network policies. See the threat model note.
Currency: a reference like this is only as good as its last maintenance pass. Pinned image tags and external links rot — check the latest date in the changelog and verify image pins against the registry before deploying anything from here.
Who this is for
- You run a homelab, NAS, Pi, or small server
- You know basic Linux and have run at least one container before
- You want to do things properly — security, backups, log rotation — without reading the CIS Benchmark end-to-end
- You're tired of Compose files cobbled together from Stack Overflow snippets
What this is not
- A beginner tutorial — if you've never used Docker, start with DOCKER-BASICS.md
- A guide for large-scale production, Kubernetes, or Swarm deployments
- A drop-in solution — you'll need to adapt the template to your services
What's included
- An annotated
docker-compose.ymltemplate — copy it into your project. Includes security defaults, log rotation, resource limits, and healthchecks as a starting baseline. - 21 sections of best practices — from network trust zones and secrets management to USB passthrough and cross-platform gotchas. The WSL2/NTFS warning alone will save you hours.
- A troubleshooting guide — step-by-step debugging playbook, decision tree, and fixes for orphan containers, port conflicts, and data that "disappears" after a recreate.
- A monitoring stack — Prometheus, Grafana, Node Exporter, and cAdvisor. A reference config you'll want to adapt to your setup (Node Exporter gives meaningful host metrics on Linux only).
- Hardened recipes — ready-to-deploy templates for Pi-hole, Nextcloud, and Traefik with security exceptions documented inline.
- Reverse proxy & HTTPS guide — how to put Traefik in front of your services with automatic Let's Encrypt certificates.
- Advanced secrets management — graduating from plain-text secrets to SOPS, Doppler, or git-crypt.
- Helper scripts — safe resets, hard resets, disk reports, and pruning. So you don't have to remember the flags.
- Glossary and index — look up any term, or find where a topic is discussed across the docs.
- Roadmap — where v1.2 is headed: per-service validation, CI boot tests, a blocks catalogue, and a much larger recipe set.
- A quickstart stack — Homepage dashboard + Uptime Kuma, a working two-service demo of every pattern the guide recommends. Deploy it first if you learn by example.
- An MCP server — 11 tools that let AI agents load the standards, fetch recipes, and lint compose YAML on demand. See AGENT-SETUP.md for registration.
- AI agent instructions — for Claude Code, Copilot, Codex, and Cursor, so your coding tools follow the same standards you do.
Worth a look:
| Section | What you get |
|---|---|
| Image trust framework (T1–T5) | A practical model for deciding whether to trust a container image |
| Security exceptions table | How to document why a service breaks the rules — and what compensates |
| CIS Benchmark mapping | Security controls mapped to what a pen tester would flag |
| LLM prompt templates | Copy-paste prompts for getting an LLM to design, review, and debug your stack |
| Cleanup levels (safe → nuclear) | Five levels of Docker cleanup, from project-scoped to "remove everything" |
| Capability cheat sheet | Which Linux capabilities each service type actually needs |
Where to start
| If you want to... | Go here |
|---|---|
| Try a working demo stack first | Quickstart |
| Learn what Docker & Compose are | DOCKER-BASICS.md |
| Set up a new stack properly | Best Practices |
| Deploy a real app (Pi-hole, Nextcloud) | Recipes |
| Add a reverse proxy with HTTPS | Reverse Proxy Guide |
| Encrypt secrets at rest | Secrets Management |
| Fix something that's broken | Troubleshooting |
| Look up a term | Glossary |
| Find where a topic is discussed | Index |
| Copy a ready-made template | docker-compose.yml |
| Add monitoring | monitoring/ |
| Clean up disk space or reset a stack | scripts/ |
| Use this with AI coding agents | Agent Setup |
| Expose field guide tools via MCP | MCP Server |
Quick start
Try the quickstart stack
A ready-to-run stack with a dashboard and monitoring tool that demonstrates every pattern in this guide:
cd quickstart
cp .env.example .env
docker compose up -d
# Dashboard: http://localhost:3000 Monitoring: http://localhost:3001
See quickstart/README.md for setup details.
Use the template in your own project
# 1. Copy the template into your project
cp docker-compose.yml ~/my-project/docker-compose.yml
cp .env.example ~/my-project/.env
# 2. Create secrets (never committed to git)
mkdir -p ~/my-project/secrets
echo -n "your-password" > ~/my-project/secrets/db_password.txt
# 3. Validate before deploying
cd ~/my-project
docker compose config --quiet
# 4. Deploy
docker compose up -d
# 5. Verify
docker compose ps
The template is a starting point, not a drop-in solution. You'll need to swap in your own images, volumes, and secrets. The annotations explain what each block does and why.
Architecture
How a hardened homelab stack fits together — from the user's browser down to isolated containers and read-only volumes:
flowchart TD
User([User / Browser])
User -->|HTTPS 443| Proxy
subgraph docker [Docker Host]
Proxy[Reverse Proxy<br/>Traefik / Caddy]
subgraph frontend [Frontend Network]
App1[App Container<br/>e.g. Nextcloud]
App2[App Container<br/>e.g. Grafana]
end
subgraph backend [Backend Network — no external access]
DB[(Database<br/>Postgres / MariaDB)]
Cache[(Cache<br/>Redis)]
end
subgraph storage [Volumes & Secrets]
Vols[Bind Mounts<br/>read-only where possible]
Secrets["/run/secrets/*<br/>file-based, never in .env"]
end
Proxy -->|HTTP internal| App1
Proxy -->|HTTP internal| App2
App1 --> DB
App1 --> Cache
App2 --> DB
DB --- Vols
DB --- Secrets
App1 --- Vols
end
style Proxy fill:#4a9eff,color:#fff
style DB fill:#e67e22,color:#fff
style Cache fill:#e67e22,color:#fff
style App1 fill:#2ecc71,color:#fff
style App2 fill:#2ecc71,color:#fff
style Secrets fill:#e74c3c,color:#fff
style backend fill:#fff3e0,stroke:#e67e22
style frontend fill:#e8f5e9,stroke:#2ecc71
Each container runs with cap_drop: ALL, no-new-privileges, resource
limits, and log rotation. Networks isolate trust zones — the database is
never reachable from the internet, and secrets are mounted as files, not
passed as environment variables.
What hardening looks like
A naive Compose service vs the same service with this guide's defaults applied:
services:
web:
image: nginx:latest
ports:
- "80:80"
volumes:
- ./html:/usr/share/nginx/html
restart: always
services:
web:
image: nginx:1.27.4 # Pin to exact version
security_opt:
- no-new-privileges:true # Block privilege escalation
cap_drop: [ALL] # Drop all capabilities
cap_add:
- NET_BIND_SERVICE # Only what's needed for port 80
read_only: true # Immutable root filesystem
tmpfs:
- /tmp
- /var/cache/nginx
- /run
ports:
- "80:80"
volumes:
- ./html:/usr/share/nginx/html:ro # Read-only bind mount
mem_limit: 128m # Prevent OOM killing neighbours
cpus: 0.5 # Prevent CPU starvation
pids_limit: 100 # Prevent fork bombs
restart: unless-stopped # Respect manual stops
logging:
driver: json-file
options: { max-size: "10m", max-file: "3" }
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:80/"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
networks:
- frontend
Every directive is explained in the best practices. The annotated template is a copy-paste starting point.
Helper scripts
# Restart a stack without losing data
./scripts/safe-reset.sh [path/to/docker-compose.yml]
# Full teardown + rebuild (WARNING: deletes volumes)
./scripts/hard-reset.sh [path/to/docker-compose.yml]
# See what Docker is using on disk
./scripts/docker-disk-report.sh
# Remove unused resources (stopped containers, dangling images, etc.)
./scripts/prune-unused.sh # Safe mode
./scripts/prune-unused.sh --aggressive # Also removes all unused images + volumes
Best practices — topics covered
Repo structure
├── README.md ← You are here
├── quickstart/
│ ├── README.md ← Try this first — working demo stack
│ ├── docker-compose.yml ← Homepage dashboard + Uptime Kuma monitoring
│ ├── .env.example ← Quickstart environment template
│ └── config/homepage/ ← Dashboard configuration files
├── CONTRIBUTING.md ← How to contribute
├── SECURITY.md ← Security policy
├── CHANGELOG.md ← What changed
├── GITHUB-METADATA.md ← Repo metadata and publication guide
├── LICENSE ← MIT licence
├── CLAUDE.md ← Claude Code project instructions
├── AGENTS.md ← OpenAI Codex agent instructions
├── docker-compose.yml ← Annotated template (copy into your project)
├── .env.example ← Environment variable template
├── Makefile ← Local linting (make lint)
├── recipes/
│ ├── README.md ← Recipe overview and usage
│ ├── pihole.yml ← Pi-hole DNS ad blocker (hardened)
│ ├── nextcloud.yml ← Nextcloud + MariaDB + Redis (hardened)
│ └── traefik.yml ← Traefik v3 reverse proxy with HTTPS
├── docs/
│ ├── BEST-PRACTICES.md ← Best practices (21 sections)
│ ├── DOCKER-BASICS.md ← New to Docker? Start here
│ ├── TROUBLESHOOTING.md ← Gotchas, debugging, cleanup, reset recipes
│ ├── REVERSE-PROXY.md ← Reverse proxy & HTTPS with Traefik
│ ├── SECRETS-MANAGEMENT.md ← Advanced secrets: SOPS, Doppler, git-crypt
│ ├── GLOSSARY.md ← Definitions for every Docker/Compose term
│ ├── INDEX.md ← Find any topic across all files
│ ├── STYLE.md ← Voice and style guide for contributors
│ ├── AGENT-SETUP.md ← Multi-agent skill pack setup guide
│ └── reviews/ ← Review reports
├── mcp-server/
│ ├── README.md ← MCP server setup and registration
│ ├── server.py ← MCP server — exposes tools for AI agents
│ └── requirements.txt ← Python dependency (mcp>=1.2.0)
├── .github/
│ ├── copilot-instructions.md ← GitHub Copilot repo instructions
│ ├── dependabot.yml ← Automated Docker + Actions updates
│ ├── ISSUE_TEMPLATE/ ← Bug report and feature request templates
│ ├── PULL_REQUEST_TEMPLATE.md ← PR checklist
│ └── workflows/validate.yml ← CI: lint, validate, live stack test
├── monitoring/
│ ├── docker-compose.yml ← Prometheus + Grafana + exporters stack
│ └── prometheus/prometheus.yml ← Prometheus scrape config template
└── scripts/
├── safe-reset.sh ← Restart stack without data loss
├── hard-reset.sh ← Full teardown + rebuild (destroys volumes)
├── docker-disk-report.sh ← Show what Docker is using on disk
└── prune-unused.sh ← Remove unused resources (safe or aggressive)
Security approach
This guide follows the CIS Docker Benchmark and OWASP Docker Security Cheat Sheet as baselines. The defaults are:
- Drop all Linux capabilities, add back only what's needed
- Block privilege escalation (
no-new-privileges) - Run as non-root where the image supports it
- Use Docker secrets for passwords (not environment variables)
- Read-only root filesystem where possible
These are safe defaults for a homelab LAN. They reduce your attack surface and catch common mistakes. They are not a complete security architecture — if you're exposing services to the internet, you'll need more (reverse proxy, TLS, WAF, network policies). The security hardening section explains each control, when to relax it, and how to document exceptions.
Trust and limits
This guide is:
- A hardened starting point for homelab and self-hosted stacks
- Based on published standards (CIS Docker Benchmark, OWASP Docker Security)
- Tested with Docker Engine 24+ and Compose v2 on Linux, macOS, and Windows/WSL2
This guide is not:
- A substitute for a security audit
- Validated for internet-facing production without additional controls (reverse proxy, TLS, WAF)
- A guarantee — Docker, Compose, and upstream images change; verify against your environment
- Maintained by a security team — it is a community reference
If you find an error or a gap, open an issue.
Standards
- CIS Docker Benchmark — container isolation, resource limits, capabilities
- OWASP Docker Security Cheat Sheet — secrets, images, networking
- Docker Compose specification — authoritative reference for all directives
Troubleshooting quick fixes
Service can't connect to another service
Likely cause: Using localhost instead of the service name. Inside a Compose network, localhost means the container itself.
Fix: Use the service name as the hostname (e.g., database:5432, not localhost:5432).
Data disappeared after restart
Likely cause: Data was stored in the container filesystem or an anonymous volume, or down -v deleted named volumes.
Fix: Use explicit named volumes or bind mounts for all persistent data. Restore from backup if available.
Port conflict ("address already in use")
Likely cause: Another container or host process is using the port.
Fix:
docker ps --format "table {{.Names}}\t{{.Ports}}"
docker compose down --remove-orphans
docker compose up -d
For the full debugging playbook, decision tree, and more fixes, see TROUBLESHOOTING.md.
Contributing
See CONTRIBUTING.md for how to run checks, what to include in a PR, and what changes are welcome. Voice and style guidelines are in STYLE.md.