[Docs] Update FAQ (#8777)

* Update FAQ * Add links to FAQ * Extra info * Extend documentation for debug options
inventree · Dec 27, 2024 · b0ce67f · b0ce67f
1 parent 189f230
commit b0ce67f
Show file tree

Hide file tree

Showing 4 changed files with 53 additions and 8 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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: