diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..e83e37f --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,290 @@ +# Home Lab Quick Start Guide + +**Welcome to your documented homelab!** This guide will help you manage and maintain your cluster. + +--- + +## 🎯 What's Been Set Up + +✅ **Cluster Audit Complete** - All services documented +✅ **Memos Fixed** - Running at https://memos.bendtstudio.com +✅ **WebStatic Scaled** - Down to 1 replica, stable +✅ **Documentation Created** - Service catalog and guides +✅ **Backup Scripts** - Automated backup tools ready +✅ **Infrastructure Repo** - All configs in version control + +--- + +## 🚀 Quick Access + +### Your Services (via HTTPS) + +| Service | URL | Status | +|---------|-----|--------| +| **Memos** | https://memos.bendtstudio.com | ✅ Working | +| **Gitea** | https://gitea.bendtstudio.com:3000 | ✅ Git server | +| **BewCloud** | Check Traefik routes | ✅ Cloud storage | +| **Immich** | Check Traefik routes | ✅ Photos | +| **SilverBullet** | Check Traefik routes | ✅ Notes | + +### Management Interfaces + +| Tool | URL | Use For | +|------|-----|---------| +| **Dokploy** | http://192.168.2.130:3000 | Deploy containers | +| **Swarmpit** | http://192.168.2.130:888 | Monitor cluster | +| **Traefik** | http://192.168.2.130:8080 | View routes | +| **MinIO** | http://192.168.2.18:9001 | Object storage | +| **DNS** | http://192.168.2.130:5380 | Manage DNS | + +--- + +## 📁 Important Files + +### In This Repo + +``` +cloud-compose/ +├── HOMELAB_AUDIT.md # Complete cluster documentation +├── SERVICE_CATALOG.md # All services documented +├── ACTION_PLAN.md # Step-by-step improvement plan +├── QUICK_REFERENCE.md # Quick access commands +├── memos-compose.yml # Fixed memos configuration +├── infrastructure/ # Backup scripts & configs +│ ├── README.md # How to use backups +│ ├── scripts/ # Backup automation +│ │ ├── backup-compose-files.sh +│ │ └── backup-critical-data.sh +│ └── compose/ # Backed up compose files +``` + +--- + +## 🔄 Regular Maintenance + +### Daily (Recommended) + +```bash +# Check cluster health +ssh ubuntu@192.168.2.130 "docker service ls" + +# Quick backup +./infrastructure/scripts/backup-compose-files.sh +``` + +### Weekly + +```bash +# Full backup +./infrastructure/scripts/backup-critical-data.sh + +# Review Swarmpit dashboard +open http://192.168.2.130:888 + +# Commit changes to git +git add . +git commit -m "Weekly backup $(date +%Y-%m-%d)" +git push +``` + +--- + +## 🛠️ Common Tasks + +### Deploy a New Service + +1. Create `docker-compose.yml` file +2. Add Traefik labels for HTTPS: + ```yaml + labels: + - traefik.http.routers.myapp.rule=Host(`myapp.bendtstudio.com`) + - traefik.http.routers.myapp.tls.certresolver=letsencrypt + - traefik.enable=true + ``` +3. Upload via Dokploy UI +4. Deploy +5. Add DNS record in Technitium DNS +6. Commit compose file to this repo + +### Backup Everything + +```bash +# Run both backup scripts +cd infrastructure/scripts +./backup-compose-files.sh +./backup-critical-data.sh + +# Commit to git +cd ../.. +git add infrastructure/ +git commit -m "Backup $(date +%Y-%m-%d)" +git push +``` + +### Check Service Logs + +```bash +# View logs +ssh ubuntu@192.168.2.130 "docker service logs --tail 50 -f" + +# Common services: +# - bewcloud-memos-ssogxn-memos +# - bendtstudio-webstatic-iq9evl +# - dokploy +``` + +### Restart a Service + +```bash +# Via SSH +ssh ubuntu@192.168.2.130 "docker service update --force " + +# Or via Dokploy UI +open http://192.168.2.130:3000 +``` + +--- + +## 🆘 Troubleshooting + +### Service Won't Start + +```bash +# Check logs +ssh ubuntu@192.168.2.130 "docker service logs --tail 100" + +# Common fixes: +# 1. Permission issues (like memos had) +# 2. Missing environment variables +# 3. Port conflicts +# 4. Image not found +``` + +### Can't Access Website + +1. Check if container is running: + ```bash + ssh ubuntu@192.168.2.130 "docker ps | grep " + ``` + +2. Check Traefik routes: + ```bash + open http://192.168.2.130:8080 + ``` + +3. Check DNS: + ```bash + dig memos.bendtstudio.com @192.168.2.130 + ``` + +### Database Issues + +```bash +# Check database container +ssh ubuntu@192.168.2.130 "docker ps | grep postgres" + +# Check database logs +ssh ubuntu@192.168.2.130 "docker service logs dokploy-postgres --tail 50" +``` + +--- + +## 📊 Current Status + +### Nodes +- **tpi-n1** (192.168.2.130) - Manager ✅ +- **tpi-n2** (192.168.2.19) - Worker ✅ +- **node-nas** (192.168.2.18) - Storage ✅ + +### Running Services +```bash +# Check all services +ssh ubuntu@192.168.2.130 "docker service ls" +``` + +### Known Issues +- **Syncthing** - Stopped (0 replicas), start when needed: + ```bash + docker service scale syncthing=1 + ``` + +--- + +## 📚 Documentation + +- **Service Catalog** - `SERVICE_CATALOG.md` +- **Infrastructure Guide** - `infrastructure/README.md` +- **Audit Report** - `HOMELAB_AUDIT.md` +- **Action Plan** - `ACTION_PLAN.md` + +--- + +## 🎓 Learning Resources + +### Docker Swarm +- Official Docs: https://docs.docker.com/engine/swarm/ +- Service Management: `docker service --help` + +### Dokploy +- Documentation: https://dokploy.com/docs/ +- UI at: http://192.168.2.130:3000 + +### Traefik +- Routing: http://192.168.2.130:8080/dashboard/ +- Labels Reference: https://doc.traefik.io/traefik/routing/providers/docker/ + +--- + +## 📞 Quick Commands Reference + +```bash +# SSH to nodes +ssh -i ~/.ssh/id_ed25519 ubuntu@192.168.2.130 # Controller +ssh -i ~/.ssh/id_ed25519 ubuntu@192.168.2.19 # Worker +ssh tim@192.168.2.18 # NAS + +# Check cluster +docker node ls +docker service ls +docker stack ls + +# View logs +docker service logs --tail 100 -f + +# Scale service +docker service scale = + +# Update service +docker service update --force +``` + +--- + +## ✅ Next Steps + +### High Priority (This Week) +- [ ] Test backup scripts +- [ ] Set up automated daily backups (cron) +- [ ] Verify all services have working HTTPS +- [ ] Add missing compose files to version control + +### Medium Priority (This Month) +- [ ] Create disaster recovery procedures +- [ ] Set up monitoring alerts +- [ ] Document all environment variables +- [ ] Test restore procedures + +### Low Priority (When Time) +- [ ] Set up Prometheus/Grafana +- [ ] Create network diagrams +- [ ] Automate SSL certificate renewal checks +- [ ] Security audit + +--- + +**Questions or issues?** Check the detailed documentation in: +- `HOMELAB_AUDIT.md` - Complete technical details +- `SERVICE_CATALOG.md` - Service-specific information +- `infrastructure/README.md` - Backup and management guide + +*Last Updated: February 9, 2026*