Add homelab service troubleshooting guide

- Document SSL certificate restoration after nginx updates
- Add WebDAV 301 error diagnosis and resolution
- Include media file sync troubleshooting between copyparty and Jellyfin
- Add service deployment best practices
- Provide step-by-step solutions for common configuration issues

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/troubleshooting.md

@@ -310,3 +310,108 @@ Due to 3 interfaces:
 
   This way both your ethernet (enp4s0) and WiFi will use 192.168.0.100, solving your dual interface IP issue.
   Ready to run these commands?
+
+# Homelab Service Issues
+
+## SSL Certificate Breaks After Nginx Updates
+
+**Issue:** HTTPS stops working after deploying nginx configuration changes from the repo.
+
+**Root cause:** Certbot modifies the deployed nginx configuration directly (adding SSL blocks), but the repo only contains the base HTTP configuration. When deploying from repo, it overwrites certbot's SSL additions.
+
+**Solution:**
+```bash
+# 1. Re-run certbot to restore SSL configuration
+sudo certbot --nginx -d ak-homelab.duckdns.org --non-interactive
+
+# 2. Copy complete config (with SSL blocks) back to repo
+sudo cp /etc/nginx/sites-available/homelab config/nginx/homelab.conf
+
+# 3. Commit updated config to prevent future issues
+git add config/nginx/homelab.conf
+git commit -m "Update nginx config with SSL configuration from certbot"
+```
+
+**Prevention:** Always copy deployed configurations back to repo after certbot runs to preserve SSL blocks.
+
+## WebDAV Upload Error 301 (Moved Permanently)
+
+**Issue:** WebDAV clients (X-plore, rclone) get HTTP 301 redirect errors when uploading files, even though browsing works fine.
+
+**Root cause:** Nginx reverse proxy missing WebDAV-specific headers needed for upload operations.
+
+**Solution:** Ensure nginx configuration includes WebDAV headers:
+```nginx
+location /files/ {
+    proxy_pass http://127.0.0.1:8082/files/;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    
+    # WebDAV specific headers (REQUIRED for uploads)
+    proxy_set_header Depth $http_depth;
+    proxy_set_header Destination $http_destination;
+    proxy_set_header Overwrite $http_overwrite;
+    proxy_set_header If $http_if;
+    
+    proxy_request_buffering off;
+}
+```
+
+**WebDAV Client Settings (X-plore):**
+- URL: `https://ak-homelab.duckdns.org/files/` 
+- Username: `hoborg`
+- Password: `AdminPass2024!`
+- Port: 443 (HTTPS)
+
+## Media Files Not Syncing Between Copyparty and Jellyfin
+
+**Issue:** Files uploaded to Copyparty don't appear in Jellyfin media library.
+
+**Root cause:** Volume mount mismatch or Jellyfin not scanning new files.
+
+**Troubleshooting:**
+```bash
+# 1. Verify volume mounts match
+# Copyparty config: /home/hoborg/private -> /private
+# Jellyfin config: /home/hoborg/private:/media/private:ro
+
+# 2. Check file permissions
+ls -la /home/hoborg/private/
+# Files should be readable by user 1000:1000
+
+# 3. Force Jellyfin library rescan
+docker exec jellyfin curl -X POST "http://localhost:8096/Library/Refresh"
+
+# 4. Check Jellyfin logs
+docker-compose -f /opt/docker/jellyfin/docker-compose.yml logs jellyfin
+```
+
+## Service Deployment Best Practices
+
+**To avoid common issues:**
+
+1. **Always test nginx before reload:**
+```bash
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+2. **Backup configs before changes:**
+```bash
+sudo cp /etc/nginx/sites-available/homelab /etc/nginx/sites-available/homelab.backup
+```
+
+3. **Use temporary scripts for multiple sudo commands:**
+```bash
+# Create script with all commands, then run once with sudo
+echo "command1; command2; command3" > /tmp/deploy.sh
+chmod +x /tmp/deploy.sh
+sudo -A /tmp/deploy.sh
+```
+
+4. **Monitor service logs after changes:**
+```bash
+sudo systemctl status nginx copyparty
+docker-compose -f /opt/docker/jellyfin/docker-compose.yml logs --tail 50
+```