🏠 Homelab Docker Documentation Handbook

Generated: 2026-07-23 · Timezone: Australia/Sydney
Purpose: Comprehensive reference for maintaining, troubleshooting, and rebuilding all Docker Compose services.

---

📁 Repository Layout

Docker/
├── Cloud/
│   ├── Gaius/          ← Cloud VPS #1 (Gaius)
│   │   ├── adguard/    ← AdGuard DNS instance #2
│   │   └── tools/      ← Dockflare agent
│   └── Starbuck/       ← Cloud VPS #2 (Starbuck)
│       ├── adguard/    ← AdGuard DNS instances #1 + Sync
│       ├── authentik/  ← SSO / Identity Provider
│       ├── pangolin/   ← Tunnelled reverse proxy
│       ├── services/   ← Apprise, Gatus, Uptime Kuma
│       ├── tools/      ← Dockflare agent
│       └── traefik/    ← Cloud-facing Traefik
└── Homelab/
    ├── ARR-Stack/      ← Media automation (*arr suite)
    ├── Bluesky/        ← Self-hosted Bluesky PDS
    ├── ColonialOne/    ← Glances system monitor
    ├── DockFlare/      ← Cloudflare Tunnel manager
    ├── Docker/         ← Core homelab service stacks
    │   ├── health/     ← Fitbit & ResMed health exporters
    │   ├── librarrarian/ ← Media transcoding dashboard
    │   ├── linkwarden/ ← Bookmark manager
    │   ├── obsidian/   ← Obsidian + CouchDB LiveSync
    │   ├── private/    ← Private static sites
    │   ├── prometheus/ ← Prometheus + all exporters
    │   ├── reitti/     ← Location/route tracking
    │   ├── scanopy/    ← Container vulnerability scanner
    │   ├── services/   ← Main services megastack
    │   ├── tools/      ← Newt, socket-proxy, traefik-kop
    │   └── velld/      ← Database backup manager
    ├── Forgejo/        ← Self-hosted Git server + CI runner
    ├── Immich/         ← Photo library & ML
    ├── Media/
    │   ├── services/   ← Media companion apps
    │   └── tools/      ← RouteGhost, traefik-kop
    ├── Traefik/        ← Homelab reverse proxy (primary)
    ├── VPNnet/         ← WireGuard VPN + Tailscale exit node
    └── komodo-tools/   ← Komodo socket proxy

---

📄 Stack Documentation Index

Stack	Host	Doc Link
AdGuard (Gaius)	Cloud – Gaius VPS	adguard-gaius.md
AdGuard (Starbuck)	Cloud – Starbuck VPS	adguard-starbuck.md
Authentik	Cloud – Starbuck VPS	authentik.md
Pangolin	Cloud – Starbuck VPS	pangolin.md
Starbuck Services	Cloud – Starbuck VPS	starbuck-services.md
Starbuck/Gaius Tools	Cloud – Both VPS	cloud-tools.md
Starbuck Traefik	Cloud – Starbuck VPS	starbuck-traefik.md
ARR-Stack	Homelab	arr-stack.md
Bluesky PDS	Homelab	bluesky.md
ColonialOne	Homelab	colonialone.md
DockFlare	Homelab	dockflare.md
Forgejo	Homelab	forgejo.md
Health Exporters	Homelab	health.md
Immich	Homelab	immich.md
Librarrarian	Homelab	librarrarian.md
Linkwarden	Homelab	linkwarden.md
Media Services	Homelab	media-services.md
Media Tools	Homelab	media-tools.md
Obsidian	Homelab	obsidian.md
Prometheus Stack	Homelab	prometheus.md
qBittorrent	Homelab	qbittorrent.md
Reitti	Homelab	reitti.md
Scanopy	Homelab	scanopy.md
Services (Megastack)	Homelab	services.md
Tools	Homelab	tools.md
Traefik (Homelab)	Homelab	traefik.md
Velld	Homelab	velld.md
VPNnet	Homelab	vpnnet.md
komodo-tools	Homelab	komodo-tools.md

---

🌐 Shared External Networks

These Docker networks must be created before bringing up stacks that reference them as external: true.

docker network create traefik
docker network create database
docker network create internal
docker network create apps
docker network create backend
docker network create cloudflare-net
docker network create vpn-net
docker network create gatus-net

Tip: Run docker network ls to check which already exist.

---

🔑 Key Conventions

