inventree/inventree-docs
2
0
Fork 0
mirror of https://github.com/inventree/inventree-docs.git synced 2025-04-27 21:26:43 +00:00
Code

Update configuration documentation (#342)

Browse Source 
* Update docs for config.yaml

(cherry picked from commit eb7d4bb251f8c59f4dba2ebce67e6a3d27bd233e)

* Add more settings

(cherry picked from commit 70cf34c7afaef23133d3215e957add6ffa3a4928)

* Config docs cleanup

* Update docker dev quickstart guide

* plugin settings

* Document currency support

* Add extra information for secret_key

* Slight tweaks to docker setup guide
This commit is contained in:
Oliver 2022-07-31 19:26:49 +10:00 committed by GitHub
parent b1f614bacf
commit ecd29e9b4d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 97 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

118
docs/start/config.md
View File

@ -4,26 +4,12 @@ title: Database Configuration
## Database Configuration ## Database Configuration
Admin users will need to adjust the InvenTree installation to meet the particular needs of their setup. For example, pointing to the correct database backend, or specifying a list of allowed hosts. While many InvenTree options can be configured at "run time", there are a number of system configuration parameters which need to be set *before* running InvenTree. Admin users will need to adjust the InvenTree installation to meet the particular needs of their setup. For example, pointing to the correct database backend, or specifying a list of allowed hosts.
InvenTree system settings can be specified in a configuration file, or via environment variables. InvenTree system settings can be specified either in a configuration file, or via environment variables.
!!! info "Environment Variables" !!! info "Environment Variables"
Settings specified using environment variables take priority Settings specified using environment variables take priority. Values provided in the configuration file are ignored if a matching environment variable is present.
### Configuration File
To support install specific settings, a simple configuration file ``config.yaml`` is provided. This configuration file is loaded by the InvenTree server at runtime. Settings specific to a given install should be adjusted in ``config.yaml``.
The default InvenTree config file is located at `./InvenTree/config.yaml`
However, the config file can be placed elsewhere, and specified with the `INVENTREE_CONFIG_FILE` environment variable.
A short snippet from an example configuration file file is shown below. The entire default configuration file can be found on [GitHub](https://github.com/inventree/InvenTree/blob/master/InvenTree/config_template.yaml)
``` yaml
{% include 'config.yaml' %}
```
### Environment Variables ### Environment Variables
@ -38,25 +24,45 @@ In addition to specifying InvenTree options via the `config.yaml` file, these op
!!! warning "Available Variables" !!! warning "Available Variables"
Some configuration options cannot be set via environment variables. Refer to the documentation below. Some configuration options cannot be set via environment variables. Refer to the documentation below.
### Configuration File
To support install specific settings, a simple configuration file `config.yaml` is provided. This configuration file is loaded by the InvenTree server at runtime. Settings specific to a given install should be adjusted in `config.yaml`.
The default InvenTree config file is located at `./InvenTree/config.yaml`
!!! tip "Configuration File Location"
The config file can be placed elsewhere, and specified with the `INVENTREE_CONFIG_FILE` environment variable.
A configuration file *template* can be found on [GitHub](https://github.com/inventree/InvenTree/blob/master/InvenTree/config_template.yaml)
!!! info "Template File"
The default configuration file (as defined by the template linked above) will be copied to the specifed configuration file location on first run, if a configuration file is not found in that location.
## Basic Options ## Basic Options
The following basic options are available: The following basic options are available:
| Environment Variable | Settings File | Description | Default | | Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| INVENTREE_DEBUG | debug | Enable debug mode | True | | INVENTREE_DEBUG | debug | Enable [debug mode](./intro.md#debug-mode) | True |
| INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | WARNING | | INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | WARNING |
| INVENTREE_TIMZONE | timezome | Server timezone | UTC |
| ADMIN_URL | admin_url | URL for accessing [admin interface](../settings/admin.md) | admin |
| INVENTREE_LANGUAGE | language | Default language | en-us |
## Administrator Account ## Administrator Account
An administrator account can be specified using the following environment variables: An administrator account can be specified using the following environment variables:
| Environment Variable | Settings File | Description | Default | | Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| INVENTREE_ADMIN_USER | admin_user | Admin account username | *Not set* | | INVENTREE_ADMIN_USER | admin_user | Admin account username | *Not set* |
| INVENTREE_ADMIN_PASSWORD | admin_password | Admin account password | *Not set* | | INVENTREE_ADMIN_PASSWORD | admin_password | Admin account password | *Not set* |
| INVENTREE_ADMIN_EMAIL | admin_email |Admin account email address | *Not set* | | INVENTREE_ADMIN_EMAIL | admin_email |Admin account email address | *Not set* |
!!! info "Administrator Account"
Providing `INVENTREE_ADMIN` credentials will result in the provided account being created with *superuser* permissions when InvenTree is started.
## Secret Key ## Secret Key
InvenTree requires a secret key for providing cryptographic signing - this should be a secret (and unpredictable) value. InvenTree requires a secret key for providing cryptographic signing - this should be a secret (and unpredictable) value.
@ -75,6 +81,11 @@ A file containing the secret key can be passed via the environment variable `INV
If not specified via environment variables, the fallback secret_key file (automatically generated as part of InvenTree installation) will be used. If not specified via environment variables, the fallback secret_key file (automatically generated as part of InvenTree installation) will be used.
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_SECRET_KEY | secret_key | Raw secret key value | *Not set* |
| INVENTREE_SECRET_KEY_FILE | secret_key_file | File containing secret key value | *Not set* |
## Database Options ## Database Options
InvenTree provides support for multiple database backends - any backend supported natively by Django can be used. InvenTree provides support for multiple database backends - any backend supported natively by Django can be used.
@ -83,7 +94,7 @@ Database options are specified under the *database* heading in the configuration
The following database options can be configured: The following database options can be configured:
| Environment Variable | Settings File | Description | Default | | Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| INVENTREE_DB_ENGINE | database.ENGINE | Database backend | *Not set* | | INVENTREE_DB_ENGINE | database.ENGINE | Database backend | *Not set* |
| INVENTREE_DB_NAME | database.NAME | Database name | *Not set* | | INVENTREE_DB_NAME | database.NAME | Database name | *Not set* |
@ -92,13 +103,34 @@ The following database options can be configured:
| INVENTREE_DB_HOST | database.HOST | Database host address (if required) | *Not set* | | INVENTREE_DB_HOST | database.HOST | Database host address (if required) | *Not set* |
| INVENTREE_DB_PORT | database.PORT | Database host port (if required) | *Not set* | | INVENTREE_DB_PORT | database.PORT | Database host port (if required) | *Not set* |
### PostgreSQL Settings
If running with a PostgreSQL database backend, the following additional options are available:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_DB_TIMEOUT | database.timeout | Database connection timeout (s) | 2 |
| INVENTREE_DB_TCP_KEEPALIVES | database.tcp_keepalives | TCP keepalive | 1 |
| INVENTREE_DB_TCP_KEEPALIVES_IDLE | database.tcp_keepalives_idle | Idle TCP keepalive | 1 |
| INVENTREE_DB_TCP_KEEPALIVES_INTERNAL | database.tcp_keepalives_internal | Internal TCP keepalive | 1|
| INVENTREE_DB_TCP_KEEPALIVES_COUNT | database.tcp_keepalives_count | TCP keepalive count | 5 |
| INVENTREE_DB_ISOLATION_SERIALIZABLE | database.serializable | Database isolation level configured to "serializable" | False |
### MySQL Settings
If running with a MySQL database backend, the following additional options are available:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_DB_ISOLATION_SERIALIZABLE | database.serializable | Database isolation level configured to "serializable" | False |
## Email Settings ## Email Settings
To enable [email functionality](../settings/email.md), email settings must be configured here, either via environment variables or within the configuration file. To enable [email functionality](../settings/email.md), email settings must be configured here, either via environment variables or within the configuration file.
The following email settings are available: The following email settings are available:
| Environment Variable | Settings File | Description | Default | | Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| INVENTREE_EMAIL_BACKEND | email.backend | Email backend module | django.core.mail.backends.smtp.EmailBackend | | INVENTREE_EMAIL_BACKEND | email.backend | Email backend module | django.core.mail.backends.smtp.EmailBackend |
| INVENTREE_EMAIL_HOST | email.host | Email server host | *Not set* | | INVENTREE_EMAIL_HOST | email.host | Email server host | *Not set* |
@ -108,6 +140,13 @@ The following email settings are available:
| INVENTREE_EMAIL_TLS | email.tls | Enable TLS support | False | | INVENTREE_EMAIL_TLS | email.tls | Enable TLS support | False |
| INVENTREE_EMAIL_SSL | email.ssl | Enable SSL support | False | | INVENTREE_EMAIL_SSL | email.ssl | Enable SSL support | False |
| INVENTREE_EMAIL_SENDER | email.sender | Name of sender | *Not set* | | INVENTREE_EMAIL_SENDER | email.sender | Name of sender | *Not set* |
| INVENTREE_EMAIL_PREFIX | email.prefix | Prefix for subject text | [InvenTree] |
## Supported Currencies
The currencies supported by InvenTree must be specified in the [configuration file](#configuration-file).
A list of currency codes (e.g. *AUD*, *CAD*, *JPY*, *USD*) can be specified using the `currencies` variable.
## Allowed Hosts / CORS ## Allowed Hosts / CORS
@ -116,6 +155,12 @@ By default, all hosts are allowed, and CORS requests are enabled from any origin
!!! danger "Not Secure" !!! danger "Not Secure"
Allowing access from any host is not secure, and should be adjusted for your installation. Allowing access from any host is not secure, and should be adjusted for your installation.
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| *N/A* | allowed_hosts | List of allowed hosts | `*` |
| *N/A* | cors.allow_all | Allow all remote URLS for CORS checks | False |
| *N/A* | cors.whitelist | List of whitelisted CORS URLs | *Empty list* |
!!! info "Configuration File" !!! info "Configuration File"
Allowed hosts and CORS options must be changed in the configuration file, and cannot be set via environment variables Allowed hosts and CORS options must be changed in the configuration file, and cannot be set via environment variables
@ -156,20 +201,33 @@ If the selected providers need additional settings they must be added as dicts u
The login-experience can be altered with the following settings: The login-experience can be altered with the following settings:
| Environment Variable | Settings File | Description | Default | | Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| INVENTREE_LOGIN_CONFIRM_DAYS | login_confirm_days | Duration for which confirmation links are valid | 3 | | INVENTREE_LOGIN_CONFIRM_DAYS | login.confirm_days | Duration for which confirmation links are valid | 3 |
| INVENTREE_LOGIN_ATTEMPTS | login_attempts | Count of allowed login attempts before blocking user | 5 | | INVENTREE_LOGIN_ATTEMPTS | login.attempts | Count of allowed login attempts before blocking user | 5 |
### Authentication Backends ### Authentication Backends
Custom authentication backends can be used by specifying them here. These can for example be used to add [LDAP / AD login](https://django-auth-ldap.readthedocs.io/en/latest/) to InvenTree Custom authentication backends can be used by specifying them here. These can for example be used to add [LDAP / AD login](https://django-auth-ldap.readthedocs.io/en/latest/) to InvenTree
### Sentry Integration
The InvenTree server can be integrated with the [sentry.io](https://sentry.io) monitoring service, for error logging and performance tracking.
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_SENTRY_ENABLED | sentry.enabled | Enable sentry.io integration | False |
| INVENTREE_SENTRY_DSN | sentry.dsn | Sentry DSN (data source name) key | *Defaults to InvenTree developer key* |
| INVENTREE_SENTRY_SAMPLE_RATE | sentry.sample_rate | How often to send data samples | 0.1 |
!!! info "Default DSN"
If enabled with the default DSN, server errors will be logged to a sentry.io account monitored by the InvenTree developers.
### Customisation Options ### Customisation Options
The logo and custom messages can be changed/set: The logo and custom messages can be changed/set:
| Environment Variable | Settings File | Description | Default | | Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| INVENTREE_CUSTOM_LOGO | customize.logo | Path to logo in the media storage | | | INVENTREE_CUSTOM_LOGO | customize.logo | Path to logo in the media storage | |
| INVENTREE_CUSTOMIZE | customize.login_message | Custom message for login page | | | INVENTREE_CUSTOMIZE | customize.login_message | Custom message for login page | |
@ -184,11 +242,11 @@ If you want to remove the InvenTree branding as far as possible from your end-us
The following [plugin](../extend/plugins.md) configuration options are available: The following [plugin](../extend/plugins.md) configuration options are available:
| Environment Variable | Settings File | Description | Default | | Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| INVENTREE_PLUGINS_ENABLED | plugins_enabled | Enable plugin support | False | | INVENTREE_PLUGINS_ENABLED | plugins.enabled | Enable plugin support | False |
| INVENTREE_PLUGIN_FILE | *N/A* | Location of plugin installation file | `./InvenTree/plugins.txt` | | INVENTREE_PLUGIN_FILE | plugins.plugin_file | Location of plugin installation file | *Not set* |
| INVENTREE_PLUGIN_DIR | *N/A* | Location of external plugin directory | *Not set* | | INVENTREE_PLUGIN_DIR | plugins.plugin_dir | Location of external plugin directory | *Not set* |
## Other Options ## Other Options

1
docs/start/docker_dev.md
View File

@ -34,6 +34,7 @@ To get "up and running" with a development environment, complete with a set of [
```bash ```bash
git clone https://github.com/inventree/InvenTree.git && cd InvenTree git clone https://github.com/inventree/InvenTree.git && cd InvenTree
docker compose run inventree-dev-server invoke install
docker compose run inventree-dev-server invoke setup-test docker compose run inventree-dev-server invoke setup-test
docker compose up -d docker compose up -d
``` ```

12
docs/start/docker_prod.md
View File

@ -16,13 +16,17 @@ The following guide provides a streamlined production InvenTree installation, wi
#### Docker Image #### Docker Image
This production setup guide uses the official InvenTree docker image, available from dockerhub. The provided docker-compose file targets `inventree:stable` by default. This production setup guide uses the official InvenTree docker image, available from dockerhub.
!!! info "Stable Version"
The provided docker-compose file targets `inventree:stable` by default.
#### Docker Compose #### Docker Compose
A sample [docker compose file](https://github.com/inventree/InvenTree/blob/master/docker/production/docker-compose.yml) is provided to sequence all the required processes. A sample [docker compose file](https://github.com/inventree/InvenTree/blob/master/docker/production/docker-compose.yml) is provided to sequence all the required processes.
*If you require a different configuration, use this file as a starting point*. !!! tip "Starting Point"
If you require a different configuration, use this docker-compose file as a starting point.
#### Static and Media Files #### Static and Media Files
@ -33,7 +37,7 @@ The sample docker-compose configuration outlined on this page uses nginx to serv
#### Required Files #### Required Files
The following files required for this setup are provided with the InvenTree source, located in the `./docker/production` directory of the InvenTree source code: The following files required for this setup are provided with the InvenTree source, located in the `./docker/production` directory of the [InvenTree source code](https://github.com/inventree/InvenTree/tree/master/docker/production):
| Filename | Description | | Filename | Description |
| --- | --- | | --- | --- |
@ -187,7 +191,7 @@ docker-compose pull
This ensures that the InvenTree containers will be running the latest version of the InvenTree source code. This ensures that the InvenTree containers will be running the latest version of the InvenTree source code.
!!! info "Tagged Version" !!! info "Tagged Version"
If you are targetting a particular "tagged" version of InvenTree, you may wish to edit your docker-compose file before issuing the `docker-compose pull` command If you are targetting a particular "tagged" version of InvenTree, you may wish to edit the `INVENTREE_TAG` variable in the `.env` file before issuing the `docker-compose pull` command
### Update Database ### Update Database

15
main.py
View File

@ -6,21 +6,6 @@ from urllib import request
def define_env(env): def define_env(env):
# Ensure that the config template is always up to date
CFG_URL = "https://raw.githubusercontent.com/inventree/InvenTree/master/InvenTree/config_template.yaml"
# Only perform this step if we are building on RTD server
if os.environ.get('READTHEDOCS', False):
response = request.urlopen(CFG_URL)
print(f"Reading config template from GitHub: Response {response.status}")
if response.status == 200:
data = response.read()
if len(data) > 0:
with open("_includes/config.yaml", "w") as f:
f.write(str(data.decode()))
@env.macro @env.macro
def listimages(subdir): def listimages(subdir):
""" """