If you’ve been struggling with large file uploads in Nextcloud, especially when using it in a Docker container on Unraid, this guide will help you configure Nextcloud, NGINX, PHP, and HAProxy to handle large file uploads efficiently. This post walks through the common causes and solutions for file upload limits, timeout issues, and general troubleshooting tips to ensure your Nextcloud setup can handle large files without a hitch.

Common Issue: Large File Uploads Failing

When attempting to upload large files, you may run into errors like:

  • 413 Request Entity Too Large
  • 504 Gateway Time-out
  • Files uploading, then disappearing
  • Timeout issues or slow performance for large uploads

These errors can be caused by misconfigurations in NGINX, PHP, or HAProxy when proxying requests. Let’s fix that.

TL;DR

# nextcloud/nginx/nginx.conf
http {
    client_max_body_size 100G;
    proxy_read_timeout 3600s;
    proxy_buffering off;
}

# nextcloud/nginx/site-confs/default.conf
server {
    fastcgi_buffers 64 4K;

    client_max_body_size 100G;
    client_body_timeout 3600s;

    # Increase proxy timeouts
    proxy_connect_timeout 3600s;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    fastcgi_read_timeout 3600s;
}

# nextcloud/php/php-local.ini
upload_max_filesize = 100G
post_max_size = 100G
max_input_time = 3600
max_execution_time = 3600
memory_limit = 15G

Step 1: Adjusting NGINX Configuration for Large File Uploads

NGINX often imposes limits on file sizes and timeouts by default. To resolve the issue, you’ll need to modify your NGINX configuration.

Directory Structure on Unraid (Nextcloud Docker, Unraid)

If you’re using Nextcloud in a Docker container on Unraid, you can find NGINX and PHP configurations in your appdata folder, typically at:

<code>/mnt/cache/appdata/nextcloud/nginx

Edit NGINX Configuration

  1. Locate NGINX Config: Typically, this file will be nginx.conf or might be in the site-confs/ directory depending on your setup.
  2. Add or Modify the Following Settings:
  3. client_max_body_size 100G; client_body_timeout 3600s; send_timeout 3600s; fastcgi_buffers 64 4K;
    • client_max_body_size sets the maximum allowed file size for uploads. In this case, it’s set to 100GB.
    • client_body_timeout increases the time NGINX will wait for file uploads.
    • send_timeout prevents NGINX from timing out when sending data.
    • fastcgi_buffers improves the buffer size for handling larger requests.
  4. Apply Changes: Restart NGINX after making these changes. You can do this from within the container using:
  5. codenginx -s reload
client_max_body_size 100G;
client_body_timeout 3600s;
send_timeout 3600s;
fastcgi_buffers 64 4K;

Step 2: Configuring PHP for Large Uploads

PHP also has built-in limits for handling uploads. You need to adjust the following settings:

  1. Locate PHP Config (php-local.ini):
  2. /mnt/cache/appdata/nextcloud/php/php-local.ini
  3. Modify These Settings: upload_max_filesize = 100G post_max_size = 100G max_execution_time = 3600 memory_limit = 512M
    • upload_max_filesize and post_max_size control the maximum allowed file size (set to 100GB in this example).
    • max_execution_time prevents the script from timing out during long uploads.
    • memory_limit defines the maximum memory PHP is allowed to use.
  4. Apply Changes: Restart PHP by restarting the Docker container or reload PHP inside the container if needed.
upload_max_filesize = 100G
post_max_size = 100G
max_execution_time = 3600
memory_limit = 512M

Step 3: Adjusting HAProxy Settings for Large File Transfers

If you’re using HAProxy as a load balancer or reverse proxy in pfSense, you’ll need to adjust some settings to ensure it can handle large file uploads. HAProxy has its own buffers and timeout limits that can cause issues if not configured correctly.

  1. Key HAProxy Settings:
    • Tune Buffers: tune.bufsize 65536 This increases the buffer size to accommodate larger requests.
    • Timeouts:
    • timeout client 3600s timeout server 3600s timeout connect 5000ms
    • These timeouts are essential for allowing longer uploads without dropping the connection.
  2. Apply Changes in pfSense:
    • You can apply these settings in pfSense by navigating to Services > HAProxy and adjusting these parameters in the global section and frontend/backend configurations.
    Important: If you’re still facing issues with “Entity Too Large” errors or timeout issues, ensure that HAProxy isn’t limiting body size. Some users have reported that tweaking tune.bufsize and timeout values resolved upload problems.
timeout client 3600s
timeout server 3600s
timeout connect 5000ms

Step 4: Testing Your Configuration

Once you’ve made these changes, you’ll want to test uploading large files:

  1. Test Uploads:
    • Try uploading large files (e.g., 5GB or 10GB) directly to the local IP address of your Nextcloud instance first. This bypasses any external proxies like HAProxy or Cloudflare.
    • If the file uploads successfully, test the upload via your domain (e.g., nextcloud.example.com).
  2. Troubleshooting Tips:
    • If the file uploads to your local IP but fails via HAProxy, the issue is likely with HAProxy’s buffer or timeout settings.
    • If the file appears to upload but is deleted after reaching the final stage, check for proxy timeouts and fastcgi settings.
  3. Monitoring Logs:
    • Always check your NGINX, PHP, and HAProxy logs for clues on what’s going wrong. Common errors include:
      • 413 Request Entity Too Large in NGINX.
      • 504 Gateway Timeout from HAProxy.

Conclusion: Optimizing Large File Uploads in Nextcloud on Unraid

By following the steps outlined in this guide, you can effectively handle large file uploads in Nextcloud. From adjusting NGINX and PHP configurations to tuning HAProxy for larger requests, these settings will help you avoid common file upload issues. Make sure to test your setup thoroughly, monitor logs, and adjust timeouts and buffers as necessary.

If you’ve tried everything and still face issues, ensure you’re not facing file system-level restrictions or bandwidth bottlenecks on your network.

By taking these steps, you should have a stable and scalable Nextcloud instance capable of handling large uploads without interruptions.