How to configure Nextcloud behind a reverse proxy

Nextcloud uses request metadata to build login redirects, sharing links, WebDAV endpoints, and deployment warnings. When a public reverse proxy terminates TLS or changes the visible hostname before forwarding traffic to Nextcloud, the server must know which proxy address to trust and which public URL users actually reach.

The proxy should forward the public Host, X-Forwarded-For, and X-Forwarded-Proto values while discarding caller-supplied identity headers at the edge. Nextcloud only trusts forwarded values from addresses listed in trusted_proxies, so the entry belongs to the proxy source address as seen by the web server, not to a visitor address.

Configure the public hostname as a trusted domain, set the CLI URL and overwrite values to the external HTTPS URL, and keep subdirectory deployments explicit with overwritewebroot when the public path is not the site root. A request through the proxy and the Administration overview should show the public hostname and scheme without reverse-proxy or insecure-URL warnings.

1. Open a shell in the Nextcloud installation directory.

   $ cd /var/www/nextcloud

   Use the directory that contains the occ file. Common web-server installs use /var/www/nextcloud, while container images often use /var/www/html.

2. Add the public proxy hostname to trusted_domains.

   $ sudo -u www-data php occ config:system:set trusted_domains 1 --value=cloud.example.net
   System config value trusted_domains => 1 set to string cloud.example.net

   Use the next unused numeric index for the public hostname. Keep the old internal hostname if administrators still need it from the trusted network.
   Related: How to add a trusted domain in Nextcloud

3. Add the reverse proxy address to trusted_proxies.

   $ sudo -u www-data php occ config:system:set trusted_proxies 0 --value=10.0.0.10
   System config value trusted_proxies => 0 set to string 10.0.0.10

   Use the proxy address, subnet, or trusted load-balancer range that reaches Nextcloud. Do not add broad client networks, because Nextcloud would trust forwarded client-address headers from those sources.

4. Set the external URL used by occ and background jobs.

   $ sudo -u www-data php occ config:system:set overwrite.cli.url --value=https://cloud.example.net
   System config value overwrite.cli.url set to string https://cloud.example.net

   The CLI URL should match the public HTTPS address users open in a browser.

5. Set the public host override.

   $ sudo -u www-data php occ config:system:set overwritehost --value=cloud.example.net
   System config value overwritehost set to string cloud.example.net

   Use only the hostname and optional port, without https://.

6. Set the public protocol override.

   $ sudo -u www-data php occ config:system:set overwriteprotocol --value=https
   System config value overwriteprotocol set to string https

   Set overwritewebroot as a separate system value only when the public URL uses a path prefix such as https://cloud.example.net/nextcloud.

7. Confirm the proxy forwards the expected request headers to Nextcloud.

   Host: cloud.example.net
   X-Forwarded-For: 203.0.113.25, 10.0.0.10
   X-Forwarded-Proto: https

   The header names above match Nextcloud defaults. If the proxy uses a different client-IP header, set forwarded_for_headers only after the proxy rewrites that header at the trusted edge.
   Tool: NGINX Proxy Headers Checker

8. Check the saved trusted proxy value.

   $ sudo -u www-data php occ config:system:get trusted_proxies
   10.0.0.10

9. Check the saved public URL value.

   $ sudo -u www-data php occ config:system:get overwrite.cli.url
   https://cloud.example.net

10. Check the saved host override.

    $ sudo -u www-data php occ config:system:get overwritehost
    cloud.example.net

11. Check the saved protocol override.

    $ sudo -u www-data php occ config:system:get overwriteprotocol
    https

12. Request the status endpoint through the public proxy URL.

    $ curl -sS https://cloud.example.net/status.php
    {"installed":true,"maintenance":false,"needsDbUpgrade":false,"version":"34.0.0.12","versionstring":"34.0.0","edition":"","productname":"Nextcloud","extendedSupport":false}

    A response from https://cloud.example.net confirms the proxy reaches Nextcloud through the public hostname. A trusted-domain error means the public host is not listed in trusted_domains.

13. Recheck the Administration overview for proxy-related warnings.

    $ sudo -u www-data php occ setupchecks
    	security:
    		✓ HTTPS access and URLs: You are accessing your instance over a secure connection, and your instance is generating secure URLs.
    	config:
    		✓ Overwrite CLI URL: The "overwrite.cli.url" option in your config.php is correctly set to "https://cloud.example.net".
    ##### snipped #####

    Review the browser page under Administration settings → Overview as well, because the web view is where administrators normally see deployment warnings.
    Related: How to check Nextcloud administration overview warnings