# 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! 🎉**