# 👋 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! 🚀**