convez.ai
MCP Server
UniversalSyntropy

docker-compose-field-guide

UniversalSyntropy/docker-compose-field-guide

Ver no GitHub
BomPluginScore · de 0 a 100

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-guide

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 2 meses
Versão
v1.1.0
Issues abertas
8
Contribuidores
2

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 compose plugin).

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

Worth a look:

SectionWhat you get
Image trust framework (T1–T5)A practical model for deciding whether to trust a container image
Security exceptions tableHow to document why a service breaks the rules — and what compensates
CIS Benchmark mappingSecurity controls mapped to what a pen tester would flag
LLM prompt templatesCopy-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 sheetWhich Linux capabilities each service type actually needs

Where to start

If you want to...Go here
Try a working demo stack firstQuickstart
Learn what Docker & Compose areDOCKER-BASICS.md
Set up a new stack properlyBest Practices
Deploy a real app (Pi-hole, Nextcloud)Recipes
Add a reverse proxy with HTTPSReverse Proxy Guide
Encrypt secrets at restSecrets Management
Fix something that's brokenTroubleshooting
Look up a termGlossary
Find where a topic is discussedIndex
Copy a ready-made templatedocker-compose.yml
Add monitoringmonitoring/
Clean up disk space or reset a stackscripts/
Use this with AI coding agentsAgent Setup
Expose field guide tools via MCPMCP 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

#Topic#Topic
1Compose File Structure12Update Management
2Image Management13Backup & Disaster Recovery
3Security Hardening14Monitoring
4Storage & Volumes15Cross-Platform Compatibility
5Host Filesystem Setup16USB & Hardware Devices
6Environment & Configuration17Penetration Testing Readiness
7Networking18Container Source Verification
8Resource Limits19LLM-Assisted Workflow
9Healthchecks & Dependencies20Checklist for New Services
10Logging21References
11Graceful Shutdown

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


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.

License

MIT

Ver o original no GitHub

Bom para

Relacionados