added ansible script

2026-02-16 23:40:30 +01:00
parent e6e444fff7
commit 8925d9677e
86 changed files with 15476 additions and 1911 deletions
--- a/ansible/PROJECT_SUMMARY.md
+++ b/ansible/PROJECT_SUMMARY.md
@@ -0,0 +1,560 @@
+# Nextcloud Stack - Ansible Deployment Project
+
+## 🎉 Project Complete!
+
+This Ansible automation project provides complete, one-command deployment of a self-hosted Nextcloud productivity stack to Ubuntu-based LXC/VPS servers.
+
+---
+
+## 📦 What's Included
+
+### Core Files
+
+```
+ansible-nextcloud-deployment/
+├── setup.sh                          # ⭐ Interactive configuration wizard
+├── Makefile                          # Convenient command shortcuts
+├── ansible.cfg                       # Ansible configuration
+├── .gitignore                        # Git ignore rules
+│
+├── inventory/                        # Generated by setup.sh
+│   ├── hosts.yml                    # Server inventory (generated)
+│   └── group_vars/all/
+│       ├── vars.yml                 # Public variables (generated)
+│       └── vault.yml                # Encrypted secrets (generated)
+│
+├── playbooks/                        # ⭐ Deployment playbooks
+│   ├── site.yml                     # Main orchestrator
+│   ├── 01-preflight-checks.yml      # DNS, connectivity validation
+│   ├── 02-system-setup.yml          # Packages, firewall, security
+│   ├── 03-docker-setup.yml          # Docker CE installation
+│   ├── 04-tailscale-setup.yml       # VPN setup
+│   ├── 05-deploy-stack.yml          # Docker Compose deployment
+│   ├── 06-configure-caddy.yml       # Reverse proxy + SSL
+│   ├── 07-setup-backups.yml         # Backup automation
+│   ├── 08-post-deployment.yml       # Final verification
+│   └── 99-rollback.yml              # Emergency rollback
+│
+├── roles/                            # ⭐ Ansible roles
+│   ├── nextcloud_stack/
+│   │   └── templates/
+│   │       ├── docker-compose.yml.j2  # Complete stack definition
+│   │       └── env.j2                 # Environment variables
+│   └── caddy/
+│       └── templates/
+│           └── Caddyfile.j2           # Reverse proxy config
+│
+└── docs/                             # ⭐ Documentation
+    ├── README.md                    # Project overview
+    ├── DEPLOYMENT_GUIDE.md          # Quick start guide
+    ├── TROUBLESHOOTING.md           # Common issues & solutions
+    └── BACKUP_RESTORE.md            # Backup procedures
+```
+
+### Stack Components (12 Services)
+
+**Public Services** (via HTTPS):
+- Nextcloud (file sync & collaboration)
+- OnlyOffice (document editor)
+- Excalidraw (whiteboard)
+- Obsidian (note-taking)
+
+**Infrastructure**:
+- PostgreSQL 18 (database)
+- Redis 7 (cache)
+- Caddy (reverse proxy + automatic SSL)
+
+**Management** (Tailscale-only):
+- Homarr (dashboard)
+- Dockhand (container manager)
+- Uptime Kuma (monitoring)
+
+**Automation**:
+- Watchtower (auto-updates with safety exclusions)
+
+---
+
+## 🚀 Quick Start
+
+### 1. Configure
+
+```bash
+./setup.sh
+```
+
+Interactive wizard collects all configuration:
+- Server details (IP, domain, SSH)
+- User information
+- Admin credentials
+- Subdomain preferences
+- Tailscale auth key (optional)
+- Monitoring settings
+
+**Generates:**
+- `inventory/hosts.yml` - Server inventory
+- `inventory/group_vars/all/vars.yml` - Public config
+- `inventory/group_vars/all/vault.yml` - Encrypted secrets
+
+### 2. Deploy
+
+```bash
+make deploy
+```
+
+Or:
+```bash
+ansible-playbook playbooks/site.yml --ask-vault-pass
+```
+
+**Duration:** 30-45 minutes per server
+
+### 3. Access
+
+- Nextcloud: `https://cloud.yourdomain.com`
+- Homarr: `https://home.yourdomain.com` (Tailscale)
+- Uptime Kuma: `https://uptime.yourdomain.com` (Tailscale)
+
+---
+
+## ✨ Key Features
+
+### 🔒 Security
+
+- **Firewall**: UFW configured (only SSH, HTTP, HTTPS, Tailscale open)
+- **Fail2ban**: SSH brute-force protection (5 failures = 10 min ban)
+- **Automatic Security Updates**: Unattended upgrades enabled
+- **Secret Management**: Ansible Vault encryption for all credentials
+- **Access Control**: Management UIs restricted to Tailscale network
+- **SSL/TLS**: Automatic Let's Encrypt certificates via Caddy
+- **Container Isolation**: Dedicated Docker network
+
+### 💾 Backups
+
+- **Daily**: PostgreSQL database dumps (3:00 AM)
+- **Weekly**: Full volume backups (Sundays, 3:00 AM)
+- **Retention**: 30 days
+- **Location**: `/opt/nextcloud-stack/backups/`
+- **Off-site Ready**: rclone pre-installed
+- **Automated**: Cron jobs configured
+- **Tested**: Documented restore procedures
+
+### 🔄 Updates
+
+**Automated (Watchtower)**:
+- Caddy, Excalidraw, Obsidian, Homarr, Dockhand, Uptime Kuma
+
+**Monitor Only**:
+- OnlyOffice (notifications, manual update)
+
+**Manual Required**:
+- Nextcloud, PostgreSQL, Redis (too critical to auto-update)
+
+### 🌐 Multi-Server Support
+
+Deploy identical stacks to multiple servers:
+- Each server gets unique domain
+- Fully independent deployments
+- Shared Tailscale network (optional)
+
+### 📊 Monitoring
+
+- **Uptime Kuma**: Service health monitoring
+- **Email Alerts**: Configurable notifications
+- **Status Page**: Optional public status page
+- **Container Health**: Docker healthchecks
+- **SSL Monitoring**: Certificate expiry tracking
+
+---
+
+## 📚 Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [README.md](README.md) | Complete project overview, features, usage |
+| [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | Step-by-step deployment instructions |
+| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Common issues and solutions |
+| [BACKUP_RESTORE.md](BACKUP_RESTORE.md) | Backup and restore procedures |
+| [AGENTS.md](AGENTS.md) | Docker Compose & Ansible guidelines |
+
+---
+
+## 🛠️ Makefile Commands
+
+```bash
+make help          # Show all commands
+make setup         # Run interactive setup
+make ping          # Test connectivity
+make check         # Run preflight checks
+make deploy        # Full deployment
+make deploy-dry    # Test run (no changes)
+make status        # Show container status
+make logs          # View all logs
+make backup        # Run manual backup
+make restart       # Restart all containers
+make edit-vault    # Edit encrypted secrets
+make rekey-vault   # Change vault password
+```
+
+---
+
+## 🎯 Design Principles
+
+### 1. **User-Friendly**
+- Interactive setup script (no manual configuration editing)
+- Automatic SSL certificates
+- Clear documentation
+- Helpful error messages
+
+### 2. **Secure by Default**
+- Minimal firewall rules
+- Encrypted secrets (Ansible Vault)
+- Tailscale-only admin interfaces
+- Automatic security updates
+- No hardcoded credentials
+
+### 3. **Production-Ready**
+- Automated backups
+- Monitoring included
+- Health checks configured
+- Documented restore procedures
+- Emergency rollback playbook
+
+### 4. **Maintainable**
+- Modular playbook structure
+- Clear variable naming
+- Comprehensive comments
+- Role-based organization
+- Git-friendly (.gitignore configured)
+
+### 5. **Safe Updates**
+- Critical services excluded from auto-update
+- Watchtower uses label-based control
+- Manual update procedures documented
+- Rollback capability included
+
+---
+
+## 🔧 Deployment Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. SETUP (./setup.sh)                                       │
+│    • Collect server details, domains, credentials           │
+│    • Generate encrypted inventory & variables               │
+│    • Create Ansible Vault with secrets                      │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 2. PREFLIGHT CHECKS (01-preflight-checks.yml)              │
+│    • Verify Ansible version, SSH connectivity               │
+│    • Check disk space, ports availability                   │
+│    • Validate DNS records, detect LXC                       │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 3. SYSTEM SETUP (02-system-setup.yml)                      │
+│    • Update packages, install essentials                    │
+│    • Configure UFW firewall, fail2ban                       │
+│    • Enable automatic security updates                      │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 4. DOCKER SETUP (03-docker-setup.yml)                      │
+│    • Remove old Docker installations                        │
+│    • Install Docker CE + Compose v2                         │
+│    • Configure Docker daemon                                │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 5. TAILSCALE SETUP (04-tailscale-setup.yml)                │
+│    • Install Tailscale                                      │
+│    • Activate if auth key provided                          │
+│    • Enable systemd service                                 │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 6. DEPLOY STACK (05-deploy-stack.yml)                      │
+│    • Create directory structure                             │
+│    • Template docker-compose.yml, .env, configs             │
+│    • Pull Docker images, start containers                   │
+│    • Wait for services healthy                              │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 7. CONFIGURE CADDY (06-configure-caddy.yml)                │
+│    • Validate Caddyfile syntax                              │
+│    • Reload Caddy configuration                             │
+│    • Obtain Let's Encrypt SSL certificates                  │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 8. SETUP BACKUPS (07-setup-backups.yml)                    │
+│    • Create backup script                                   │
+│    • Configure cron jobs (daily/weekly)                     │
+│    • Run test backup                                        │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│ 9. POST-DEPLOYMENT (08-post-deployment.yml)                │
+│    • Verify all containers running                          │
+│    • Install Nextcloud apps                                 │
+│    • Configure background jobs                              │
+│    • Create deployment report                               │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+                    ✅ DEPLOYMENT COMPLETE!
+```
+
+---
+
+## 🧩 Template Files
+
+### docker-compose.yml.j2
+
+Complete Docker Compose stack with:
+- All 12 services configured
+- Health checks for critical services
+- Proper dependencies (depends_on with conditions)
+- Watchtower labels for update control
+- Named volumes and networks
+- Environment variables from .env
+
+**Location**: `roles/nextcloud_stack/templates/docker-compose.yml.j2`
+
+### Caddyfile.j2
+
+Caddy reverse proxy configuration with:
+- Automatic SSL for all domains
+- Public services (Nextcloud, OnlyOffice, etc.)
+- Tailscale-restricted services (Homarr, Dockhand, Uptime Kuma)
+- Security headers
+- Large file upload support (10GB)
+- Optional public status page
+
+**Location**: `roles/caddy/templates/Caddyfile.j2`
+
+### env.j2
+
+Environment variables template with:
+- Database credentials
+- Redis password
+- Nextcloud admin credentials
+- Application secrets (Homarr)
+- Domain configuration
+- Timezone settings
+
+**Location**: `roles/nextcloud_stack/templates/env.j2`
+
+---
+
+## 🔐 Security Considerations
+
+### Secrets Management
+
+All sensitive data encrypted with Ansible Vault:
+- Database passwords
+- Admin credentials
+- Application secrets
+- Tailscale auth keys
+
+**Never committed in plain text!**
+
+### Network Security
+
+- **Public**: Only Nextcloud and productivity apps
+- **Tailscale-only**: All management interfaces
+- **Internal**: Database and Redis (no external access)
+
+### Firewall Rules (UFW)
+
+```
+22/tcp   - SSH
+80/tcp   - HTTP (redirects to HTTPS)
+443/tcp  - HTTPS
+443/udp  - HTTP/3 (QUIC)
+41641/udp - Tailscale
+Default: DENY
+```
+
+### Update Strategy
+
+**Why not auto-update everything?**
+
+- **Nextcloud**: Database migrations may fail automatically
+- **PostgreSQL**: Schema changes could break Nextcloud
+- **Redis**: Unlikely issues, but excluded for consistency
+
+**Safe to auto-update:**
+- Stateless applications (Excalidraw, Obsidian)
+- Infrastructure (Caddy)
+- Management tools (Homarr, Dockhand)
+
+---
+
+## 📊 Resource Usage (Approximate)
+
+### Disk Space
+
+- Docker images: ~5GB
+- Initial volumes: ~2GB
+- Backups (30 days): ~50GB
+- **Total recommended**: 100GB minimum
+
+### Memory
+
+- PostgreSQL: ~256MB
+- Redis: ~256MB (configured limit)
+- Nextcloud: ~512MB
+- OnlyOffice: ~2GB
+- Other services: ~1GB combined
+- **Total**: 4-6GB RAM recommended
+
+### Network
+
+- **Inbound**: 80, 443 (HTTP/HTTPS), 41641 (Tailscale)
+- **Outbound**: Internet access required for Let's Encrypt, Docker images, updates
+
+---
+
+## 🎓 Next Steps
+
+### Immediate
+
+1. **Test the deployment** on a test server first
+2. **Verify DNS** is configured correctly
+3. **Run setup.sh** and answer questions carefully
+4. **Deploy** with `make deploy`
+5. **Access Nextcloud** and complete initial setup
+
+### After Deployment
+
+1. **Configure Uptime Kuma** monitoring
+2. **Customize Homarr** dashboard
+3. **Test backups** with `make backup`
+4. **Enable 2FA** in Nextcloud
+5. **Install additional Nextcloud apps** as needed
+
+### Ongoing
+
+1. **Monitor** service health in Uptime Kuma
+2. **Review backups** monthly
+3. **Test restore** procedures quarterly
+4. **Update Nextcloud** when new versions release (manually)
+5. **Check logs** for any issues
+
+---
+
+## 💡 Tips & Best Practices
+
+### For LXC Containers
+
+**On LXC host, enable nested virtualization:**
+```bash
+lxc config set CONTAINER_NAME security.nesting true
+lxc restart CONTAINER_NAME
+```
+
+### For Production Use
+
+1. Use strong passwords (not example passwords)
+2. Enable Nextcloud 2FA
+3. Configure off-site backups with rclone
+4. Set up Uptime Kuma email alerts
+5. Review logs regularly
+
+### For Multiple Servers
+
+Each server can have:
+- Different domain
+- Different subdomain preferences
+- Same or different Tailscale network
+
+Just run `setup.sh` and add all servers when prompted.
+
+---
+
+## 🐛 Known Limitations
+
+1. **Watchtower is archived** (December 2025)
+   - Still works, but no longer maintained
+   - Consider alternative update strategies long-term
+
+2. **OnlyOffice needs 2GB+ RAM**
+   - May be slow on low-memory servers
+   - Consider disabling if not needed
+
+3. **First-time deployment takes 30-45 min**
+   - Mostly Docker image downloads
+   - Subsequent deploys are faster
+
+4. **Let's Encrypt rate limits**
+   - 50 certs/week per domain
+   - Use staging server for testing
+
+---
+
+## 📜 License
+
+MIT License - Use freely, modify as needed
+
+---
+
+## 🙏 Acknowledgments
+
+Built with these amazing open-source projects:
+
+- **Nextcloud** - File sync and collaboration
+- **Caddy** - Automatic HTTPS web server
+- **Ansible** - IT automation
+- **Docker** - Containerization
+- **PostgreSQL** - Database
+- **Tailscale** - Zero-config VPN
+- **OnlyOffice**, **Excalidraw**, **Obsidian** - Productivity tools
+- **Homarr**, **Dockhand**, **Uptime Kuma** - Management & monitoring
+
+---
+
+## 📞 Support
+
+**Documentation:**
+- [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) - Getting started
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Fix common issues
+- [BACKUP_RESTORE.md](BACKUP_RESTORE.md) - Backup procedures
+
+**Project Files:**
+All source code, playbooks, and templates included in this repository.
+
+---
+
+## ✅ Checklist for New Users
+
+Before deploying:
+- [ ] Read DEPLOYMENT_GUIDE.md
+- [ ] Install Ansible 2.14+ on control machine
+- [ ] Have Ubuntu 20.04+ server ready
+- [ ] Configure DNS A records
+- [ ] Test SSH access to server
+- [ ] Have domain name ready
+- [ ] Decide on subdomain preferences
+
+After deploying:
+- [ ] Access Nextcloud web UI
+- [ ] Complete Nextcloud setup wizard
+- [ ] Setup Uptime Kuma monitoring
+- [ ] Configure Homarr dashboard
+- [ ] Test backup with `make backup`
+- [ ] Enable Nextcloud 2FA
+- [ ] Review deployment report
+- [ ] Save Ansible Vault password securely
+
+---
+
+**Project Status**: ✅ Complete and Ready for Use
+
+**Last Updated**: 2026-02-16
+
+**Version**: 1.0
+
+---
+
+**Happy self-hosting! 🎉**