Caddyfile documentation (inventree#8798) (inventree#8800)

github-actions[bot] · SchrodingersGat · web-flow · commit 4d07a49dfd70 · 2024-12-31T13:47:07.000+11:00
* basic mixin file * Add basic check for model type support * Enhanced documentation for Caddyfile * Additional documentation around proxy server * Remove code from other PR (cherry picked from commit ecc1c93) Co-authored-by: Oliver <oliver.henry.walters@gmail.com>
diff --git a/contrib/container/Caddyfile b/contrib/container/Caddyfile
@@ -4,14 +4,18 @@
 # - INVENTREE_SERVER: The internal URL of the InvenTree container (default: http://inventree-server:8000)
 #
 # Note that while this file is a good starting point, it may need to be modified to suit your specific requirements
+#
+# Ref to the Caddyfile documentation: https://caddyserver.com/docs/caddyfile
 
 
+# Logging configuration for Caddy
 (log_common) {
 	log {
 		output file /var/log/caddy/{args[0]}.access.log
 	}
 }
 
+# CORS headers control (used for static and media files)
 (cors-headers) {
 	header Allow GET,HEAD,OPTIONS
 	header Access-Control-Allow-Origin *
@@ -25,8 +29,10 @@
 	}
 }
 
-# Change the host to your domain (this will serve at inventree.localhost)
-{$INVENTREE_SITE_URL:inventree.localhost} {
+# The default server address is configured in the .env file
+# If not specified, the default address is used - http://inventree.localhost
+# If you need to listen on multiple addresses, or use a different port, you can modify this section directly
+{$INVENTREE_SITE_URL:http://inventree.localhost} {
 	import log_common inventree
 
 	encode gzip
@@ -35,25 +41,39 @@
 		max_size 100MB
 	}
 
+	# Handle static request files
 	handle_path /static/* {
 		import cors-headers static
 
 		root * /var/www/static
 		file_server
 	}
 
+	# Handle media request files
 	handle_path /media/* {
 		import cors-headers media
 
 		root * /var/www/media
 		file_server
 
+		# Force download of media files (for security)
+		# Comment out this line if you do not want to force download
 		header Content-Disposition attachment
 
+		# Authentication is handled by the forward_auth directive
+		# This is required to ensure that media files are only accessible to authenticated users
 		forward_auth {$INVENTREE_SERVER:"http://inventree-server:8000"} {
 			uri /auth/
 		}
 	}
 
-	reverse_proxy {$INVENTREE_SERVER:"http://inventree-server:8000"}
+	# All other requests are proxied to the InvenTree server
+	reverse_proxy {$INVENTREE_SERVER:"http://inventree-server:8000"} {
+
+		# If you are running behind another proxy, you may need to specify 'trusted_proxies'
+		trusted_proxies {
+			# enter your trusted proxy IP addresses here
+		}
+
+	}
 }
diff --git a/docs/docs/start/config.md b/docs/docs/start/config.md
@@ -156,7 +156,7 @@ Note that in [debug mode](./intro.md#debug-mode), some of the above settings are
 | `INVENTREE_COOKIE_SAMESITE` | `False` | Disable all same-site cookie checks in debug mode |
 | `INVENTREE_SESSION_COOKIE_SECURE` | `False` | Disable secure session cookies in debug mode (allow non-https cookies) |
 
-### INVENTREE_COOKIE_SAMESITE vs INVENTREE_SESSION_COOKIE_SECURE
+### Cookie Settings
 
 Note that if you set the `INVENTREE_COOKIE_SAMESITE` to `None`, then `INVENTREE_SESSION_COOKIE_SECURE` is automatically set to `True` to ensure that the session cookie is secure! This means that the session cookie will only be sent over secure (https) connections.
 
@@ -187,6 +187,11 @@ InvenTree provides support for the [X-Forwarded-Proto](https://developer.mozilla
 
 You can also refer to the [Django documentation]({% include "django.html" %}/ref/settings/#use-x-forwarded-host) for more information on this header.
 
+Proxy configuration can be complex, and any configuration beyond the basic setup is outside the scope of this documentation. You should refer to the documentation for the specific proxy server you are using.
+
+Refer to the [proxy server documentation](./processes.md#proxy-server) for more information.
+
+
 ## Admin Site
 
 Django provides a powerful [administrator interface]({% include "django.html" %}/ref/contrib/admin/) which can be used to manage the InvenTree database. This interface is enabled by default, and available at the `/admin/` URL.
diff --git a/docs/docs/start/processes.md b/docs/docs/start/processes.md
@@ -44,6 +44,12 @@ Further, it provides an authentication endpoint for accessing files in the `/sta
 
 Finally, it provides a [Let's Encrypt](https://letsencrypt.org/) endpoint for automatic SSL certificate generation and renewal.
 
+### Proxy Functionality
+
+#### API and Web Requests
+
+All API and web requests are reverse-proxied to the InvenTree django server. This allows the InvenTree web server to be accessed via a standard HTTP/HTTPS port, and allows the proxy server to handle SSL termination.
+
 #### Static Files
 
 Static files can be served without any need for authentication. In fact, they must be accessible *without* authentication, otherwise the unauthenticated views (such as the login screen) will not function correctly.
@@ -52,15 +58,34 @@ Static files can be served without any need for authentication. In fact, they mu
 
 It is highly recommended that the *media* files are served behind an authentication layer. This is because the media files are user-uploaded, and may contain sensitive information. Most modern web servers provide a way to serve files behind an authentication layer.
 
-#### Example Configuration
+### Proxy Configuration
+
+We provide some *sample* configuration files for getting your proxy server off the ground. The exact setup and configuration of your proxy server will depend on your specific requirements, and the software you choose to use. You may be integrating InvenTree with an existing web server, and the configuration may be different to the provided examples.
+
+#### Example Configurations
+
+**Caddy**
+
+The [docker production example](./docker.md) provides an example using [Caddy](https://caddyserver.com) to serve *static* and *media* files, and redirecting other requests to the InvenTree web server itself. Caddy is a modern web server which is easy to configure and provides a number of useful features, including automatic SSL certificate generation.
+
+You can find the sample Caddy configuration [here]({{ sourcefile("contrib/container/Caddyfile") }}).
+
+**Nginx**
+
+An alternative is to run nginx as the reverse proxy. A sample configuration file is provided [here]({{ sourcefile("contrib/container/nginx.conf") }}).
 
-The [docker production example](./docker.md) provides an example using [Caddy](https://caddyserver.com) to serve *static* and *media* files, and redirecting other requests to the InvenTree web server itself.
+#### Extending the Proxy Configuration
 
-Caddy is a modern web server which is easy to configure and provides a number of useful features, including automatic SSL certificate generation.
+You may wish to extend the proxy configuration to include additional features, based on your particular requirements. Some examples of where additional configuration may be required include:
 
-#### Alternatives to Caddy
+- **Upstream Proxy**: You may be running the InvenTree server behind another proxy server, and need to configure the proxy server to forward requests to the upstream proxy.
+- **Authentication**: You may wish to add an authentication layer to the proxy server, to restrict access to the InvenTree web interface.
+- **SSL Termination**: You may wish to terminate SSL connections at the proxy server, and forward unencrypted traffic to the InvenTree web server.
+- **Load Balancing**: You may wish to run multiple instances of the InvenTree web server, and use the proxy server to load balance between them.
+- **Custom Error Pages**: You may wish to provide custom error pages for certain HTTP status codes.
 
-An alternative is to run nginx as the reverse proxy. A sample configuration file is provided in the `./contrib/container/` source directory.
+!!! warning "No Support"
+    We do not provide support for configuring your proxy server. The configuration of the proxy server is outside the scope of this documentation. If you require assistance with configuring your proxy server, please refer to the documentation for the specific software you are using.
 
 #### Integrating with Existing Proxy
 
