diff --git a/docs/docs/start/config.md b/docs/docs/start/config.md index 1f0db68ff6..ce66631e5a 100644 --- a/docs/docs/start/config.md +++ b/docs/docs/start/config.md @@ -71,6 +71,8 @@ The following basic options are available: The *INVENTREE_SITE_URL* option defines the base URL for the InvenTree server. This is a critical setting, and it is required for correct operation of the server. If not specified, the server will attempt to determine the site URL automatically - but this may not always be correct! +The site URL is the URL that users will use to access the InvenTree server. For example, if the server is accessible at `https://inventree.example.com`, the site URL should be set to `https://inventree.example.com`. Note that this is not necessarily the same as the internal URL that the server is running on - the internal URL will depend entirely on your server configuration and may be obscured by a reverse proxy or other such setup. + ### Timezone By default, the InvenTree server is configured to use the UTC timezone. This can be adjusted to your desired local timezone. You can refer to [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for a list of available timezones. Use the values specified in the *TZ Identifier* column in the linked page. @@ -139,6 +141,7 @@ Depending on how your InvenTree installation is configured, you will need to pay | INVENTREE_CORS_ALLOW_CREDENTIALS | cors.allow_credentials | Allow cookies in cross-site requests | `True` | | INVENTREE_USE_X_FORWARDED_HOST | use_x_forwarded_host | Use forwarded host header | `False` | | INVENTREE_USE_X_FORWARDED_PORT | use_x_forwarded_port | Use forwarded port header | `False` | +| INVENTREE_USE_X_FORWARDED_PROTO | use_x_forwarded_proto | Use forwarded protocol header | `False` | | INVENTREE_SESSION_COOKIE_SECURE | cookie.secure | Enforce secure session cookies | `False` | | INVENTREE_COOKIE_SAMESITE | cookie.samesite | Session cookie mode. Must be one of `Strict | Lax | None | False`. Refer to the [mozilla developer docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) and the [django documentation]({% include "django.html" %}/ref/settings/#std-setting-SESSION_COOKIE_SAMESITE) for more information. | False | @@ -157,9 +160,32 @@ Note that in [debug mode](./intro.md#debug-mode), some of the above settings are 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. -### Proxy Settings +### Proxy Considerations -If you are running InvenTree behind another proxy, you will need to ensure that the InvenTree server is configured to listen on the correct host and port. You will likely have to adjust the `INVENTREE_ALLOWED_HOSTS` setting to ensure that the server will accept requests from the proxy. +If you are running InvenTree behind a proxy, or forwarded HTTPS connections, you will need to ensure that the InvenTree server is configured to listen on the correct host and port. You will likely have to adjust the `INVENTREE_ALLOWED_HOSTS` setting to ensure that the server will accept requests from the proxy. + +Additionally, you may need to configure the following header to ensure that the InvenTree server is watching for information forwarded by the proxy: + +**X-Forwarded-Host** + +By default, InvenTree *will not* look at the [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host) header. +If you are running InvenTree behind a proxy which obscures the upstream host information, you will need to ensure that the `INVENTREE_USE_X_FORWARDED_HOST` setting is enabled. This will ensure that the InvenTree server uses the forwarded host header for processing requests. + +You can also refer to the [Django documentation]({% include "django.html" %}/ref/settings/#secure-proxy-ssl-header) for more information on this header. + +**X-Forwarded-Port** + +InvenTree provides support for the `X-Forwarded-Port` header, which can be used to determine if the incoming request is using a forwarded port. If you are running InvenTree behind a proxy which forwards port information, you should ensure that the `INVENTREE_USE_X_FORWARDED_PORT` setting is enabled. + +Note: This header is overridden by the `X-Forwarded-Host` header. + +You can also refer to the [Django documentation]({% include "django.html" %}/ref/settings/#use-x-forwarded-port) for more information on this header. + +**X-Forwarded-Proto** + +InvenTree provides support for the [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) header, which can be used to determine if the incoming request is using HTTPS, even if the server is running behind a proxy which forwards SSL connections. If you are running InvenTree behind a proxy which forwards SSL connections, you should ensure that the `INVENTREE_USE_X_FORWARDED_PROTO` setting is enabled. + +You can also refer to the [Django documentation]({% include "django.html" %}/ref/settings/#use-x-forwarded-host) for more information on this header. ## Admin Site diff --git a/src/backend/InvenTree/InvenTree/settings.py b/src/backend/InvenTree/InvenTree/settings.py index 202d78541b..af0b3197e3 100644 --- a/src/backend/InvenTree/InvenTree/settings.py +++ b/src/backend/InvenTree/InvenTree/settings.py @@ -1063,6 +1063,12 @@ if SITE_URL: print(f"Invalid SITE_URL value: '{SITE_URL}'. InvenTree server cannot start.") sys.exit(-1) +else: + logger.warning('No SITE_URL specified. Some features may not work correctly') + logger.warning( + 'Specify a SITE_URL in the configuration file or via an environment variable' + ) + # Enable or disable multi-site framework SITE_MULTI = get_boolean_setting('INVENTREE_SITE_MULTI', 'site_multi', False) @@ -1183,6 +1189,18 @@ SESSION_COOKIE_SECURE = ( ) ) +# Ref: https://docs.djangoproject.com/en/4.2/ref/settings/#std-setting-SECURE_PROXY_SSL_HEADER +if ssl_header := get_boolean_setting( + 'INVENTREE_USE_X_FORWARDED_PROTO', 'use_x_forwarded_proto', False +): + # The default header name is 'HTTP_X_FORWARDED_PROTO', but can be adjusted + ssl_header_name = get_setting( + 'INVENTREE_X_FORWARDED_PROTO_NAME', + 'x_forwarded_proto_name', + 'HTTP_X_FORWARDED_PROTO', + ) + SECURE_PROXY_SSL_HEADER = (ssl_header_name, 'https') + USE_X_FORWARDED_HOST = get_boolean_setting( 'INVENTREE_USE_X_FORWARDED_HOST', config_key='use_x_forwarded_host', diff --git a/src/backend/InvenTree/config_template.yaml b/src/backend/InvenTree/config_template.yaml index 4bca100d31..7d5177fa07 100644 --- a/src/backend/InvenTree/config_template.yaml +++ b/src/backend/InvenTree/config_template.yaml @@ -25,6 +25,9 @@ database: # HOST: Database host address (if required) # PORT: Database host port (if required) +# Base URL for the InvenTree server (or use the environment variable INVENTREE_SITE_URL) +# site_url: 'http://localhost:8000' + # Set debug to False to run in production mode, or use the environment variable INVENTREE_DEBUG debug: False @@ -45,8 +48,10 @@ log_level: WARNING # Configure if logs should be output in JSON format # Use environment variable INVENTREE_JSON_LOG json_log: False + # Enable database-level logging, or use the environment variable INVENTREE_DB_LOGGING db_logging: False + # Enable writing a log file, or use the environment variable INVENTREE_WRITE_LOG write_log: False @@ -56,8 +61,6 @@ language: en-us # System time-zone (default is UTC). Reference: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones timezone: UTC -# Base URL for the InvenTree server (or use the environment variable INVENTREE_SITE_URL) -site_url: 'http://localhost:8000' # Add new user on first startup by either adding values here or from a file #admin_user: admin @@ -114,14 +117,11 @@ allowed_hosts: # - 'http://localhost' # - 'http://*.localhost' -# Proxy forwarding settings -# If InvenTree is running behind a proxy, you may need to configure these settings - -# Override with the environment variable INVENTREE_USE_X_FORWARDED_HOST -use_x_forwarded_host: false - -# Override with the environment variable INVENTREE_USE_X_FORWARDED_PORT -use_x_forwarded_port: false +# Enable Proxy header passthrough +# Override with the environment variable INVENTREE_USE_X_FORWARDED_
+# use_x_forwarded_host: true +# use_x_forwarded_port: true +# use_x_forwarded_proto: true # Cookie settings (nominally the default settings should be fine) cookie: @@ -160,7 +160,6 @@ cache: host: 'inventree-cache' port: 6379 - # Login configuration login_confirm_days: 3 login_attempts: 5