@@ -1,3 +1,257 @@
|
||||
# compose-files
|
||||
# Homelab Infrastructure Repository - Docker Swarm Compose Files
|
||||
|
||||
Docker Swarm compose files for homelab services
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user