Convention	Description
PUID=1027 / PGID=100	Standard unprivileged user/group across all media services
TZ=Australia/Sydney	Global timezone for all containers
backup=media / backup=services	Docker labels used by backup tooling to tag containers
read_only: true + tmpfs	Hardened containers using 11notes images
traefik-kop	Syncs Traefik labels from remote hosts via Redis
dockflare	Manages Cloudflare Tunnel routes from Docker labels
.env files	Secrets are stored in .env alongside each compose.yaml

---

🚀 Cloudflare Pages Deployment via Forgejo

This documentation can be automatically published as a static site on Cloudflare Pages using Forgejo Actions.

How It Works

Push to Forgejo  →  Forgejo Actions runner  →  Build (optional)  →  Cloudflare Pages deploy

Setup Steps

1. Create a Cloudflare Pages Project

1. Go to Cloudflare Dashboard → Workers & Pages → Create Application → Pages
2. Choose Direct Upload (Wrangler CLI deploys from CI)
3. Name your project e.g. homelab-docs

2. Get Cloudflare Credentials

Item	Where to find it
Account ID	Right sidebar of the Cloudflare dashboard
API Token	My Profile → API Tokens → Create Token → use Edit Cloudflare Workers template + add Pages permissions

3. Add Secrets to Forgejo

In your Forgejo repo: Settings → Secrets → Actions

Secret Name	Value
CLOUDFLARE_API_TOKEN	Your Cloudflare API token
CLOUDFLARE_ACCOUNT_ID	Your Cloudflare account ID

4. Create the Forgejo Actions Workflow

Create .forgejo/workflows/deploy-docs.yml:

name: Deploy Docs to Cloudflare Pages

on:
  push:
    branches:
      - main
    paths:
      - 'Documentation/**'

jobs:
  deploy:
    runs-on: docker
    container:
      image: node:20-alpine
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Wrangler
        run: npm install -g wrangler

      - name: Deploy to Cloudflare Pages
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
        run: |
          wrangler pages deploy Documentation \
            --project-name=homelab-docs \
            --branch=main \
            --commit-dirty=true

5. Optional — MkDocs Material for a Polished Wiki

For a full wiki experience, add mkdocs.yml at the repo root and update the workflow:

      - name: Setup Python
        run: apk add python3 py3-pip

      - name: Install MkDocs Material
        run: pip install mkdocs-material

      - name: Build docs
        run: mkdocs build --site-dir public

      - name: Deploy to Cloudflare Pages
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
        run: |
          wrangler pages deploy public \
            --project-name=homelab-docs \
            --branch=main

[!NOTE] The Documentation/ directory is served as the site root. Cloudflare Pages will automatically serve index.html if you run a static site generator like MkDocs.

---

⚠️ Important Security Notes

[!CAUTION] Several compose files contain plaintext credentials (passwords, API keys, WireGuard private keys) directly in the YAML. These should be migrated to .env files or Docker secrets. Do not commit these files to a public repository without scrubbing secrets first.

[!WARNING] The prometheus/compose.yaml stack contains exposed API keys for Sonarr, Radarr, Lidarr, Prowlarr, qBittorrent, and UniFi. Rotate these keys if the repo is ever made public.

---

🤖 Generation Prompt Reference

This documentation suite was originally generated using the following prompt:

Act as a senior DevOps and homelab documentation engineer. 
Analyze the following Docker Compose file(s) and write clean, comprehensive, and human-readable markdown documentation for my self-hosted homelab.

The docker compose files are inside this repo, the documentation files are in the Documentation directory

Please structure the generated documentation with the following sections:
1. **Overview**: A brief summary of what this stack does and its core purpose.
2. **Architecture & Services**: A bulleted breakdown of each container/service, its role, and its exposed internal/external ports.
3. **Networking**: Explanation of custom networks used, bridge modes, or reverse proxy integration (e.g., Nginx Proxy Manager, Traefik).
4. **Persistent Storage**: Details on volumes and bind mounts, explaining where data is stored on the host machine.
5. **Environment Variables**: A table or list describing all required environment variables and secrets (leave out sensitive passwords/keys).
6. **Access & Usage**: Default URLs, login instructions (if standard), and basic health-check or startup commands.
7. **Maintenance & Backup**: Recommendations on how to update containers and backup their specific persistent volumes.

Keep the tone practical, concise, and optimized for an Obsidian or BookStack homelab wiki.

Also show a way on how to show this on a cloudflare pages page via forgejo