diff --git a/docs/troubleshooting.md b/docs/troubleshooting/troubleshooting.md similarity index 75% rename from docs/troubleshooting.md rename to docs/troubleshooting/troubleshooting.md index b381995..e68fd9d 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting/troubleshooting.md @@ -313,6 +313,71 @@ Due to 3 interfaces: # Homelab Service Issues +## Landing Page Returns 404 Not Found + +**Issue:** Landing page at `https://ak-homelab.duckdns.org/` returns 404 Not Found despite nginx running and other services working. + +**Symptoms:** +- Landing page returns 404 Not Found +- Nginx logs show attempts to access `/etc/nginx/html/index.html` instead of `/var/www/homelab/index.html` +- Custom 404 pages work but main index doesn't load +- Services like `/gitea/`, `/files/`, `/media/` work correctly + +**Root Cause:** +1. Default server block in `/etc/nginx/nginx.conf` conflicted with homelab configuration +2. Missing `default_server` directive in homelab server blocks +3. Incorrect location block (`location = /` vs `location /`) +4. Nginx not properly reloading configuration changes + +**Resolution Steps:** +```bash +# 1. Comment out default server block in nginx.conf +sudo nano /etc/nginx/nginx.conf +# Comment out the entire server { listen 80; server_name localhost; ... } block + +# 2. Add default_server directives to homelab config +sudo nano /etc/nginx/sites-available/homelab +# Change to: listen 80 default_server; and listen 443 ssl default_server; +# Add server_name ak-homelab.duckdns.org _; (underscore catches all) + +# 3. Fix location block for root path +# Change from: location = / { ... } +# Change to: location / { root /var/www/homelab; index index.html; try_files $uri $uri/ =404; } + +# 4. Add custom error pages to prevent fallback +# Add: error_page 404 /404.html; +# location = /404.html { root /var/www/homelab; internal; } + +# 5. Test and restart (reload may not be sufficient) +sudo nginx -t +sudo systemctl restart nginx # Use restart, not reload + +# 6. Verify file permissions +sudo ls -la /var/www/homelab/index.html +# Should be readable by nginx user (http) +``` + +**Verification Commands:** +```bash +# Test HTTP redirect +curl -I http://192.168.0.100/ + +# Test HTTPS access +curl -I https://ak-homelab.duckdns.org/ --insecure + +# Check active nginx configuration +sudo nginx -T | grep -A10 "server_name ak-homelab" + +# Monitor real-time nginx logs +sudo journalctl -u nginx -f +``` + +**Final Working Configuration:** +- HTTP redirects properly to HTTPS (301 redirect) +- HTTPS returns 200 OK with full landing page HTML +- Security headers present (X-Frame-Options, X-Content-Type-Options, X-XSS-Protection) +- Custom error handling prevents fallback to default nginx errors + ## SSL Certificate Breaks After Nginx Updates **Issue:** HTTPS stops working after deploying nginx configuration changes from the repo. @@ -415,3 +480,66 @@ sudo -A /tmp/deploy.sh sudo systemctl status nginx copyparty docker-compose -f /opt/docker/jellyfin/docker-compose.yml logs --tail 50 ``` + +## Configuration Debugging Commands + +### Nginx Configuration Analysis +```bash +# Show all active server blocks +sudo nginx -T | grep -A50 "server {" + +# Find all nginx config files +sudo find /etc/nginx -name "*.conf" -exec grep -l "server_name\|listen.*80\|listen.*443" {} \; + +# Check which server block is handling requests +sudo nginx -T | grep -A20 "location = /" + +# Verify sites-enabled vs sites-available +sudo ls -la /etc/nginx/sites-enabled/ +sudo ls -la /etc/nginx/sites-available/ + +# Test nginx config without reloading +sudo nginx -t +``` + +### File Permissions and Access +```bash +# Check file permissions for web content +sudo ls -la /var/www/homelab/ +sudo -u http ls -la /var/www/homelab/ # Test as nginx user + +# Check SSL certificate access +sudo ls -la /etc/letsencrypt/live/ak-homelab.duckdns.org/ + +# Verify configuration deployment +diff /home/hoborg/homelab/config/nginx/homelab.conf /etc/nginx/sites-available/homelab +``` + +### Real-time Debugging +```bash +# Monitor nginx logs in real-time +sudo journalctl -u nginx -f + +# Monitor nginx logs since specific time +sudo journalctl -u nginx --since "10 minutes ago" + +# Test with verbose curl output +curl -v https://ak-homelab.duckdns.org/ --insecure + +# Check nginx worker processes +ps aux | grep nginx +``` + +### Service Status Verification +```bash +# Check all homelab services at once +sudo systemctl status nginx copyparty +docker-compose -f /opt/docker/gitea/docker-compose.yml ps +docker-compose -f /opt/docker/jellyfin/docker-compose.yml ps + +# Quick connectivity test for all services +curl -I https://ak-homelab.duckdns.org/ # Landing page +curl -I https://ak-homelab.duckdns.org/gitea/ # Gitea +curl -I https://ak-homelab.duckdns.org/files/ # Copyparty +curl -I https://ak-homelab.duckdns.org/media/ # Jellyfin +``` diff --git a/docs/troubleshooting/webdav-copyparty.md b/docs/troubleshooting/webdav-copyparty.md new file mode 100644 index 0000000..e1dcab4 --- /dev/null +++ b/docs/troubleshooting/webdav-copyparty.md @@ -0,0 +1,203 @@ +# WebDAV Copyparty Troubleshooting Guide + +This document captures the issues encountered and solutions found while setting up WebDAV with copyparty behind an nginx reverse proxy. + +## Initial Problem + +WebDAV clients (X-plore File Manager) could browse folders but could not upload files, receiving HTTP 301 redirects instead of successful uploads. + +## Root Causes Identified + +### 1. Nginx Automatic Redirects +**Problem**: Nginx was automatically adding trailing slashes and performing internal redirects that broke WebDAV PUT requests. + +**Symptoms**: +- PROPFIND (directory listing) worked: `HTTP/1.1 207 Multi-Status` +- PUT (file upload) failed: `HTTP/1.1 301 Moved Permanently` +- Web interface worked normally +- Direct curl uploads worked through nginx + +**Solution**: Disable nginx automatic redirects: +```nginx +server { + # Critical: Disable automatic redirects for WebDAV + merge_slashes off; + + location ~ ^/files(/.*)?$ { + # Critical: Disable nginx response modifications + proxy_redirect off; + } +} +``` + +### 2. Copyparty Permissions +**Problem**: Copyparty required explicit delete permissions for WebDAV DELETE operations. + +**Symptoms**: +- File uploads worked after nginx fix +- File deletions failed: `'delete' not allowed for user hoborg` +- Error: `HTTP/1.1 403 Forbidden` + +**Solution**: Add `d` (delete) permission to user accounts: +```ini +[/shared] + /home/hoborg/shared + accs: + rw: guest + rwmd: hoborg # Changed from 'rwm' to 'rwmd' +``` + +**Copyparty Permission Flags**: +- `r` (read): List folders, download files +- `w` (write): Upload files +- `m` (move): Move/rename files and folders +- `d` (delete): Permanently delete files and folders +- `a` (admin): See uploader IPs, config reload + +## Debugging Process + +### Step 1: Isolate the Problem +Test direct copyparty connection vs nginx proxy: + +```bash +# Test direct copyparty (bypassing nginx) +curl -X PUT "http://127.0.0.1:8082/files/shared/test.txt" \ + -u "hoborg:password" -d "test content" -v + +# Test through nginx proxy +curl -X PUT "https://ak-homelab.duckdns.org/files/shared/test.txt" \ + -u "hoborg:password" -d "test content" -v +``` + +**Result**: Direct copyparty worked, nginx proxy returned 301 → nginx issue + +### Step 2: Monitor Logs +Check what HTTP methods are actually reaching copyparty: + +```bash +# Monitor copyparty logs in real-time +sudo journalctl -u copyparty -f + +# Monitor nginx access logs +sudo tail -f /var/log/nginx/access.log +``` + +**Finding**: X-plore PUT requests never reached copyparty logs → nginx blocking + +### Step 3: Test WebDAV Methods +```bash +# Test PROPFIND (directory listing) +curl -X PROPFIND "https://ak-homelab.duckdns.org/files/shared/" \ + -u "hoborg:password" -H "Depth: 1" -v + +# Test PUT (file upload) +curl -X PUT "https://ak-homelab.duckdns.org/files/shared/test.txt" \ + -u "hoborg:password" -d "test content" -v + +# Test DELETE (file deletion) +curl -X DELETE "https://ak-homelab.duckdns.org/files/shared/test.txt" \ + -u "hoborg:password" -v +``` + +## Final Working Configuration + +### Nginx Configuration (`/etc/nginx/sites-available/homelab`) +```nginx +server { + listen 443 ssl; + server_name ak-homelab.duckdns.org; + + # Critical: Disable automatic redirects for WebDAV + merge_slashes off; + + # Copyparty file server - WORKING WebDAV config + location ~ ^/files(/.*)?$ { + # Explicitly allow WebDAV methods + limit_except GET POST PUT DELETE PROPFIND PROPPATCH MKCOL COPY MOVE LOCK UNLOCK { deny all; } + + proxy_pass http://127.0.0.1:8082/files$1; + 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 + 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_set_header Lock-Token $http_lock_token; + + # Large file upload support + client_max_body_size 10G; + client_body_buffer_size 128k; + + # Upload timeout settings + proxy_connect_timeout 300s; + proxy_send_timeout 300s; + proxy_read_timeout 300s; + + # Critical: Streaming uploads for WebDAV + proxy_buffering off; + proxy_request_buffering off; + + # Critical: Disable nginx response modifications + proxy_redirect off; + } +} +``` + +### Copyparty Configuration (`~/.config/copyparty/copyparty.conf`) +```ini +[global] + i: 127.0.0.1 + p: 8082 + rp-loc: /files + rproxy: -1 + usernames + chpw + +[accounts] + hoborg: password + +[/shared] + /home/hoborg/shared + accs: + rwmd: hoborg # r=read, w=write, m=move, d=delete +``` + +## X-plore Client Settings +- **Server**: `ak-homelab.duckdns.org` +- **Path**: `/files/shared/` (or other folder paths) +- **Protocol**: HTTPS (port 443) +- **Username**: `hoborg` +- **Password**: [user password] + +## Key Lessons Learned + +1. **Nginx proxy_redirect off is critical** - Prevents nginx from modifying WebDAV responses +2. **merge_slashes off prevents automatic redirects** - Stops nginx from "fixing" WebDAV paths +3. **Copyparty needs explicit 'd' permission** - Delete operations require separate permission flag +4. **Test direct vs proxied connections** - Isolates nginx vs backend issues +5. **Monitor logs during troubleshooting** - Shows exactly what requests reach the backend + +## Commands for Future Troubleshooting + +```bash +# Test WebDAV connectivity +curl -X PROPFIND "https://ak-homelab.duckdns.org/files/shared/" \ + -u "username:password" -H "Depth: 1" -v + +# Monitor copyparty service +sudo journalctl -u copyparty -f + +# Check nginx configuration +sudo nginx -t +sudo systemctl reload nginx + +# Test file operations +curl -X PUT "https://ak-homelab.duckdns.org/files/shared/test.txt" \ + -u "username:password" -d "test" -v +curl -X DELETE "https://ak-homelab.duckdns.org/files/shared/test.txt" \ + -u "username:password" -v +```