[docs] Improve setup guide for non-standard hosting (#12588)

* [docs] Updated docs for complex server setups

Ref: https://github.com/inventree/InvenTree/discussions/12538

* Add FAQ entry

contrib/container/.env

@@ -14,8 +14,14 @@ INVENTREE_TAG=stable
 INVENTREE_SITE_URL="http://localhost"
 #INVENTREE_SITE_URL="http://inventree.localhost"
 #INVENTREE_SITE_URL="https://inventree.my-domain.com"  # Or a public domain name (which you control)
+
+# Port that the InvenTree server listens on *inside* the container - do not change unless you know what you are doing
 INVENTREE_WEB_PORT=8000
 
+# Ports that the proxy (Caddy) publishes on the *host* - change these to serve InvenTree on a non-standard port
+#INVENTREE_HTTP_PORT=80
+#INVENTREE_HTTPS_PORT=443
+
 # InvenTree proxy forwarding settings
 INVENTREE_USE_X_FORWARDED_HOST=True
 INVENTREE_USE_X_FORWARDED_PORT=True

docs/docs/faq.md

@@ -196,6 +196,16 @@ This means that either:
 
 In either case, ensure that the directory is available *on your local machine* and the user account has the required permissions.
 
+### Running on a Non-Standard Port / Behind an Existing Reverse Proxy
+
+If you want to serve InvenTree on a port other than 80/443 (for example, because those ports are already used by another service on your host), or you want to place InvenTree behind an existing reverse proxy which already handles SSL for other services, refer to:
+
+- [Proxy (external) port configuration](./start/docker_install.md#proxy-external-port) - the `INVENTREE_HTTP_PORT` / `INVENTREE_HTTPS_PORT` variables
+- [Integrating with an existing reverse proxy](./start/processes.md#integrating-with-existing-proxy) - a worked example, including the required `INVENTREE_TRUSTED_ORIGINS` setting
+
+!!! tip "Automatic HTTPS"
+    The bundled Caddy proxy's [Automatic HTTPS](./start/docker.md#ssl-certificates) only works if it is reachable on the standard ports 80/443, for the Let's Encrypt ACME challenge. If that is not the case for your setup, terminate SSL at your external proxy instead.
+
 
 ## Error Rendering Component
 

docs/docs/start/config.md

@@ -122,6 +122,9 @@ Depending on how your InvenTree installation is configured, you will need to pay
 !!! success "INVENTREE_SITE_URL"
     If you have specified the `INVENTREE_SITE_URL`, this will automatically be used as a trusted CSRF and CORS host (see below).
 
+!!! tip "Running Behind a Reverse Proxy"
+    If InvenTree is served behind an existing reverse proxy (e.g. NGINX, Traefik) with SSL termination happening upstream, refer to the [worked example](./processes.md#integrating-with-existing-proxy) for the combination of `INVENTREE_TRUSTED_ORIGINS` and `INVENTREE_USE_X_FORWARDED_*` settings that setup requires.
+
 {{ configtable() }}
 {{ configsetting("INVENTREE_ALLOWED_HOSTS") }} List of allowed hosts |
 {{ configsetting("INVENTREE_TRUSTED_ORIGINS", default="Uses the *INVENTREE_SITE_URL* parameter, if set. Otherwise, an empty list.") }} List of trusted origins. Refer to the [django documentation]({% include "django.html" %}/ref/settings/#csrf-trusted-origins) |

docs/docs/start/docker.md

@@ -93,6 +93,9 @@ The production docker compose configuration outlined on this page uses [Caddy](h
 
 The provided `Caddyfile` configuration file is setup to enable [Automatic HTTPS](https://caddyserver.com/docs/automatic-https) by default! All you have to do is specify a `https://` URL in the `INVENTREE_SITE_URL` variable.
 
+!!! warning "Standard Ports Required"
+    Automatic HTTPS requires that the Caddy container be reachable on the standard ports 80/443, so that it can complete a Let's Encrypt ACME challenge. This will not work if InvenTree is published on a non-standard port, or is running behind another reverse proxy. In those cases, terminate SSL at the external proxy instead, and run Caddy over plain HTTP - refer to [running behind an existing reverse proxy](./processes.md#integrating-with-existing-proxy).
+
 ### Containers
 
 The example docker compose file launches the following containers:

docs/docs/start/docker_install.md

@@ -225,6 +225,9 @@ The provided `Caddyfile` configuration file is setup to enable [Automatic HTTPS]
 
 The [Caddy](./docker.md#ssl-certificates) container will automatically generate SSL certificates for your domain.
 
+!!! warning "Standard Ports Required"
+    Automatic HTTPS relies on a Let's Encrypt ACME challenge, which requires that your server be reachable on the standard ports 80 and/or 443. If you are publishing InvenTree on a non-standard port (see [below](#web-server-bind-address)), or your host cannot be reached externally on those ports, automatic HTTPS will fail. In that case, terminate SSL at an external reverse proxy instead - refer to [running behind an existing reverse proxy](./processes.md#integrating-with-existing-proxy).
+
 #### Persistent Files
 
 Any persistent files generated by the Caddy container (such as certificates, etc) will be stored in the `caddy` directory within the external volume.
@@ -241,6 +244,20 @@ This can be adjusted using the following environment variables:
 
 These variables are combined in the [Dockerfile]({{ sourcefile("contrib/container/Dockerfile") }}) to build the bind string passed to the InvenTree server on startup.
 
+!!! warning "Internal Port Only"
+    `INVENTREE_WEB_PORT` controls the port used *internally* between the `inventree-server` (gunicorn) and `inventree-proxy` (Caddy) containers. It is not the port that other machines on your network connect to, and in most cases should be left at its default value of `8000`.
+
+#### Proxy (External) Port
+
+The port that is actually published to your host - and thus reachable by other devices on your network - is controlled separately, via the `inventree-proxy` service:
+
+| Environment Variable | Default |
+| --- | --- |
+| `INVENTREE_HTTP_PORT` | 80 |
+| `INVENTREE_HTTPS_PORT` | 443 |
+
+If you want to serve InvenTree on a non-standard port (for example, because port 80/443 is already in use by another service on the same host), set `INVENTREE_HTTP_PORT` and/or `INVENTREE_HTTPS_PORT` in your `.env` file, and update `INVENTREE_SITE_URL` to include the matching port number, e.g. `INVENTREE_SITE_URL="http://192.168.1.10:5143"`.
+
 !!! tip "IPv6 Support"
     To enable IPv6/Dual Stack support, set `INVENTREE_WEB_ADDR` to `[::]` when you create/start the container.
 

docs/docs/start/processes.md

@@ -104,9 +104,17 @@ You may wish to extend the proxy configuration to include additional features, b
 
 #### Integrating with Existing Proxy
 
-You may wish to integrate the InvenTree web server with an existing reverse proxy server. This is possible, but requires careful configuration to ensure that the static and media files are served correctly.
+You may wish to integrate the InvenTree web server with an existing reverse proxy server - for example, a single NGINX, Traefik, or Caddy instance which already terminates SSL for other services on your network (common on NAS platforms such as TrueNAS, Unraid, or Synology). This is possible, but requires careful configuration to ensure that the static and media files are served correctly, and that InvenTree trusts requests forwarded from the upstream proxy.
 
-*Note: A custom configuration of the proxy server is outside the scope of this documentation!*
+*Note: Configuration of your external proxy server itself is outside the scope of this documentation - refer to the documentation for the specific software you are using.*
+
+The pattern below outlines the InvenTree-side configuration that this setup always requires, regardless of which proxy software sits in front of it:
+
+- Leave the bundled `inventree-proxy` (Caddy) container serving plain **HTTP** - do not enable [Automatic HTTPS](./docker.md#ssl-certificates), as Caddy will not be reachable directly for the ACME challenge. SSL termination is handled entirely by your existing external proxy instead.
+- Publish the `inventree-proxy` container's HTTP port (`INVENTREE_HTTP_PORT`, see [docker_install.md](./docker_install.md#proxy-external-port)) on an address/port that your external proxy can reach, and point the external proxy's upstream/backend at that address.
+- Set `INVENTREE_SITE_URL` to the externally-visible URL that users and the external proxy will actually use to reach InvenTree (e.g. `https://inventree.example.com`), even though InvenTree itself is only ever served over plain HTTP internally.
+- If the external proxy's public URL differs from `INVENTREE_SITE_URL` (for example, if `INVENTREE_SITE_URL` is set to an internal address rather than the public domain), explicitly add the public URL to [`INVENTREE_TRUSTED_ORIGINS`](./config.md#server-access) - otherwise, form submissions (including login) will fail CSRF validation.
+- The forwarded-header settings `INVENTREE_USE_X_FORWARDED_HOST`, `INVENTREE_USE_X_FORWARDED_PORT`, and `INVENTREE_USE_X_FORWARDED_PROTO` (see [Server Access](./config.md#server-access)) are enabled by default in the provided `.env` file, so that InvenTree correctly reports its own HTTPS URL even though it only ever receives plain HTTP traffic from your external proxy. Ensure your external proxy actually sets the corresponding `X-Forwarded-*` headers when forwarding requests.
 
 ### Background Worker