Reorganize troubleshooting documentation

- Move existing troubleshooting.md to docs/troubleshooting/ folder - Add comprehensive WebDAV copyparty troubleshooting guide - Document nginx 301 redirect issues and solutions - Include debugging methodology and working configurations - Add future troubleshooting commands and client settings 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-19 19:40:34 +02:00
parent a1d7128a41
commit ffca3cb751
2 changed files with 331 additions and 0 deletions
--- a/docs/troubleshooting/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
+```
--- a/docs/troubleshooting/webdav-copyparty.md
+++ 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
+```