dotfiles_arch/ansible/DEPLOYMENT_GUIDE.md

# 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