Homelab Infrastructure Repository - Docker Swarm Compose Files

This Gitea repository contains Docker Swarm compose files for all services running in the homelab.

For operational scripts (backup hooks, prune watchdog, network configuration), see the separate homelab-scripts repository.

---

📁 Directory Structure

├── traefik.yaml               # Reverse proxy & load balancer
├── auth.yaml                  # Authentik authentication
├── postgresql.yaml            # PostgreSQL database
├── maintenance.yaml           # Cronicle scheduler, Uptime Kuma
├── ... (other service stacks)
└── README.md                  # This file

---

🚀 Quick Start

Deploy a Stack

# SSH into a Docker LXC (docker-1, docker-2, or docker-3)
ssh root@docker-1

# Clone this repo locally
cd /volume1/docker
git clone https://git.bryanmail.net/admin/compose-files.git repo
cd repo

# Deploy a stack
docker stack deploy -c traefik.yaml traefik
docker stack deploy -c auth.yaml auth
docker stack deploy -c postgresql.yaml postgresql

Update a Stack

# Pull latest changes
git pull origin main

# Re-deploy (applies changes)
docker stack deploy -c traefik.yaml traefik

# View status
docker stack ps traefik
docker service ls

Remove a Stack

docker stack rm traefik

---

📋 Available Stacks

Stack	File	Purpose
Traefik	traefik.yaml	Reverse proxy, load balancer, TLS termination
Authentik	auth.yaml	Authentication & authorization
PostgreSQL	postgresql.yaml	Database backend
Maintenance	maintenance.yaml	Cronicle jobs, Uptime Kuma monitoring
...	...	(Add more as you create them)

---

🛠️ Common Tasks

Deploy a New Service

1. Create compose file in this repo: myservice.yaml
2. Test locally (on single host):

   docker-compose -f myservice.yaml up -d
   

3. Convert to Swarm format (remove container_name, use services: for Swarm)
4. Deploy to Swarm:

   docker stack deploy -c myservice.yaml myservice
   

5. Commit & push:

   git add myservice.yaml
   git commit -m "Add myservice stack"
   git push origin main
   

Check Service Status

# List all services
docker service ls

# Get details about a service
docker service inspect traefik_reverse-proxy

# View service logs
docker service logs -f traefik_reverse-proxy

# Check tasks (containers)
docker service ps traefik_reverse-proxy

Monitor Disk Space

df -h /volume1/docker-root

# Docker prune watchdog handles auto-cleanup (see homelab-scripts repo)

---

🔐 Secrets Management

DO NOT commit secrets, passwords, or API keys to this repo.

Use one of these approaches:

Option 1: Docker Secrets (Recommended for Swarm)

services:
  myapp:
    secrets:
      - db_password

secrets:
  db_password:
    external: true

Create the secret:

echo "mysecretpassword" | docker secret create db_password -

Option 2: Environment Files (Not tracked by git)

# Create .env (add to .gitignore)
echo "DB_PASSWORD=mysecretpassword" > .env

# Use in compose
env_file: .env

---

📚 Architecture

Swarm Cluster

nuck7-1 (Hypervisor)        nuck7-2 (Hypervisor)        nuck7-3 (Hypervisor)
├─ docker-1 (LXC 4031)      ├─ docker-2 (LXC 4032)      ├─ docker-3 (LXC 4033)
│  └─ Swarm Manager         │  └─ Swarm Leader          │  └─ Swarm Manager
└─ ...                      └─ ...                      └─ ...

Storage

• CephFS mounted at /volume1/docker/ (shared across all nodes)
• Compose files: /volume1/docker/compose-files/
• Service data: Named volumes or /volume1/docker/ mounts

Networking

• VIP: 192.168.4.30 (Keepalived)
• Docker hosts: 192.168.4.31-33
• Traefik: Reverse proxy with Let's Encrypt TLS
• Domain: bryanmail.net

---

🔗 Related Repositories

• homelab-scripts - Operational scripts (backup hooks, monitoring, network config)
• Proxmox MCP Setup - Documented in notes
• Architecture Decision Records (ADRs) - Documented in notes

---

🐛 Troubleshooting

Stack won't deploy

# Check syntax
docker-compose config -f myservice.yaml

# Check node availability
docker node ls

# Check disk space
df -h /volume1/docker-root

Service keeps crashing

# View logs
docker service logs -f myservice_name

# Inspect container
docker ps -a | grep myservice

Network issues

# List networks
docker network ls --filter driver=overlay

# Test connectivity
docker run --rm --network traefik_backend alpine ping traefik_reverse-proxy

---

📞 Contributing

When adding new services:

1. Use Swarm-compatible YAML (no container_name)
2. Document requirements in compose file comments
3. Test on non-production first
4. Add notes about volumes, secrets, networking
5. Update this README with stack description

---

📝 Git Workflow

# Before starting work
git pull origin main

# Create feature branch for new service
git checkout -b feature/new-service

# Make changes and commit
git add .
git commit -m "Add new-service stack"

# Push
git push origin feature/new-service

---

Version Control Best Practices

• Keep compose files in sync with deployed state
• Pin image versions (avoid latest tag)
• Document breaking changes in commit messages
• Use meaningful commit messages for audit trail