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/START_HERE.md
+++ b/ansible/START_HERE.md
@@ -0,0 +1,192 @@
+# 👋 Welcome to Nextcloud Stack Ansible Deployment!
+
+## 🚀 Quick Start (Choose Your Path)
+
+### 🏃 I Want to Deploy NOW
+1. Read → [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) (10 min read)
+2. Run → `./setup.sh` (5-10 min)
+3. Deploy → `make deploy` (30-45 min)
+
+### 📚 I Want to Learn More First
+1. Read → [README.md](README.md) - Complete project overview
+2. Read → [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) - Design & architecture
+3. Then → Follow Quick Start above
+
+### 🔧 I'm Having Issues
+1. Check → [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+2. Check logs → `make logs`
+3. Review → [BACKUP_RESTORE.md](BACKUP_RESTORE.md) if you need to restore
+
+---
+
+## 📖 Documentation Index
+
+| Document | Purpose | Read Time |
+|----------|---------|-----------|
+| **[DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)** | Step-by-step deployment instructions | 10 min |
+| **[README.md](README.md)** | Complete project overview & features | 15 min |
+| **[PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)** | Technical details & design | 10 min |
+| **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** | Common issues & solutions | Reference |
+| **[BACKUP_RESTORE.md](BACKUP_RESTORE.md)** | Backup & restore procedures | Reference |
+| **[AGENTS.md](AGENTS.md)** | Docker & Ansible development guidelines | Reference |
+
+---
+
+## ✅ Pre-Deployment Checklist
+
+Before you begin, ensure you have:
+
+- [ ] Ubuntu 20.04+ server (LXC or VPS)
+- [ ] Root or sudo access to server
+- [ ] Minimum 100GB disk space on server
+- [ ] Ansible 2.14+ installed on your laptop/control machine
+- [ ] Domain name with DNS control
+- [ ] SSH access configured to server
+
+**Critical:** DNS A records must point to your server BEFORE deployment!
+
+---
+
+## 🎯 What You'll Get
+
+After deployment, you'll have:
+
+### Public Services (HTTPS)
+- **Nextcloud** - File sync & collaboration
+- **OnlyOffice** - Document editor (Word, Excel, PowerPoint)
+- **Excalidraw** - Whiteboard & diagrams
+- **Obsidian** - Note-taking & knowledge management
+
+### Management Tools (Tailscale-only, secure)
+- **Homarr** - Beautiful dashboard for all services
+- **Dockhand** - Container management interface
+- **Uptime Kuma** - Monitoring & alerts
+
+### Infrastructure (automatic, invisible)
+- **Caddy** - Reverse proxy with automatic SSL
+- **PostgreSQL** - Database
+- **Redis** - Cache for better performance
+- **Watchtower** - Automatic updates (safe services only)
+
+---
+
+## 💡 Key Features
+
+- ✅ **One-command deployment** - `make deploy` does everything
+- ✅ **Automatic SSL** - Let's Encrypt certificates via Caddy
+- ✅ **Secure by default** - Firewall, fail2ban, Vault encryption
+- ✅ **Auto backups** - Daily DB, weekly volumes (30-day retention)
+- ✅ **Multi-server** - Deploy to multiple VPS with unique domains
+- ✅ **Production-ready** - Monitoring, backups, documentation
+
+---
+
+## 🏗️ Project Structure
+
+```
+/home/liph/programming/ansible/
+├── setup.sh ⭐                    # Start here! Interactive setup
+├── Makefile                       # Convenient commands (make deploy)
+├── playbooks/                     # 10 Ansible playbooks
+│   ├── site.yml                  # Main orchestrator
+│   ├── 01-preflight-checks.yml   # Validates environment
+│   ├── 02-system-setup.yml       # Packages & security
+│   ├── 03-docker-setup.yml       # Docker installation
+│   ├── 04-tailscale-setup.yml    # VPN setup
+│   ├── 05-deploy-stack.yml       # Main deployment
+│   ├── 06-configure-caddy.yml    # SSL & reverse proxy
+│   ├── 07-setup-backups.yml      # Backup automation
+│   ├── 08-post-deployment.yml    # Verification
+│   └── 99-rollback.yml           # Emergency rollback
+├── roles/                         # Templates & configs
+│   ├── nextcloud_stack/
+│   │   └── templates/
+│   │       ├── docker-compose.yml.j2  # 12-service stack
+│   │       └── env.j2                 # Environment vars
+│   └── caddy/
+│       └── templates/
+│           └── Caddyfile.j2           # Reverse proxy config
+└── docs/                          # You are here!
+```
+
+---
+
+## 🎓 Common Commands
+
+After setup, you'll use these frequently:
+
+```bash
+make deploy        # Deploy everything
+make status        # Check container status
+make logs          # View all logs
+make backup        # Run manual backup
+make restart       # Restart all containers
+make edit-vault    # Edit encrypted secrets
+```
+
+---
+
+## 📞 Need Help?
+
+1. **Common Issues**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+2. **Backup/Restore**: [BACKUP_RESTORE.md](BACKUP_RESTORE.md)
+3. **Full Documentation**: [README.md](README.md)
+
+---
+
+## ⚡ 30-Second Overview
+
+This project automates deploying a complete self-hosted productivity stack:
+
+1. **Configure once**: `./setup.sh` collects all info
+2. **Deploy anywhere**: `make deploy` to any Ubuntu server
+3. **Use immediately**: Access via `https://cloud.yourdomain.com`
+
+**Time to deploy:** 30-45 minutes (mostly automatic)
+
+---
+
+## 🎯 Recommended First Steps
+
+### For Complete Beginners
+1. Read [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)
+2. Configure DNS for your domain
+3. Run `./setup.sh` on your laptop
+4. Run `make deploy` and wait
+5. Access your new Nextcloud!
+
+### For Experienced Users
+1. Skim [README.md](README.md) to understand the stack
+2. Review [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) for architecture
+3. Run `./setup.sh` and `make deploy`
+4. Review generated configs in `/opt/nextcloud-stack/`
+
+### For Developers
+1. Read [AGENTS.md](AGENTS.md) for development guidelines
+2. Review playbooks in `playbooks/` directory
+3. Check templates in `roles/*/templates/`
+4. Customize as needed for your use case
+
+---
+
+## 🌟 What Makes This Special?
+
+- **User-friendly**: Interactive setup, no manual config editing
+- **Secure**: Ansible Vault, firewalls, Tailscale, automatic updates
+- **Complete**: Monitoring, backups, SSL, documentation included
+- **Production-ready**: Tested deployment procedures, rollback capability
+- **Maintainable**: Clean code, comprehensive docs, modular design
+
+---
+
+## 🚦 Ready to Begin?
+
+**New users**: Start with [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)
+
+**Quick reference**: See [README.md](README.md)
+
+**Technical details**: Check [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)
+
+---
+
+**Let's build your self-hosted cloud! 🚀**