From b0ce67fcd7f20dbd5ba2a8369dda36d91d1d0436 Mon Sep 17 00:00:00 2001 From: Oliver Date: Fri, 27 Dec 2024 15:46:17 +1100 Subject: [PATCH] [Docs] Update FAQ (#8777) * Update FAQ * Add links to FAQ * Extra info * Extend documentation for debug options --- docs/docs/faq.md | 14 +++++++++++ docs/docs/start/config.md | 39 ++++++++++++++++++++++++------- docs/docs/start/docker_install.md | 4 ++++ docs/docs/start/installer.md | 4 ++++ 4 files changed, 53 insertions(+), 8 deletions(-) diff --git a/docs/docs/faq.md b/docs/docs/faq.md index 4904124ed4..4d9ea2bac1 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -44,6 +44,20 @@ This error occurs because your installed python version is not up to date. We [r You (or your system administrator) needs to update python to meet the minimum requirements for InvenTree. +### InvenTree Site URL + +During the installation or update process, you may see an error similar to: + +``` +'No CSRF_TRUSTED_ORIGINS specified. Please provide a list of trusted origins, or specify INVENTREE_SITE_URL' +``` + +If you see this error, it means that the `INVENTREE_SITE_URL` environment variable has not correctly specified. Refer to the [configuration documentation](./start/config.md#site-url) for more information. + +### Login Issues + +If you have successfully started the InvenTree server, but are experiencing issues logging in, it may be due to the security interactions between your web browser and the server. While the default configuration should work for most users, if you do experience login issues, ensure that your [server access settings](./start/config.md#server-access) are correctly configured. + ## Update Issues Sometimes, users may encounter unexpected error messages when updating their InvenTree installation to a newer version. diff --git a/docs/docs/start/config.md b/docs/docs/start/config.md index b672756128..1f0db68ff6 100644 --- a/docs/docs/start/config.md +++ b/docs/docs/start/config.md @@ -61,13 +61,6 @@ The following basic options are available: | Environment Variable | Configuration File | Description | Default | | --- | --- | --- | --- | | INVENTREE_SITE_URL | site_url | Specify a fixed site URL | *Not specified* | -| INVENTREE_DEBUG | debug | Enable [debug mode](./intro.md#debug-mode) | True | -| INVENTREE_DEBUG_QUERYCOUNT | debug_querycount | Enable [query count logging](https://github.com/bradmontgomery/django-querycount) in the terminal | False | -| INVENTREE_DEBUG_SHELL | debug_shell | Enable [administrator shell](https://github.com/djk2/django-admin-shell) (only in debug mode) | False | -| INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | WARNING | -| INVENTREE_JSON_LOG | json_log | log as json | False | -| INVENTREE_DB_LOGGING | db_logging | Enable logging of database messages | False | -| INVENTREE_WRITE_LOG | write_log | Enable writing of log messages to file at config base | False | | INVENTREE_TIMEZONE | timezone | Server timezone | UTC | | INVENTREE_ADMIN_ENABLED | admin_enabled | Enable the [django administrator interface]({% include "django.html" %}/ref/contrib/admin/) | True | | INVENTREE_ADMIN_URL | admin_url | URL for accessing [admin interface](../settings/admin.md) | admin | @@ -90,6 +83,36 @@ By default, the InvenTree server will not automatically apply database migration With "auto update" enabled, the InvenTree server will automatically apply database migrations as required. To enable automatic database updates, set `INVENTREE_AUTO_UPDATE` to `True`. +## Debugging and Logging Options + +The following debugging / logging options are available: + +| Environment Variable | Configuration File | Description | Default | +| --- | --- | --- | --- | +| INVENTREE_DEBUG | debug | Enable [debug mode](./intro.md#debug-mode) | False | +| INVENTREE_DEBUG_QUERYCOUNT | debug_querycount | Enable [query count logging](https://github.com/bradmontgomery/django-querycount) in the terminal | False | +| INVENTREE_DEBUG_SHELL | debug_shell | Enable [administrator shell](https://github.com/djk2/django-admin-shell) (only in debug mode) | False | +| INVENTREE_DB_LOGGING | db_logging | Enable logging of database messages | False | +| INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | WARNING | +| INVENTREE_JSON_LOG | json_log | log as json | False | +| INVENTREE_WRITE_LOG | write_log | Enable writing of log messages to file at config base | False | + +### Debug Mode + +Enabling the `INVENTREE_DEBUG` setting will turn on [Django debug mode]({% include "django.html" %}/ref/settings/#debug). This mode is intended for development purposes, and should not be enabled in a production environment. Read more about [InvenTree debug mode](./intro.md#debug-mode). + +### Query Count Logging + +Enabling the `INVENTREE_DEBUG_QUERYCOUNT` setting will log the number of database queries executed for each page load. This can be useful for identifying performance bottlenecks in the InvenTree server. Note that this setting is only available if `INVENTREE_DEBUG` is also enabled. + +### Debug Shell + +Enabling the `INVENTREE_DEBUG_SHELL` setting will allow the use of the [administrator shell](https://github.com/djk2/django-admin-shell). Note that this setting is only available if `INVENTREE_DEBUG` is also enabled, and is only accessible to superuser accounts. + +### Database Logging + +Enabling the `INVENTREE_DB_LOGGING` setting will log all database queries to the terminal. This can be useful for debugging database-related issues. + ## Server Access Depending on how your InvenTree installation is configured, you will need to pay careful attention to the following settings. If you are running your server behind a proxy, or want to adjust support for [CORS requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), one or more of the following settings may need to be adjusted. @@ -121,7 +144,7 @@ Depending on how your InvenTree installation is configured, you will need to pay ### Debug Mode -Note that in [debug mode](./intro.md#debug-mode), some of the above settings are automatically adjusted to allow for easier development: +Note that in [debug mode](./intro.md#debug-mode), some of the above settings are automatically adjusted to allow for easier development. The following settings are internally overridden in debug mode with the values specified below: | Setting | Value in Debug Mode | Description | | --- | --- | --- | diff --git a/docs/docs/start/docker_install.md b/docs/docs/start/docker_install.md index aa7f9b3f0d..9db21f3e82 100644 --- a/docs/docs/start/docker_install.md +++ b/docs/docs/start/docker_install.md @@ -23,6 +23,10 @@ The following guide provides a streamlined production InvenTree installation, wi !!! warning "Docker Knowledge Required" This guide assumes that you are reasonably comfortable with the basic concepts of docker and docker compose. +### Frequently Asked Questions + +If you encounter any issues during the installation process, please refer first to the [FAQ](../faq.md) for common problems and solutions. + ## Docker Installation ### Required Files diff --git a/docs/docs/start/installer.md b/docs/docs/start/installer.md index 220e30a93a..73e2828ca7 100644 --- a/docs/docs/start/installer.md +++ b/docs/docs/start/installer.md @@ -23,6 +23,10 @@ The above command may need to be run with `sudo` permissions, depending on the s sudo wget -qO install.sh https://get.inventree.org && sudo bash install.sh ``` +#### Frequently Asked Questions + +If you encounter any issues during the installation process, please refer first to the [FAQ](../faq.md) for common problems and solutions. + ### File Locations The installer creates the following directories: