193 lines
6.2 KiB
Markdown
193 lines
6.2 KiB
Markdown
# 👋 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! 🚀**
|