admin/compose-files
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README - focus on compose files only, scripts moved to homelab-scripts repo

Browse Source
This commit is contained in:
admin
2026-06-18 23:01:32 -07:00
parent bde1332053
commit 293dcef556
1 changed files with 135 additions and 220 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+134 -219
View File
@@ -1,54 +1,33 @@
# Homelab Infrastructure Repository # Homelab Infrastructure Repository - Docker Swarm Compose Files
This Gitea repository contains all configuration files and scripts for managing the homelab infrastructure: This Gitea repository contains **Docker Swarm compose files** for all services running in the homelab.
- **Docker Swarm** cluster (3 nodes: docker-1, docker-2, docker-3) **For operational scripts** (backup hooks, prune watchdog, network configuration), see the separate **`homelab-scripts`** repository.
- **Proxmox** cluster (3 nodes: nuck7-1, nuck7-2, nuck7-3)
- **Operational automation** (backups, monitoring, network management)
--- ---
## 📁 Directory Structure ## 📁 Directory Structure
``` ```
├── compose-files/ # Docker Swarm compose files ├── traefik.yaml # Reverse proxy & load balancer
│ ├── traefik.yaml # Reverse proxy & load balancer ├── auth.yaml # Authentik authentication
│ ├── auth.yaml # Authentik authentication ├── postgresql.yaml # PostgreSQL database
│ ├── postgresql.yaml # PostgreSQL database ├── maintenance.yaml # Cronicle scheduler, Uptime Kuma
│ ├── ... (other stacks) ├── ... (other service stacks)
│ └── (add new services here) └── README.md # This file
│
├── scripts/ # Operational scripts
│ ├── monitoring/ # Disk & service monitoring
│ │ ├── docker-prune-watchdog.sh
│ │ ├── docker-prune-watchdog.env.example
│ │ └── docker-prune-watchdog.service
│ ├── backup/ # Backup automation
│ │ └── vzdump-docker-hook.sh
│ ├── network/ # Network configuration
│ │ ├── mtu_phase1.sh
│ │ ├── mtu_phase2.sh
│ │ └── mtu_rollback.sh
│ └── fixes/ # One-time boot fixes
│ └── rc.local.fix.sh
│
├── SCRIPTS-README.md # Detailed scripts documentation
├── README.md # This file
└── .gitignore # Don't commit secrets, logs, etc.
``` ```
--- ---
## 🚀 Quick Start ## 🚀 Quick Start
### Using Docker Swarm Compose Files ### Deploy a Stack
```bash ```bash
# SSH into a Docker LXC # SSH into a Docker LXC (docker-1, docker-2, or docker-3)
ssh root@docker-1 # or docker-2, docker-3 ssh root@docker-1
# Clone the repo locally # Clone this repo locally
cd /volume1/docker cd /volume1/docker
git clone https://git.bryanmail.net/admin/compose-files.git repo git clone https://git.bryanmail.net/admin/compose-files.git repo
cd repo cd repo
@@ -57,230 +36,151 @@ cd repo
docker stack deploy -c traefik.yaml traefik docker stack deploy -c traefik.yaml traefik
docker stack deploy -c auth.yaml auth docker stack deploy -c auth.yaml auth
docker stack deploy -c postgresql.yaml postgresql docker stack deploy -c postgresql.yaml postgresql
```
# View running stacks ### Update a Stack
docker stack ls
```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 docker service ls
``` ```
### Managing & Updating Stacks ### Remove a Stack
```bash ```bash
# Pull latest from repo
git pull origin main
# Update a specific stack (re-deploy)
docker stack deploy -c traefik.yaml traefik
# Remove a stack
docker stack rm traefik docker stack rm traefik
# View stack status
docker stack ps traefik
# View service logs
docker service logs traefik_reverse-proxy
``` ```
--- ---
## 🛠️ Operational Scripts ## 📋 Available Stacks
### **[→ Full Scripts Documentation](SCRIPTS-README.md)** | Stack | File | Purpose |
|-------|------|---------|
Quick reference: | Traefik | traefik.yaml | Reverse proxy, load balancer, TLS termination |
| Authentik | auth.yaml | Authentication & authorization |
#### 1. **Docker Prune Watchdog** | PostgreSQL | postgresql.yaml | Database backend |
Automatically manages disk space on Docker nodes. | Maintenance | maintenance.yaml | Cronicle jobs, Uptime Kuma monitoring |
```bash | ... | ... | (Add more as you create them) |
# Check status
systemctl status docker-prune-watchdog.service
# View logs
tail -f /dev/shm/docker-prune-watchdog.log
# Configuration
cat /etc/docker-prune-watchdog.env
```
#### 2. **Proxmox Backup Hook**
Gracefully stops Docker during backups to prevent corruption.
```bash
# Installed at
/usr/local/bin/vzdump-docker-hook.sh
# Check logs
tail -f /var/log/vzdump-docker-hook.log
```
#### 3. **MTU 9000 Migration**
Migrate Docker Swarm to Jumbo Frames for improved performance.
```bash
# See SCRIPTS-README.md for detailed steps
```
--- ---
## 📋 Architecture ## 🛠️ Common Tasks
### Proxmox Cluster
```
nuck7-1 (Hypervisor) nuck7-2 (Hypervisor) nuck7-3 (Hypervisor)
├─ docker-1 (LXC 4031) ├─ docker-2 (LXC 4032) ├─ docker-3 (LXC 4033)
│ └─ Docker Swarm Node │ └─ Docker Swarm Node │ └─ Docker Swarm Node
│ (Manager) │ (Leader) │ (Manager)
└─ ...other LXCs └─ ...other LXCs └─ ...other LXCs
```
### Storage
- **CephFS** mounted at `/volume1/docker/` (shared across all docker LXCs)
- **Compose files**: `/volume1/docker/compose-files/`
- **Scripts**: `/volume1/docker/mtu_migration/`, `/usr/local/bin/`, etc.
- **Data volumes**: PostgreSQL, Authentik, and other services use named volumes or `/volume1/docker/` mounts
### Networking
- **VIP**: 192.168.4.30 (Keepalived, managed by docker-2)
- **Docker hosts**: 192.168.4.31 (docker-1), 192.168.4.32 (docker-2), 192.168.4.33 (docker-3)
- **Traefik**: Reverse proxy with Let's Encrypt TLS + Authentik forward auth
- **Domain**: bryanmail.net
---
## 🔧 Common Tasks
### Deploy a New Service ### Deploy a New Service
1. **Create compose file** in `/volume1/docker/compose-files/myservice.yaml` 1. **Create compose file** in this repo: `myservice.yaml`
2. **Test locally**: 2. **Test locally** (on single host):
```bash ```bash
docker compose -f myservice.yaml up -d docker-compose -f myservice.yaml up -d
docker compose -f myservice.yaml logs
``` ```
3. **Convert to Swarm** (remove `container_name`, use `services:` format for Swarm) 3. **Convert to Swarm format** (remove `container_name`, use `services:` for Swarm)
4. **Deploy to Swarm**: 4. **Deploy to Swarm**:
```bash ```bash
docker stack deploy -c myservice.yaml myservice docker stack deploy -c myservice.yaml myservice
``` ```
5. **Commit to repo**: 5. **Commit & push**:
```bash ```bash
git add myservice.yaml git add myservice.yaml
git commit -m "Add myservice stack" git commit -m "Add myservice stack"
git push origin main git push origin main
``` ```
### Update a Running Service ### Check Service Status
```bash
# Edit the compose file
nano /volume1/docker/compose-files/traefik.yaml
# Redeploy
docker stack deploy -c /volume1/docker/compose-files/traefik.yaml traefik
# Verify changes
docker stack ps traefik
```
### Check Disk Space
```bash
# On docker host
df -h /volume1/docker-root
# View prune watchdog status
systemctl status docker-prune-watchdog.service
tail -f /dev/shm/docker-prune-watchdog.log
```
### Monitor Services
```bash ```bash
# List all services # List all services
docker service ls docker service ls
# Get service details # Get details about a service
docker service inspect traefik_reverse-proxy docker service inspect traefik_reverse-proxy
# View service logs # View service logs
docker service logs -f traefik_reverse-proxy docker service logs -f traefik_reverse-proxy
# Check service tasks (containers) # Check tasks (containers)
docker service ps traefik_reverse-proxy 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)
```
--- ---
## ⚠️ Important Notes ## 🔐 Secrets Management
### Secrets Management
**DO NOT commit secrets, passwords, or API keys to this repo.** **DO NOT commit secrets, passwords, or API keys to this repo.**
Use one of these approaches: Use one of these approaches:
1. **Docker Secrets** (for Swarm)
```yaml
services:
myapp:
secrets:
- db_password
secrets:
db_password:
external: true
```
2. **Environment files** (add to `.gitignore`) ### Option 1: Docker Secrets (Recommended for Swarm)
```bash ```yaml
# Create .env (not tracked by git) services:
echo "DB_PASSWORD=mysecretpassword" > .env myapp:
secrets:
- db_password
# Use in compose secrets:
env_file: .env db_password:
``` external: true
3. **Docker Secrets CLI**
```bash
echo "mysecretpassword" | docker secret create db_password -
```
### Git Workflow
```bash
# Before starting work
git pull origin main
# Create a feature branch for new services
git checkout -b feature/new-service
# Make changes
# ... edit files ...
# Commit
git add .
git commit -m "Add new-service stack with documentation"
# Push
git push origin feature/new-service
# Create PR for review (if using pull requests)
``` ```
### Backup Strategy Create the secret:
- **Proxmox backups**: Automatic via vzdump-docker-hook.sh ```bash
- **Database exports**: Automated via Cronicle jobs echo "mysecretpassword" | docker secret create db_password -
- **Configurations**: Version controlled in this repo (compose files, scripts) ```
- **Volumes**: Proxmox handles via CephFS snapshots
### 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
```
--- ---
## 📚 Related Documentation ## 📚 Architecture
- **Architecture Decision Records (ADRs)**: See notes ### Swarm Cluster
- ADR-006: Jumbo Frames (MTU 9000) ```
- ADR-009: Backup Strategy nuck7-1 (Hypervisor) nuck7-2 (Hypervisor) nuck7-3 (Hypervisor)
- ADR-011: Observability & Self-Healing ├─ docker-1 (LXC 4031) ├─ docker-2 (LXC 4032) ├─ docker-3 (LXC 4033)
│ └─ Swarm Manager │ └─ Swarm Leader │ └─ Swarm Manager
└─ ... └─ ... └─ ...
```
- **Detailed Scripts**: [→ SCRIPTS-README.md](SCRIPTS-README.md) ### Storage
- **Proxmox Setup**: Documented in separate notes - **CephFS** mounted at `/volume1/docker/` (shared across all nodes)
- **MCP Servers**: Proxmox MCP configured in Open WebUI - **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
--- ---
@@ -296,47 +196,62 @@ docker node ls
# Check disk space # Check disk space
df -h /volume1/docker-root df -h /volume1/docker-root
# Check Docker status
systemctl status docker
``` ```
### Service container keeps restarting ### Service keeps crashing
```bash ```bash
# View service logs # View logs
docker service logs -f myservice_container docker service logs -f myservice_name
# Inspect container state # Inspect container
docker ps -a | grep myservice docker ps -a | grep myservice
``` ```
### Network issues ### Network issues
```bash ```bash
# Check overlay networks # List networks
docker network ls --filter driver=overlay docker network ls --filter driver=overlay
# Verify network connectivity # Test connectivity
docker run --rm --network traefik_backend alpine ping traefik_reverse-proxy docker run --rm --network traefik_backend alpine ping traefik_reverse-proxy
``` ```
--- ---
## 🤝 Contributing ## 📞 Contributing
When adding new services: When adding new services:
1. **Use Swarm-compatible YAML** (no `container_name`, proper `services:` format) 1. Use **Swarm-compatible YAML** (no `container_name`)
2. **Document requirements** in compose file comments 2. Document requirements in compose file comments
3. **Test on non-production first** (docker-compose up on single host) 3. Test on non-production first
4. **Add notes** about persistent volumes, secrets, networking 4. Add notes about volumes, secrets, networking
5. **Update this README** if adding infrastructure changes 5. Update this README with stack description
--- ---
## 📞 Support ## 📝 Git Workflow
For detailed script documentation: [→ SCRIPTS-README.md](SCRIPTS-README.md) ```bash
# Before starting work
git pull origin main
For architecture decisions: See ADRs in notes # Create feature branch for new service
git checkout -b feature/new-service
For troubleshooting: Check logs, verify disk space, check Docker Swarm status # 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