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)

./setup.sh

Answer the questions about your servers and preferences. This generates your encrypted configuration.

Step 2: Deploy (30-45 minutes per server)

make deploy

Or manually:

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:

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:

sudo apt update
sudo apt install ansible

macOS:

brew install ansible

Verify:

ansible --version
# Should be 2.14 or higher

2. Clone Repository

git clone <your-repo-url>
cd ansible-nextcloud-deployment

3. Run Interactive Setup

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

make ping

Or:

ansible all -m ping --ask-vault-pass

Expected output:

server-hostname | SUCCESS => {
    "ping": "pong"
}

5. Run Deployment

make deploy

Or manually:

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)

ssh user@server
sudo tailscale up

Test Backups

make backup

Or on the server:

ssh user@server
/opt/nextcloud-stack/backup.sh

Check Service Status

make status

Or on the server:

ssh user@server
cd /opt/nextcloud-stack
docker compose ps

View Logs

make logs

Or on the server:

ssh user@server
cd /opt/nextcloud-stack
docker compose logs -f

---

🎓 Learning Ansible Commands

Useful Makefile Shortcuts

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

# 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

dig +short cloud.yourdomain.com

LXC Container Issues

Symptom: Docker won't start

Solution (on LXC host):

lxc config set CONTAINER_NAME security.nesting true
lxc restart CONTAINER_NAME

Port Already in Use

Symptom: Caddy fails to start

Solution:

sudo systemctl stop apache2
sudo systemctl stop nginx

Full troubleshooting guide:

See TROUBLESHOOTING.md

---

📚 Additional Documentation

• README.md - Complete project overview
• TROUBLESHOOTING.md - Common issues and solutions
• BACKUP_RESTORE.md - Backup and restore procedures
• 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:

   docker compose logs [service-name]
   

2. Deployment report:

   cat /opt/nextcloud-stack/DEPLOYMENT.txt
   

3. System status:

   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

Last Updated: 2026-02-16