Archived
258 lines
5.5 KiB
Markdown
258 lines
5.5 KiB
Markdown
# 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
|