compose-files/README.md

# 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

```bash
# 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

```bash
# 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

```bash
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):
   ```bash
   docker-compose -f myservice.yaml up -d
   ```
3. **Convert to Swarm format** (remove `container_name`, use `services:` for Swarm)
4. **Deploy to Swarm**:
   ```bash
   docker stack deploy -c myservice.yaml myservice
   ```
5. **Commit & push**:
   ```bash
   git add myservice.yaml
   git commit -m "Add myservice stack"
   git push origin main
   ```

### Check Service Status

```bash
# 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

```bash
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)
```yaml
services:
  myapp:
    secrets:
      - db_password

secrets:
  db_password:
    external: true
```

Create the secret:
```bash
echo "mysecretpassword" | docker secret create db_password -
```

### Option 2: Environment Files (Not tracked by git)
```bash
# 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](https://git.bryanmail.net/admin/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
```bash
# 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
```bash
# View logs
docker service logs -f myservice_name

# Inspect container
docker ps -a | grep myservice
```

### Network issues
```bash
# 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

```bash
# 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