added ansible script
This commit is contained in:
liph
470
ansible/DEPLOYMENT_GUIDE.md
Normal file
470
ansible/DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,470 @@
|
||||
# Quick Deployment Guide
|
||||
|
||||
Get your Nextcloud Stack running in under an hour!
|
||||
|
||||
## ⚡ Quick Start (3 Steps)
|
||||
|
||||
### Step 1: Configure (5-10 minutes)
|
||||
|
||||
```bash
|
||||
./setup.sh
|
||||
```
|
||||
|
||||
Answer the questions about your servers and preferences. This generates your encrypted configuration.
|
||||
|
||||
### Step 2: Deploy (30-45 minutes per server)
|
||||
|
||||
```bash
|
||||
make deploy
|
||||
```
|
||||
|
||||
Or manually:
|
||||
```bash
|
||||
ansible-playbook playbooks/site.yml --ask-vault-pass
|
||||
```
|
||||
|
||||
### Step 3: Access Your Services
|
||||
|
||||
- **Nextcloud**: `https://cloud.yourdomain.com`
|
||||
- **OnlyOffice**: `https://office.yourdomain.com`
|
||||
- **Excalidraw**: `https://draw.yourdomain.com`
|
||||
- **Obsidian**: `https://notes.yourdomain.com`
|
||||
|
||||
**Management (Tailscale only)**:
|
||||
- **Homarr Dashboard**: `https://home.yourdomain.com`
|
||||
- **Dockhand**: `https://manage.yourdomain.com`
|
||||
- **Uptime Kuma**: `https://uptime.yourdomain.com`
|
||||
|
||||
---
|
||||
|
||||
## 📋 Prerequisites Checklist
|
||||
|
||||
### Before You Begin
|
||||
|
||||
- [ ] Ubuntu 20.04+ server (LXC or VPS)
|
||||
- [ ] Root or sudo access
|
||||
- [ ] Minimum 100GB disk space
|
||||
- [ ] Ansible 2.14+ on your control machine
|
||||
- [ ] Domain name with DNS access
|
||||
|
||||
### DNS Configuration (CRITICAL!)
|
||||
|
||||
Before deployment, create these A records pointing to your server IP:
|
||||
|
||||
```
|
||||
cloud.yourdomain.com → YOUR_SERVER_IP
|
||||
office.yourdomain.com → YOUR_SERVER_IP
|
||||
draw.yourdomain.com → YOUR_SERVER_IP
|
||||
notes.yourdomain.com → YOUR_SERVER_IP
|
||||
home.yourdomain.com → YOUR_SERVER_IP
|
||||
manage.yourdomain.com → YOUR_SERVER_IP
|
||||
uptime.yourdomain.com → YOUR_SERVER_IP
|
||||
```
|
||||
|
||||
**Verify DNS before deployment:**
|
||||
```bash
|
||||
dig +short cloud.yourdomain.com
|
||||
# Should return: YOUR_SERVER_IP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What Gets Deployed
|
||||
|
||||
### 12 Services
|
||||
|
||||
| Service | Purpose | Auto-Update |
|
||||
|---------|---------|-------------|
|
||||
| **Nextcloud** | File sync & collaboration | ❌ Manual |
|
||||
| **PostgreSQL 18** | Database | ❌ Manual |
|
||||
| **Redis 7** | Cache | ❌ Manual |
|
||||
| **OnlyOffice** | Document editor | 👁️ Monitor |
|
||||
| **Excalidraw** | Whiteboard | ✅ Auto |
|
||||
| **Obsidian** | Notes | ✅ Auto |
|
||||
| **Caddy** | Reverse proxy + SSL | ✅ Auto |
|
||||
| **Homarr** | Dashboard | ✅ Auto |
|
||||
| **Dockhand** | Container manager | ✅ Auto |
|
||||
| **Uptime Kuma** | Monitoring | ✅ Auto |
|
||||
| **Watchtower** | Auto-updater | N/A |
|
||||
|
||||
### Security Features
|
||||
|
||||
- ✅ UFW firewall configured
|
||||
- ✅ Fail2ban for SSH protection
|
||||
- ✅ Automatic SSL certificates (Let's Encrypt)
|
||||
- ✅ Ansible Vault encrypted secrets
|
||||
- ✅ Tailscale-only admin interfaces
|
||||
- ✅ Automatic security updates
|
||||
|
||||
### Backup System
|
||||
|
||||
- **Daily**: Database backups (3:00 AM)
|
||||
- **Weekly**: Volume backups (Sundays)
|
||||
- **Retention**: 30 days
|
||||
- **Location**: `/opt/nextcloud-stack/backups/`
|
||||
|
||||
---
|
||||
|
||||
## 📝 Detailed Setup Process
|
||||
|
||||
### 1. Install Ansible (Control Machine)
|
||||
|
||||
**Ubuntu/Debian:**
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install ansible
|
||||
```
|
||||
|
||||
**macOS:**
|
||||
```bash
|
||||
brew install ansible
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
ansible --version
|
||||
# Should be 2.14 or higher
|
||||
```
|
||||
|
||||
### 2. Clone Repository
|
||||
|
||||
```bash
|
||||
git clone <your-repo-url>
|
||||
cd ansible-nextcloud-deployment
|
||||
```
|
||||
|
||||
### 3. Run Interactive Setup
|
||||
|
||||
```bash
|
||||
chmod +x setup.sh
|
||||
./setup.sh
|
||||
```
|
||||
|
||||
**You'll be asked for:**
|
||||
|
||||
1. **Server Details** (for each server):
|
||||
- IP address
|
||||
- Hostname
|
||||
- Domain (e.g., `example.com`)
|
||||
- SSH user
|
||||
- SSH key path
|
||||
|
||||
2. **User Information**:
|
||||
- Your name
|
||||
- Your email (for SSL certificates)
|
||||
- Timezone
|
||||
|
||||
3. **Admin Account**:
|
||||
- Nextcloud admin username
|
||||
- Nextcloud admin password
|
||||
|
||||
4. **Subdomain Preferences** (defaults shown):
|
||||
- Nextcloud: `cloud`
|
||||
- OnlyOffice: `office`
|
||||
- Excalidraw: `draw`
|
||||
- Obsidian: `notes`
|
||||
- Homarr: `home`
|
||||
- Dockhand: `manage`
|
||||
- Uptime Kuma: `uptime`
|
||||
|
||||
5. **Tailscale** (optional):
|
||||
- Auth key (or skip for manual activation)
|
||||
|
||||
6. **Monitoring**:
|
||||
- Alert email
|
||||
- Public status page (yes/no)
|
||||
|
||||
7. **Backups**:
|
||||
- Install rclone (yes/no)
|
||||
|
||||
8. **Ansible Vault Password**:
|
||||
- Create a password to encrypt secrets
|
||||
|
||||
**Output:**
|
||||
- `inventory/hosts.yml` - Server inventory
|
||||
- `inventory/group_vars/all/vars.yml` - Public variables
|
||||
- `inventory/group_vars/all/vault.yml` - Encrypted secrets
|
||||
|
||||
### 4. Test Connectivity
|
||||
|
||||
```bash
|
||||
make ping
|
||||
```
|
||||
|
||||
Or:
|
||||
```bash
|
||||
ansible all -m ping --ask-vault-pass
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
server-hostname | SUCCESS => {
|
||||
"ping": "pong"
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Run Deployment
|
||||
|
||||
```bash
|
||||
make deploy
|
||||
```
|
||||
|
||||
Or manually:
|
||||
```bash
|
||||
ansible-playbook playbooks/site.yml --ask-vault-pass
|
||||
```
|
||||
|
||||
**What happens** (30-45 minutes):
|
||||
|
||||
1. ✅ **Preflight Checks** (2 min)
|
||||
- Validates DNS, connectivity, disk space
|
||||
|
||||
2. ⚙️ **System Setup** (10-15 min)
|
||||
- Installs packages
|
||||
- Configures firewall (UFW)
|
||||
- Sets up fail2ban
|
||||
|
||||
3. 🐳 **Docker Setup** (5 min)
|
||||
- Removes old Docker
|
||||
- Installs Docker CE + Compose v2
|
||||
|
||||
4. 🔐 **Tailscale** (2 min)
|
||||
- Installs Tailscale
|
||||
- Activates if auth key provided
|
||||
|
||||
5. 📦 **Deploy Stack** (10-15 min)
|
||||
- Templates configuration files
|
||||
- Pulls Docker images
|
||||
- Starts all containers
|
||||
- Initializes Nextcloud
|
||||
|
||||
6. 🌐 **Configure Caddy** (2-5 min)
|
||||
- Validates configuration
|
||||
- Obtains SSL certificates
|
||||
|
||||
7. 💾 **Setup Backups** (2 min)
|
||||
- Creates backup script
|
||||
- Sets up cron jobs
|
||||
|
||||
8. ✅ **Post-Deployment** (5 min)
|
||||
- Verifies all services
|
||||
- Installs Nextcloud apps
|
||||
- Creates deployment report
|
||||
|
||||
### 6. Access Your Services
|
||||
|
||||
**Immediately after deployment:**
|
||||
|
||||
1. **Nextcloud**: `https://cloud.yourdomain.com`
|
||||
- Login with admin credentials from setup
|
||||
|
||||
2. **Setup Uptime Kuma** (via Tailscale):
|
||||
- `https://uptime.yourdomain.com`
|
||||
- Create admin account on first visit
|
||||
- Add monitors for your services
|
||||
|
||||
3. **Configure Homarr** (via Tailscale):
|
||||
- `https://home.yourdomain.com`
|
||||
- Add service tiles
|
||||
- Customize dashboard
|
||||
|
||||
4. **OnlyOffice Integration**:
|
||||
- Nextcloud → Settings → Administration → Office
|
||||
- Document Server: `https://office.yourdomain.com`
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Post-Deployment Tasks
|
||||
|
||||
### Activate Tailscale (if not done automatically)
|
||||
|
||||
```bash
|
||||
ssh user@server
|
||||
sudo tailscale up
|
||||
```
|
||||
|
||||
### Test Backups
|
||||
|
||||
```bash
|
||||
make backup
|
||||
```
|
||||
|
||||
Or on the server:
|
||||
```bash
|
||||
ssh user@server
|
||||
/opt/nextcloud-stack/backup.sh
|
||||
```
|
||||
|
||||
### Check Service Status
|
||||
|
||||
```bash
|
||||
make status
|
||||
```
|
||||
|
||||
Or on the server:
|
||||
```bash
|
||||
ssh user@server
|
||||
cd /opt/nextcloud-stack
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
make logs
|
||||
```
|
||||
|
||||
Or on the server:
|
||||
```bash
|
||||
ssh user@server
|
||||
cd /opt/nextcloud-stack
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Learning Ansible Commands
|
||||
|
||||
### Useful Makefile Shortcuts
|
||||
|
||||
```bash
|
||||
make help # Show all commands
|
||||
make ping # Test connectivity
|
||||
make check # Run preflight checks only
|
||||
make deploy # Full deployment
|
||||
make deploy-dry # Test without making 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
|
||||
```
|
||||
|
||||
### Direct Ansible Commands
|
||||
|
||||
```bash
|
||||
# Run specific playbook
|
||||
ansible-playbook playbooks/01-preflight-checks.yml --ask-vault-pass
|
||||
|
||||
# Run on specific server
|
||||
ansible-playbook playbooks/site.yml --limit server1 --ask-vault-pass
|
||||
|
||||
# Dry run (no changes)
|
||||
ansible-playbook playbooks/site.yml --ask-vault-pass --check
|
||||
|
||||
# View inventory
|
||||
ansible-inventory --list
|
||||
|
||||
# Run ad-hoc command
|
||||
ansible all -m shell -a "docker ps" --ask-vault-pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Troubleshooting
|
||||
|
||||
### DNS Not Configured
|
||||
|
||||
**Symptom**: Let's Encrypt fails
|
||||
|
||||
**Solution**: Ensure all DNS A records point to server IP
|
||||
```bash
|
||||
dig +short cloud.yourdomain.com
|
||||
```
|
||||
|
||||
### LXC Container Issues
|
||||
|
||||
**Symptom**: Docker won't start
|
||||
|
||||
**Solution** (on LXC host):
|
||||
```bash
|
||||
lxc config set CONTAINER_NAME security.nesting true
|
||||
lxc restart CONTAINER_NAME
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
**Symptom**: Caddy fails to start
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
sudo systemctl stop apache2
|
||||
sudo systemctl stop nginx
|
||||
```
|
||||
|
||||
### Full troubleshooting guide:
|
||||
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Additional Documentation
|
||||
|
||||
- [README.md](README.md) - Complete project overview
|
||||
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions
|
||||
- [BACKUP_RESTORE.md](BACKUP_RESTORE.md) - Backup and restore procedures
|
||||
- [AGENTS.md](AGENTS.md) - Development guidelines
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security Best Practices
|
||||
|
||||
### After Deployment
|
||||
|
||||
1. **Change default passwords** (if you used simple ones during testing)
|
||||
2. **Enable 2FA** in Nextcloud
|
||||
3. **Review firewall rules**: `sudo ufw status`
|
||||
4. **Check fail2ban**: `sudo fail2ban-client status sshd`
|
||||
5. **Verify SSL certificates**: Visit all your domains in browser
|
||||
6. **Test backups**: Ensure they're working
|
||||
7. **Setup monitoring alerts** in Uptime Kuma
|
||||
|
||||
### Ongoing Maintenance
|
||||
|
||||
- **Weekly**: Check Uptime Kuma for service health
|
||||
- **Monthly**: Test backup restore
|
||||
- **Quarterly**: Review security updates
|
||||
- **Annually**: Rotate passwords
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Getting Help
|
||||
|
||||
1. **Check logs:**
|
||||
```bash
|
||||
docker compose logs [service-name]
|
||||
```
|
||||
|
||||
2. **Deployment report:**
|
||||
```bash
|
||||
cat /opt/nextcloud-stack/DEPLOYMENT.txt
|
||||
```
|
||||
|
||||
3. **System status:**
|
||||
```bash
|
||||
docker compose ps
|
||||
sudo systemctl status docker
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Success Checklist
|
||||
|
||||
After deployment, verify:
|
||||
|
||||
- [ ] All containers running: `docker compose ps`
|
||||
- [ ] Nextcloud accessible via HTTPS
|
||||
- [ ] SSL certificate valid (green padlock in browser)
|
||||
- [ ] Can login to Nextcloud
|
||||
- [ ] OnlyOffice integration working
|
||||
- [ ] Uptime Kuma showing all services green
|
||||
- [ ] Homarr dashboard accessible
|
||||
- [ ] Backup script runs successfully
|
||||
- [ ] Tailscale connected (if using)
|
||||
|
||||
---
|
||||
|
||||
**You're all set! Enjoy your self-hosted Nextcloud stack! 🎉**
|
||||
|
||||
For questions or issues, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||||
|
||||
**Last Updated:** 2026-02-16
|
||||
Reference in New Issue
Block a user