Docker homelab

A modular collection of Docker Compose stacks for a self-hosted homelab. Each stack is independently deployable and documents its own configuration, dependencies, storage, networking, and upgrade notes.

New here? Follow Getting started. It covers host prerequisites, local configuration, shared resources, deployment, and verification without assuming that every stack should be installed.

.
├── stacks/<name>/     # One independently documented application or service
├── portainer/         # Portainer CE, maintained outside the main stack catalog
├── documents/         # Cross-stack architecture and operations guides
├── scripts/           # Validation, preparation, and maintenance helpers
├── shared.env.example # Optional host-wide timezone and locale template
└── Makefile           # Common validation and maintenance commands

A typical stack contains:

Some stacks need additional example configuration or generated upstream files. The stack README is authoritative when its layout differs from this pattern.

1. Pick a service from the stack catalog.

2. Read that stack's README completely.

3. Run its prepare-stack.sh if present, or copy only the example files named by its README.

4. Replace placeholders and generate unique secrets in ignored local files.

5. Validate and deploy from the stack directory:

   docker compose config --quiet
   docker compose pull
   docker compose up -d
   docker compose ps

Do not assume one stack's environment variables, networks, or commands apply to another. Stack-specific instructions deliberately live beside the Compose file so they can evolve together.

Stacks remain separate but may opt into shared infrastructure:

• Caddy provides HTTP(S) ingress on trust-specific ingress-* networks.
• telemetry connects monitoring and logging services.
• Dedicated networks connect mail, AI, DNS, media, and download services.
• Named volumes and bind mounts persist application data outside containers.
• shared.env can provide common timezone and locale values.

Create only the resources required by the stacks you select. See Shared resources for the network model, storage cautions, and one-time setup, or view the generated topology for service relationships.

Committed *.example files are templates. Local files such as stack.env, .env, live Caddy snippets, private keys, and application configuration are ignored where appropriate and must not be committed.

Before deploying:

• inspect mounts and confirm remote storage is actually mounted;
• replace example domains, paths, credentials, and secret placeholders;
• use unique secrets for every application;
• check the stack README for required external networks and volumes;
• run make doctor and make validate from the repository root.

See Environment variables for shared conventions and secret-generation patterns. A stack's own README and stack.env.example remain the source of truth for its variables.

Useful read-only checks:

make doctor
make validate

Before contributing:

make hooks-install
make ci-local

The scripts reference explains the available helpers. Contributor conventions, generated documentation, and validation requirements are covered in CONTRIBUTING.md.

These stacks can expose privileged services and personal data. Review published ports, proxy routes, authentication, volume permissions, and image sources before deployment. Back up persistent data before upgrades, and avoid docker compose down -v during routine maintenance because it removes named volumes.

To report a vulnerability in the repository, see the security policy.