inventree/InvenTree
2
0
Fork 0
mirror of https://github.com/inventree/InvenTree.git synced 2025-06-16 03:55:41 +00:00
Code Activity

Documentation integration (#4653)

Browse Source 
* Add documentation under docs/ directory

* Add CI workflow for mkdocs configuration checking

* Add documentation issue template

* update pip-tools?

* Update .gitignore files

* Fix .gitignore rules

* Improve release notes page

* remove references to old repo
This commit is contained in:
Oliver
2023-04-22 22:40:29 +10:00
committed by GitHub
parent 20f01e8741
commit 2ffd2354eb
487 changed files with 44875 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
docs/docs/start/backup.md Normal file
View File

@ -0,0 +1,58 @@
---
title: Data Backup
---
## Data Backup
Backup functionality is provided natively using the [django-dbbackup library](https://django-dbbackup.readthedocs.io/en/master/). This library provides multiple options for creating backups of your InvenTree database and media files. In addition to local storage backup, multiple external storage solutions are supported (such as Amazon S3 or Dropbox).
Note that a *backup* operation is not the same as [migrating data](./migrate.md). While data *migration* exports data into a database-agnostic JSON file, *backup* exports a native database file and media file archive.
## Configuration
The following configuration options are available for backup:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_BACKUP_STORAGE | backup_storage | Backup storage backend | django.core.files.storage.FileSystemStorage |
| INVENTREE_BACKUP_DIR | backup_dir | Backup storage directory | *No default* |
| INVENTREE_BACKUP_OPTIONS | backup_options | Specific backup options (dict) | *No default* |
### Storage Providers
If you want to use an external storage provider, extra configuration is required. As a starting point, refer to the [django-dbbackup documentation](https://django-dbbackup.readthedocs.io/en/master/storage.html).
Specific storage configuration options are specified using the `backup_options` dict (in the [configuration file](./config.md)).
## Perform Backup
#### Manual Backup
To perform a manual backup operation, run the following command from the shell:
```
invoke backup
```
### Backup During Update
When performing an update of your InvenTree installation - via either [docker](./docker.md) or [bare metal](./install.md) - a backup operation is automatically performed.
### Daily Backup
If desired, InvenTree can be configured to perform automated daily backups. The run-time setting to control this is found in the *Server Configuration* tab.
{% with id="auto-backup", url="start/auto-backup.png", description="Automatic daily backup" %}
{% include 'img.html' %}
{% endwith %}
!!! tip "Optional Feature"
Automated backup is disabled by default, and must be enabled by an admin user
## Restore from Backup
To restore from a previous backup, run the following command from the shell (within virtual environment if configured):
```
invoke restore
```

291
docs/docs/start/config.md Normal file
View File

@ -0,0 +1,291 @@
---
title: Database Configuration
---
## Database Configuration
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 either via environment variables, or in a configuration file.
!!! info "Environment Variables"
Settings specified using environment variables take priority. Values provided in the configuration file are ignored if a matching environment variable is present.
### Environment Variables
In addition to specifying InvenTree options via the `config.yaml` file, these options can also be specified via environment variables. This can be usful for system administrators who want the flexibility of altering settings without editing the configuration file.
Environment variable settings generally use the `INVENTREE_` prefix, and are all uppercase.
!!! info "Configuration Priority"
Configuration options set via environment variables will take priority over the values set in the `config.yaml` file.
!!! warning "Available Variables"
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`.
#### Configuration File Location
The InvenTree server tries to locate the `config.yaml` configuration file on startup, in the following locations:
1. Location is specified by the `INVENTREE_CONFIG_FILE` environment variable
2. Located in the same local directory as the InvenTree source code
!!! tip "Config File Location"
When the InvenTree server boots, it will report the location where it expects to find the configuration file
The 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.
!!! tip "Restart Server"
The contents of the configuration file are read when the InevnTree server first launches. If any changes are made to the configuration file, ensure that the server is restarted, so that the changes can be made operational.
## Basic Options
The following basic options are available:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_DEBUG | debug | Enable [debug mode](./intro.md#debug-mode) | True |
| 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
An administrator account can be specified using the following environment variables:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_ADMIN_USER | admin_user | Admin account username | *Not specified* |
| INVENTREE_ADMIN_PASSWORD | admin_password | Admin account password | *Not specified* |
| INVENTREE_ADMIN_EMAIL | admin_email |Admin account email address | *Not specified* |
!!! info "Administrator Account"
Providing `INVENTREE_ADMIN` credentials will result in the provided account being created with *superuser* permissions when InvenTree is started.
## Secret Key
InvenTree requires a secret key for providing cryptographic signing - this should be a secret (and unpredictable) value.
The secret key can be provided in multiple ways, with the following (descending) priorities:
**Pass Secret Key via Environment Variable**
A secret key string can be passed directly using the environment variable `INVENTREE_SECRET_KEY`
**Pass Secret Key File via Environment Variable**
A file containing the secret key can be passed via the environment variable `INVENTREE_SECRET_KEY_FILE`
**Fallback to Default Secret Key File**
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 specified* |
| INVENTREE_SECRET_KEY_FILE | secret_key_file | File containing secret key value | *Not specified* |
## Database Options
InvenTree provides support for multiple database backends - any backend supported natively by Django can be used.
Database options are specified under the *database* heading in the configuration file. Any option available in the Django documentation can be used here - it is passed through transparently to the management scripts.
The following database options can be configured:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_DB_ENGINE | database.ENGINE | Database backend | *Not specified* |
| INVENTREE_DB_NAME | database.NAME | Database name | *Not specified* |
| INVENTREE_DB_USER | database.USER | Database username (if required) | *Not specified* |
| INVENTREE_DB_PASSWORD | database.PASSWORD | Database password (if required) | *Not specified* |
| INVENTREE_DB_HOST | database.HOST | Database host address (if required) | *Not specified* |
| INVENTREE_DB_PORT | database.PORT | Database host port (if required) | *Not specified* |
### 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
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:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_EMAIL_BACKEND | email.backend | Email backend module | django.core.mail.backends.smtp.EmailBackend |
| INVENTREE_EMAIL_HOST | email.host | Email server host | *Not specified* |
| INVENTREE_EMAIL_PORT | email.port | Email server port | 25 |
| INVENTREE_EMAIL_USERNAME | email.username | Email account username | *Not specified* |
| INVENTREE_EMAIL_PASSWORD | email.password | Email account password | *Not specified* |
| INVENTREE_EMAIL_TLS | email.tls | Enable TLS support | False |
| INVENTREE_EMAIL_SSL | email.ssl | Enable SSL support | False |
| INVENTREE_EMAIL_SENDER | email.sender | Name of sender | *Not specified* |
| 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
By default, all hosts are allowed, and CORS requests are enabled from any origin.
!!! danger "Not Secure"
Allowing access from any host is not secure, and should be adjusted for your installation.
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_ALLOWED_HOSTS | allowed_hosts | List of allowed hosts | `*` |
| INVENTREE_CORS_ORIGIN_ALLOW_ALL | cors.allow_all | Allow all remote URLS for CORS checks | False |
| INVENTREE_CORS_ORIGIN_WHITELIST | cors.whitelist | List of whitelisted CORS URLs | *Empty list* |
!!! info "Configuration File"
Allowed hosts and CORS options must be changed in the configuration file, and cannot be set via environment variables
For further information, refer to the following documentation:
* [Django ALLOWED_HOSTS](https://docs.djangoproject.com/en/2.2/ref/settings/#allowed-hosts)
* [Django CORS headers](https://github.com/OttoYiu/django-cors-headers)
## File Storage Locations
InvenTree requires some external directories for storing files:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_STATIC_ROOT | static_root | List of allowed hosts | *Not specified* |
| INVENTREE_MEDIA_ROOT | media_root | Allow all remote URLS for CORS checks | *Not specified* |
| INVENTREE_BACKUP_DIR | backup_dir | List of whitelisted CORS URLs | *Not specified* |
!!! tip "Serving Files"
Read the [Serving Files](./serving_files.md) section for more information on hosting *static* and *media* files
### Static File Storage
Static files **require** a local directory for storage. This directory should be specified with the `static_root` option in the config file based on the particular installation requirements.
Alternatively this location can be specified with the `INVENTREE_STATIC_ROOT` environment variable.
!!! warning "Required"
The static file directory must be specified, or the server will not start
### Uploaded File Storage
Uploaded media files **require** a local directory for storage. This directory should be specified with the `media_root` option in the config file based on the particular installation requirements.
Alternatively this location can be specified with the `INVENTREE_MEDIA_ROOT` environment variable.
!!! warning "Required"
The media file directory must be specified, or the server will not start
### Backup File Storage
Database and media backups **require** a local directory for storage. This directory should be specified with the `backup_dir` option in the config file based on the particular installation requirements.
Alternatively this location can be specified with the `INVENTREE_BACKUP_DIR` environment variable.
## Authentication
InvenTree provides allowance for additional sign-in options. The following options are not enabled by default, and care must be taken by the system administrator when configuring these settings.
### Single Sign On
SSO backends for all required authentication providers need to be added to the config file as a list under the key `social_backends`. The correct backend-name can be found in django-allauths [configuration documentation](https://django-allauth.readthedocs.io/en/latest/installation.html#django).
If the selected providers need additional settings they must be added as dicts under the key `social_providers`. The correct settings can be found in the django-allauths [provider documentation](https://django-allauth.readthedocs.io/en/latest/providers.html).
!!! warning "You are not done"
SSO still needs credentials for all providers and has to be enabled in the [global settings](../settings/global.md)!
!!! tip "More Info"
Refer to the [SSO documentation](../settings/SSO.md) for more information.
### Login Options
The login-experience can be altered with the following settings:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| 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 |
### 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
### 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
The logo and custom messages can be changed/set:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_CUSTOM_LOGO | customize.logo | Path to custom logo in the static files directory | *Not specified* |
| INVENTREE_CUSTOM_SPLASH | customize.splash | Path to custom splash screen in the static files directory | *Not specified* |
| INVENTREE_CUSTOMIZE | customize.login_message | Custom message for login page | *Not specified* |
| INVENTREE_CUSTOMIZE | customize.navbar_message | Custom message for navbar | *Not specified* |
If you want to remove the InvenTree branding as far as possible from your end-user also check the [global server settings](../settings/global.md#server-settings).
!!! info "Custom Splash Screen Path"
The provided *custom splash screen* path must be specified *relative* to the location of the `/static/` directory.
!!! info "Custom Logo Path"
The provided *custom logo* path must be specified *relative* to the location of the `/static/` directory.
## Plugin Options
The following [plugin](../extend/plugins.md) configuration options are available:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_PLUGINS_ENABLED | plugins_enabled | Enable plugin support | False |
| INVENTREE_PLUGIN_FILE | plugins_plugin_file | Location of plugin installation file | *Not specified* |
| INVENTREE_PLUGIN_DIR | plugins_plugin_dir | Location of external plugin directory | *Not specified* |
## Other Options
### Middleware
Custom middleware layers can be specified here.

58
docs/docs/start/development.md Normal file
View File

@ -0,0 +1,58 @@
---
title: Development Server
---
## Development Server
!!! warning "Installation"
Before continuing, ensure that the [installation steps](./install.md) have been completed.
InvenTree includes a simple server application, suitable for use in a development environment.
!!! warning "Deployment"
Refer to the [production server instructions](./production.md) to implement a much more robust server setup.
### Running on a Local Machine
To run the development server on a local machine, run the command:
```
(env) invoke server
```
This will launch the InvenTree web interface at `http://127.0.0.1:8000`.
A different port can be specified using the `-a` flag:
```
(env) invoke server -a 127.0.0.1:8123
```
Serving on the address `127.0.0.1` means that InvenTree will only be available *on that computer*. The server will be accessible from a web browser on the same computer, but not from any other computers on the local network.
### Running on a Local Network
To enable access to the InvenTree server from other computers on a local network, you need to know the IP of the computer running the server. For example, if the server IP address is `192.168.120.1`:
```
(env) invoke server -a 192.168.120.1:8000
```
## Background Worker
The backgroun task manager must also be started. The InvenTree server is already running in the foreground, so open a *new shell window* to start the server.
### Activate Virtual Environment
```
cd /home/inventree
source ./env/bin/activate
```
### Start Background Worker
```
(env) invoke worker
```
This will start the background process manager in the current shell.

86
docs/docs/start/docker.md Normal file
View File

@ -0,0 +1,86 @@
---
title: Docker Setup
---
## Docker Image
The most convenient method of installing and running InvenTree is to use the official [docker image](https://hub.docker.com/r/inventree/inventree), available from docker-hub.
The InvenTree docker image contains all the required system packages, python modules, and configuration files for running a containerised InvenTree web server.
!!! tip "Compose Yourself"
The InvenTree container requires linking with other docker containers (such as a database backend) for complete operation. Sample [docker compose](#docker-compose) scripts are provided to get you up and running
!!! warning "Assumed Knowledge"
A very basic understanding of [Docker](https://www.docker.com/) and [docker compose](https://docs.docker.com/compose/) is assumed, for the following setup guides.
### Tagged Images
Pre-built Docker images are available from [dockerhub](https://hub.docker.com/r/inventree/inventree) with the following tags:
| Tag | Description |
| --- | --- |
| **inventree:stable** | The most recent *stable* release version of InvenTree |
| **inventree:latest** | The most up-to-date *development* version of InvenTree. |
| **inventree:_tag_** | Specific tagged images are built for each tagged release of InvenTree, e.g. `inventree:0.7.3`|
### Docker Compose
The InvenTree docker image provides a containerized webserver, however it *must* be connected with other containers (at the very least, a database backend).
InvenTree provides sample docker compose files to get you up and running:
- A [development](#development-server) compose file provides a simple way to spin up a development environment
- A [production](#production-server) compose file is intended to be used in a production environment, running the web server behind a nginx proxy.
### Environment Variables
InvenTree run-time configuration options described in the [configuration documentation](./config.md) can be passed to the InvenTree container as environment variables. Using environment variables simplifies setup and improves portability.
### Persistent Data
As docker containers are ephemeral, any *persistent* data must be stored in an external [volume](https://docs.docker.com/storage/volumes/). To simplify installation / implementation, all external data are stored in a single volume, arranged as follows:
#### Media FIles
Uploaded media files are stored in the `media/` subdirectory of the external data volume.
#### Static Files
Static files required by the webserver are stored in the `static/` subdirectory of the external data volume.
#### Configuration File
As discussed in the [configuration documentation](./config.md), InvenTree run-time settings can be provided in a configuration file.
By default, this file will be created as `config.yaml` in the external data volume.
#### Secret Key
InvenTree uses a secret key to provide cryptographic signing for the application.
As specified in the [configuration documentation](./config.md#secret-key) this can be passed to the InvenTree application directly as an environment variable, or provided via a file.
By default, the InvenTree container expects the secret key file to exist as `secret_key.txt` (within the external data volume). If this file does not exist, it will be created and a new key will be randomly generated.
!!! warning "Same Key"
Each InvenTree container instance must use the same secret key value, otherwise unexpected behavior will occur.
#### Plugins
Plugins are supported natively when running under docker. There are two ways to [install plugins](../extend/plugins/install.md) when using docker:
- Install via the `plugins.txt` file provided in the external data directory
- Install into the `plugins/` subdirectory in the external data directory
## Docker Setup Guides
With these basics in mind, refer to the following installation guides:
### Production Server
Refer to the [docker production server setup guide](./docker_prod.md) for instructions on configuring a production server using docker.
### Development Server
Refer to the [docker development server setup guide](./docker_dev.md) for instructions on configuring a development server using docker.

168
docs/docs/start/docker_dev.md Normal file
View File

@ -0,0 +1,168 @@
---
title: Docker Development Server
---
## Docker Development Server
You can use docker to launch and manage a development server, in a similar fashion to managing a production server.
The InvenTree dockerfile (`./Dockerfile`) uses a [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) process to allow both production and development setups from the same image.
There are some key differences compared to the [docker production setup](./docker_prod.md):
- The docker image is built locally, rather than being downloaded from DockerHub
- The docker image points to the source code on your local machine (mounted as a 'volume' in the docker container)
- The django webserver is used, instead of running behind Gunicorn
- The server will automatically reload when code changes are detected
!!! info "Static and Media Files"
The development server runs in DEBUG mode, and serves static and media files natively.
!!! info "Hacker Mode"
The following setup guide starts a development server which will reload "on the fly" as changes are made to the source code. This is designed for programmers and developers who wish to add and test new InvenTree features.
### Data Directory
Persistent data (such as the stored database, media files, configuration files, etc) will be stored in the `./data` directory (relative to the InvenTree source code directory).
- This directory is automatically created when you launch InvenTree via docker
- This directory is excluded from git version tracking
## Quickstart Guide
To get "up and running" with a development environment, complete with a set of [demo data](https://github.com/inventree/demo-dataset) to work with, run the following commands:
```bash
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 up -d
```
!!! tip "Development Server"
You can then view the development server at [http://localhost:8000](http://localhost:8000)
!!! info "Details, details"
For a more in-depth setup guide, continue reading below!
## Development Setup Guide
To get started with an InvenTree development setup, follow the simple steps outlined below. Before continuing, ensure that you have completed the following steps:
- Downloaded the InvenTree source code to your local machine
- Installed docker on your local machine (install *Docker Desktop* on Windows)
- Have a terminal open to the root directory of the InvenTree source code
### Edit Environment Variables (Optional)
If desired, the user may edit the environment variables, located in the `.env` file.
!!! success "This step is optional"
This step can be skipped, as the default variables will work just fine!
!!! info "Database Credentials"
You may also wish to change the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`) from their default values
### Perform Initial Setup
Perform the initial database setup by running the following command:
```bash
docker compose run inventree-dev-server invoke update
```
If this is the first time you are configuring the development server, this command will build a development version of the inventree docker image.
This command also performs the following steps:
- Ensure required python packages are installed
- Perform the required schema updates to create the required database tables
- Update translation files
- Collect all required static files into a directory where they can be served by nginx
!!! info "Grab a coffee"
This initial build process may take a few minutes!
### Create Admin Account
If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts:
```
docker compose run inventree-dev-server invoke superuser
```
### Import Demo Data
To fill the database with a demo dataset, run the following command:
```
docker compose run inventree-dev-server invoke setup-test
```
### Start Docker Containers
Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers:
```
docker compose up -d
```
This command launches the remaining containers:
- `inventree-dev-server` - InvenTree web server
- `inventree-dev-worker` - Background worker
!!! success "Check Connection"
Check that the server is running at [http://localhost:8000](http://localhost:8000). The server may take a few minutes to be ready.
## Restarting Services
Once initial setup is complete, stopping and restarting the services is much simpler:
### Stop InvenTree Services
To stop the InvenTree development server, simply run the following command:
```
docker compose down
```
### Start InvenTree Services
To start the InvenTree development server, simply run the following command:
```
docker compose up -d
```
### Restart InvenTree Services
A restart cycle is as simple as:
```
docker compose restart
```
## Editing InvenTree Source
Any changes made to the InvenTree source code are automatically detected by the services running under docker.
Thus, you can freely edit the InvenTree source files in your editor of choice.
### Database Updates
Any updates which require a database schema change must be reflected in the database itself.
To run database migrations inside the docker container, run the following command:
```
docker compose run inventree-dev-server invoke update
```
### Docker Image Updates
Occassionally, the docker image itself may receive some updates. In these cases, it may be required that the image is rebuilt. To perform a complete rebuild of the InvenTree development image from local source, run the following command:
```
docker compose build --no-cache
```

241
docs/docs/start/docker_prod.md Normal file
View File

@ -0,0 +1,241 @@
---
title: Docker Production Server
---
## Docker Production Server
The following guide provides a streamlined production InvenTree installation, with minimal configuration required.
!!! info "Starting Point"
This setup guide should be considered a *starting point*. It is likely that your particular production requirements will vary from the example shown here.
### Before You Start
!!! warning "Docker Skills Required"
This guide assumes that you are reasonably comfortable with the basic concepts of docker and docker compose.
#### Docker Image
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
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.
!!! tip "Starting Point"
If you require a different configuration, use this docker compose file as a starting point.
#### Static and Media Files
The sample docker compose configuration outlined on this page uses nginx to serve static files and media files. If you change this configuration, you will need to ensure that static and media files are served correctly.
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details
#### 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](https://github.com/inventree/InvenTree/tree/master/docker/production):
| Filename | Description |
| --- | --- |
| [docker-compose.yml](https://github.com/inventree/InvenTree/blob/master/docker/production/docker-compose.yml) | The docker compose script |
| [.env](https://github.com/inventree/InvenTree/blob/master/docker/production/.env) | Environment variables |
| [nginx.prod.conf](https://github.com/inventree/InvenTree/blob/master/docker/production/nginx.prod.conf) | nginx proxy configuration file |
This tutorial assumes you are working from the `./docker/production` directory. If this is not the case, ensure that these required files are all located in your working directory.
!!! tip "No Source Required"
For a production setup you do not need the InvenTree source code. Simply download the three required files from the links above!
### Containers
The example docker compose file launches the following containers:
| Container | Description |
| --- | --- |
| inventree-db | PostgreSQL database |
| inventree-server | Gunicorn web server |
| invenrtee-worker | django-q background worker |
| inventree-proxy | nginx proxy server |
| *inventree-cache* | *redis cache (optional)* |
#### PostgreSQL Database
A PostgreSQL database container which requires a username:password combination (which can be changed). This uses the official [PostgreSQL image](https://hub.docker.com/_/postgres).
#### Web Server
Runs an InvenTree web server instance, powered by a Gunicorn web server.
#### Background Worker
Runs the InvenTree background worker process. This spins up a second instance of the *inventree* container, with a different entrypoint command.
#### Nginx Proxy
Nginx working as a reverse proxy, separating requests for static and media files, and directing everything else to Gunicorn.
This container uses the official [nginx image](https://hub.docker.com/_/nginx).
#### Redis Cache
Redis is used as cache storage for the InvenTree server. This provides a more performant caching system which can useful in larger installations.
This container uses the official [redis image](https://hub.docker.com/_/redis).
!!! info "Redis on Docker"
Docker adds an additional network layer - that might lead to lower performance than bare metal.
To optimise and configure your redis deployment follow the [official docker guide](https://redis.io/docs/stack/get-started/install/docker/#configuration).
!!! warning "Disabled by default"
The *redis* container is not enabled in the default configuration. This is provided as an example for users wishing to use redis.
To enable the *redis* container, run any `docker compose` commands with the `--profile redis` flag.
You will also need to un-comment the `INVENTREE_CACHE_<...>` variables in the `.env` file.
### Data Volume
InvenTree stores any persistent data (e.g. uploaded media files, database data, etc) in a [volume](https://docs.docker.com/storage/volumes/) which is mapped to a local system directory. The location of this directory must be configured in the `.env` file, specified using the `INVENTREE_EXT_VOLUME` variable.
!!! info "Data Directory"
Make sure you change the path to the local directory where you want persistent data to be stored.
#### Common Issues
When configuring a docker install, sometimes a misconfiguration can cause peculiar issues where it seems that the installation is functioning correctly, but uploaded files and plugins do not "persist" across sessions. In such cases, the "mounted" volume has not mapped to a directory on your local filesystem. This may occur if you have tried multiple setup options without clearing existing volume bindings.
!!! tip "Start with a clean slate"
To prevent such issues, it is recommended that you start with a "clean slate" if you have previously configured an InvenTree installation under docker.
If you have previously setup InvenTree, remove existing volume bindings using the following command:
```docker volume rm -f inventree-production_inventree_data```
## Production Setup Guide
### Edit Environment Variables
The first step is to edit the environment variables, located in the `.env` file.
!!! warning "External Volume"
You must define the `INVENTREE_EXT_VOLUME` variable - this must point to a directory *on your local machine* where persistent data is to be stored.
!!! warning "Database Credentials"
You must also define the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`). You should ensure they are changed from the default values for added security
### Initial Database Setup
Perform the initial database setup by running the following command:
```bash
docker compose run inventree-server invoke update
```
This command performs the following steps:
- Ensure required python packages are installed
- Create a new (empty) database
- Perform the required schema updates to create the required database tables
- Update translation files
- Collect all required static files into a directory where they can be served by nginx
### Create Administrator Account
If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts:
```
docker compose run inventree-server invoke superuser
```
Alternatively, admin account details can be specifed in the `.env` file, removing the need for this manual step:
| Variable | Description |
| --- | --- |
| INVENTREE_ADMIN_USER | Admin account username |
| INVENTREE_ADMIN_PASSWORD | Admin account password |
| INVENTREE_ADMIN_EMAIL | Admin account email address |
!!! warning "Scrub Account Data"
Ensure that the admin account credentials are removed from the `.env` file after the first run, for security.
### Start Docker Containers
Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers:
```
docker compose up -d
```
This command launches the following containers:
- `inventree-db` - PostgreSQL database
- `inventree-server` - InvenTree web server
- `inventree-worker` - Background worker
- `inventree-nginx` - Nginx reverse proxy
!!! success "Up and Running!"
You should now be able to view the InvenTree login screen at [http://localhost:1337](http://localhost:1337)
## Updating InvenTree
To update your InvenTree installation to the latest version, follow these steps:
### Stop Containers
Stop all running containers as below:
```
docker compose down
```
### Update Images
Pull down the latest version of the InvenTree docker image
```
docker compose pull
```
This ensures that the InvenTree containers will be running the latest version of the InvenTree source code.
!!! info "Tagged Version"
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
Run the following command to ensure that the InvenTree database is updated:
```
docker compose run inventree-server invoke update
```
!!! info "Skip Backup"
By default, the `invoke update` command performs a database backup. To skip this step, add the `--skip-backup` flag
### Start Containers
Now restart the docker containers:
```
docker compose up -d
```
## Data Backup
Database and media files are stored external to the container, in the volume location specified in the `docker-compose.yml` file. It is strongly recommended that a backup of the files in this volume is performed on a regular basis.
Read more about [data backup](./backup.md).
### Exporting Database as JSON
To export the database to an agnostic JSON file, perform the following command:
```
docker compose run inventree-server invoke export-records -f /home/inventree/data/data.json
```
This will export database records to the file `data.json` in your mounted volume directory.

317
docs/docs/start/install.md Normal file
View File

@ -0,0 +1,317 @@
---
title: Install InvenTree
---
## Bare Metal Setup
!!! tip "Installer"
There is an [installer](./installer.md) available - we recommend using that method.
!!! tip "Docker Guide"
This guide is for a *bare metal* InvenTree installation. If you want to install using Docker refer to the [Docker Setup Guide](./docker.md)
Follow the instructions below to install the required system packages, python modules, and InvenTree source code.
!!! warning "Experienced Users Only"
The following instructions assume a reasonably advanced level of system administration knowledge for a linux based OS
### Install System Packages
Install required system packages (as superuser):
!!! warning "OS Specific Requirements"
The following packages are required on a debian system. A different distribution may require a slightly different set of packages
!!! info "Python Version"
InvenTree requires a modern Python version check [here](https://github.com/inventree/InvenTree/blob/master/CONTRIBUTING.md#target-version) for the current minimums.
```
sudo apt-get update
sudo apt-get install \
python3 python3-dev python3-pip python3-invoke python3-venv \
git gcc g++ gettext gnupg \
poppler-utils libpango-1.0-0 libpangoft2-1.0-0 \
libjpeg-dev webp
```
!!! warning "Weasyprint"
On some systems, the dependencies for the `weasyprint` package might not be installed. Consider running through the [weasyprint installation steps](https://weasyprint.readthedocs.io/en/stable/install.html) before moving forward.
### Create InvenTree User
!!! warning "Running as Root"
It is highly recommended that the InvenTree server is not run under root. The deployment instructions assume that InvenTree is installed and run from a different user account.
Create a user account from which we will run the server:
```
sudo useradd -m -d /home/inventree -s /bin/bash inventree
```
InvenTree source code, log files, etc will be located under the `/home/inventree/` directory.
Switch to the `inventree` user so commands are performed in the correct context:
```
sudo su inventree
```
### Create Required Directories
In addition to the location where the InvenTree source code is located, you will need to create some directories for storing data which will be served to the user (and thus must be available to the webserver). The location of these directories must be provided to the server via the [configuration options](./config.md).
#### Static Files
InvenTree requires a directory for storage of [static files](./config.md#static-file-storage).
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details
#### Media Files
InvenTree requires a directory for storage of [user uploaded files](./config.md#uploaded-file-storage)
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details
#### Backup Directory
Location for storing [database backups](./config.md#backup-file-storage)
### Download Source Code
Download InvenTree source code, into the `./src` directory:
```
git clone https://github.com/inventree/inventree src
```
!!! info "Main Branch = Development"
The "main" branch of the InvenTree code base represents the "latest" (development) code. If you would like to use most recent "stable" release, target the `stable` branch.
### Create Virtual Environment
Create a python virtual environment for installing required Python packages and binaries:
```
python3 -m venv env
source ./env/bin/activate
```
!!! info "(env) prefix"
The shell prompt should now display the `(env)` prefix, showing that you are operating within the context of the python virtual environment
### Install InvenTree Packages
The Python packages required by the InvenTree server must be installed into the virtual environment.
```
pip install -U -r src/requirements.txt
```
This installs all required Python packages using pip package manager. It also creates a (default) database configuration file which needs to be edited to meet user needs before proceeding (see next step below).
## Create Database
As part of the initial setup, an empty database needs to be created. Follow the instructions below particular to your database engine of choice:
### PostgreSQL
#### Install PostgreSQL
Install required system packages:
!!! info "Sudo Actions"
Perform sudo actions from a separate shell, as 'inventree' user does not have sudo access
```
sudo apt-get install postgresql postgresql-contrib libpq-dev
```
And start the postgresql service:
```
sudo service postgresql start
```
#### Create Database and User
We need to create new database, and a postgres user to allow database access.
```
sudo -u postgres psql
```
You should now be in an interactive database shell:
```
create database inventree;
create user myuser with encrypted password 'mypass';
grant all privileges on database inventree to myuser;
```
!!! info "Username / Password"
You should change the username and password from the values specified above. This username and password will also be for the InvenTree database connection configuration.
#### Install Python Bindings
The PostgreSQL python binding must also be installed (into your virtual environment):
```
pip3 install psycopg2 pgcli
```
### MySQL / MariaDB
#### Install Backend
To run InvenTree with the MySQL or MariaDB backends, a number of extra packages need to be installed:
!!! info "Sudo Actions"
Perform sudo actions from a separate shell, as 'inventree' user does not have sudo access
```
sudo apt-get install mysql-server libmysqlclient-dev
```
#### Install Python Bindings
Install the python bindings for MySQL (into the python virtual environment).
```
pip3 install mysqlclient mariadb
```
#### Create Database
Assuming the MySQL server is installed and running, login to the MySQL server as follows:
```
sudo mysql -u root
```
Create a new database as follows:
```
mysql> CREATE DATABASE inventree;
```
Create a new user with complete access to the database:
```
mysql> CREATE USER 'myuser'@'%' IDENTIFIED WITH mysql_native_password BY 'mypass';
mysql> GRANT ALL ON inventree.* TO 'myuser'@'%';
mysql> FLUSH PRIVILEGES;
```
Exit the mysql shell:
```
mysql> EXIT;
```
!!! info "Username / Password"
You should change the username and password from the values specified above. This username and password will also be for the InvenTree database connection configuration.
## Configure InvenTree Options
Once the required software packages are installed and the database has been created, the InvenTree server options must be configured.
!!! tip "Configuration Options"
InvenTree configuration can be performed using environment variables, or the `config.yaml` configuration file (or a combination of both).
!!! info "Config Guidelines"
Refer to the [configuration guidelines](./config.md) for full details.
!!! warning "Configure Database"
Ensure database settings are correctly configured before proceeding to the next step! In particular, check that the database connection settings match the database you have created in the previous step.
## Initialize Database
The database has been configured above, but is currently empty.
### Schema Migrations
Run the following command to initialize the database with the required tables.
```
cd /home/inventree/src
invoke update
```
### Create Admin Account
Create a superuser (admin) account for the InvenTree installation:
```
invoke superuser
```
!!! success "Ready to Serve"
The InvenTree database is now fully configured, and ready to go.
## Start Server
### Development Server
The InvenTree database is now setup and ready to run. A simple development server can be launched from the command line.
The InvenTree development server is useful for testing and configuration - and it may be wholly sufficient for a small-scale installation.
Refer to the [development server instructions](./development.md) for further information.
### Production Server
In a production environment, a more robust server setup is required.
Refer to the [production server instructions](./production.md) for further information.
## Updating InvenTree
Administrators wishing to update InvenTree to the latest version should follow the instructions below. The commands listed below should be run from the InvenTree root directory.
!!! info "Update Database"
It is advisable to [backup the InvenTree database](./backup.md) before performing these steps. The particular backup procedure may depend on your installation details.
### Stop InvenTree Server
Ensure the InvenTree server is stopped. This will depend on the particulars of your database installation.
!!! info "Stop Server"
The method by which the InvenTree server is stopped depends on your particular installation!
### Update Source Code
Update the InvenTree source code to the latest version (or a particular commit if required).
For example, pull down the latest InvenTree sourcecode using Git:
```
git pull origin master
```
!!! info "Release Versions"
If you are using a particular version of InvenTree, you may wish to target a specific code branch or tag, instead of just pulling down latest master
### Perform Database Migrations
Updating the database is as simple as calling the `update` script:
```
invoke update
```
!!! info "Skip Backup"
By default, the `invoke update` command performs a database backup. To skip this step, add the `--skip-backup` flag
This command performs the following steps:
* Ensure all rquired packages are installed and up to date
* Perform required database schema changes
* Run the user through any steps which require interaction
* Collect any new or updated static files
### Restart Server
Ensure the InvenTree server is restarted. This will depend on the particulars of your database installation.

135
docs/docs/start/installer.md Normal file
View File

@ -0,0 +1,135 @@
---
title: InvenTree Installer
---
## Install
The package installer places the app files in `/opt/inventree`, the configs in `/etc/inventree` and data (static, media and database) in `/opt/inventree/data` (see [Moving Data](#moving-data) for details).
Supported OSs are Debian 11 and Ubuntu 20.04 LTS.
### Quick Script
```bash
wget -qO install.sh https://get.inventree.org && bash install.sh
```
This script does all manual steps without any input. The installation might take up to 5-10 minutes to finish.
#### Performed steps
The install script:
- checks if the current OS is supported
- installs packages needed for getting the packages keys
- executes the manual steps listed below
#### Script Options
The install script supports pulling packages from different branches and publishers.
Defaults are to use branch `stable` and publisher `inventree`.
To install from branch master and publisher matmair the install command would be.
```bash
install master matmair
```
Furthermore there are several command flags for advanced usage:
`--help` to show all options
`--version` to print the version of the install script
`--dry-run` to print but not execute the commands that would change system files
### Manual Install
The steps below are for Ubuntu 20.04 LTS, the current instructions for Ubuntu and Debian can be found [here](https://packager.io/gh/inventree/InvenTree).
Add the key needed for validating the packages.
```bash
wget -qO- https://dl.packager.io/srv/inventree/InvenTree/key | sudo apt-key add -
```
Add the package list to the package manager source list.
```bash
sudo wget -O /etc/apt/sources.list.d/inventree.list https://dl.packager.io/srv/inventree/InvenTree/stable/installer/ubuntu/20.04.repo
```
Update the local package index.
```bash
sudo apt-get update
```
Install the InvenTree package itself. This step might take multiple minutes.
```bash
sudo apt-get install inventree
```
### Options
#### Debug Outputs
Extra debug messages are printed if the environment variable `SETUP_DEBUG` is set. This exposes passwords.
#### External Calls
By default, a public AWS service is used to resolve the public IP address of the server. To prevent this the environment variable `SETUP_NO_CALLS` must be set to `true`.
#### Admin User
By default, an admin user is automatically generated with username `admin`, mail `admin@example.com` and a dynamic password that is saved to `/etc/inventree/admin_password`.
These values can be customised with the environment variables `INVENTREE_ADMIN_USER`, `INVENTREE_ADMIN_EMAIL` and `INVENTREE_ADMIN_PASSWORD`.
To stop the automatic generation of an admin user, generate an empty file needs to be placed at `/etc/inventree/admin_password`.
#### Webconfig
By default, InvenTree is served internally on port 6000 and then proxied via Nginx. The config is placed in `/etc/nginx/sites-enabled/inventree.conf` and overwritten on each update. The location can be set with the environment variable `SETUP_NGINX_FILE`.
This only serves an HTTP version of InvenTree, to use HTTPS (recommended for production) or customise any further an additional config file should be used.
#### Extra python packages
Extra python packages can be installed by setting the enviroment variable `SETUP_EXTRA_PIP`.
#### Database Options
The used database backend can be configured with enviroment variables (before the first setup) or in the config file after the installation. Check the [configuration section](./config.md#database-options) for more information.
## Moving Data
To change the data storage location, link the new location to `/opt/inventree/data`.
A rough outline of steps to achieve this could be:
- shut down the app service(s) `inventree` and webserver `nginx`
- copy data to the new location
- check everything was transferred successfully
- delete the old location
- create a symlink from the old location to the new one
- start up the services again
## Updating InvenTree
To update InvenTree run `apt install --only-upgrade inventree` - this might need to be run as a sudo user.
## Controlling InvenTree
### Services
InvenTree installs multiple services that can be controlled with your local system runner (`service` or `systemctl`).
The service `inventree` controls everything, `inventree-web` the (internal) webserver and `inventree-worker` the background worker(s).
More instances of the worker can be instantiated from the command line. This is only meant for advanced users.
This sample script launches 3 services. By default, 1 is launched.
```bash
inventree scale worker=3
```
### Environment Variables
The CLI can be used to permanently modify the environment variables used while executing the app server or workers.
To set variables use
```bash
inventree config:set ENV_VAR=123
```
To read out all variables use
```bash
inventree config
```
!!! warning "Keep things repeatable"
All CLI settings are lost when the package is uninstalled.
Use the config file where possible as it is kept on uninstall and can easily be synced across instances. Environment variables are a good place for passwords (but not the secret_key).
## Architecture
The packages are provided by [packager.io](https://packager.io/). They are built each time updates are pushed to GitHub and released about 10 minutes later. The local package index must be updated to see the new release in the package manager.
The package sets up [services](#controlling-inventree) that run the needed processes as the unprivileged user `inventree`. This keeps the privileges of InvenTree as low as possible.
A CLI is provided to interface with low-level management functions like [variable management](#enviroment-variables), log access, commands, process scaling, etc.

162
docs/docs/start/intro.md Normal file
View File

@ -0,0 +1,162 @@
---
title: Setup Introduction
---
!!! info "Fast install"
A quick-and-easy install can be done done with the following one-liner.
```bash
wget -qO install.sh https://get.inventree.org && bash install.sh
```
Read more about the [installer](./installer.md).
## Introduction
InvenTree can be self-hosted with minimal system requirements. Multiple database back-ends are supported, allowing for flexibility where required.
The InvenTree server ecosystem consists of the following components:
### Database
A persistent database is required for data storage. InvenTree can be used with any of the following database backends:
* PostgreSQL
* MySQL / MariaDB
* SQLite
!!! warning "SQLite"
While SQLite provides a simpler setup and is useful for a development environment, we strongly recommend against using it for a production environment. Use PostgreSQL or MySQL instead
Database selection should be determined by your particular installation requirements.
### Media Files
Uploaded media files (images, attachments, reports, etc) are stored to a persistent storage volume.
### Web Server
The bulk of the InvenTree code base supports the custom web server application. The web server application services user requests and facilitates database access.
The webserver code also provides a first-party API for performing database query actions.
Once a database is setup, you need a way of accessing the data. InvenTree provides a "server" application out of the box, but this may not scale particularly well with multiple users. Instead, InvenTree can be served using a webserver such as [Gunicorn](https://gunicorn.org/). For more information see the [deployment documentation](./production.md).
### Background Tasks
A separate application handles management of [background tasks](../settings/tasks.md), separate to user-facing web requests.
## OS Requirements
The InvenTree documentation assumes that the operating system is a debian based Linux OS. Some installation steps may differ for different systems.
!!! warning "Installing on Windows"
Installation on Windows is *not guaranteed* to work (at all). To install on a Windows system, it is highly recommended that you [install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10#manual-installation-steps), and then follow installation procedure from within the WSL environment.
!!! success "Docker"
Installation on any OS is simplified by following the [docker setup guide](../docker).
## Python Requirements
InvenTree runs on [Python](https://python.org).
!!! warning "Python Version"
InvenTree requrires Python 3.9 (or newer). If your system has an older version of Python installed, you will need to follow the update instructions for your OS.
### Invoke
InvenTree makes use of the [invoke](https://www.pyinvoke.org/) python toolkit for performing various administrative actions.
!!! warning "Invoke Version"
InvenTree requires invoke version 1.4.0 or newer. Some platforms may be shipped with older versions of invoke!
To display a list of the available InvenTree administration actions, run the following commands from the top level source directory:
```
invoke --list
```
### Virtual Environment
Installing the required Python packages inside a virtual environment allows a local install separate to the system-wide Python installation. While not strictly necessary, using a virtual environment is **highly recommended** as it prevents conflicts between the different Python installations.
You can read more about Python virtual environments [here](https://docs.python.org/3/tutorial/venv.html).
!!! info "Virtual Environment"
The installation intstruction assume that a virtual environment is configured
`cd` into the InvenTree directory, and create a virtual environment with the following command:
```
python3 -m venv env
```
### Activating a Virtual Environment
The virtual environment needs to be activated to ensure the correct python binaries and libraries are used. The InvenTree instructions assume that the virtual environment is always correctly activated.
To configure Inventree inside a virtual environment, ``cd`` into the inventree base directory and run the following command:
```
source env/bin/activate
```
!!! info "Activate Virtual Environment"
if
```
source env/bin/activate
```
is not working try
```
. env/bin/activate
```
This will place the current shell session inside a virtual environment - the terminal should display the ``(env)`` prefix.
## InvenTree Source Code
InvenTree source code is distributed on [GitHub](https://github.com/inventree/inventree/), and the latest version can be downloaded (using Git) with the following command:
```
git clone https://github.com/inventree/inventree/
```
Alternatively, the source can be downloaded as a [.zip archive](https://github.com/inventree/InvenTree/archive/master.zip).
!!! info "Updating via Git"
Downloading the source code using Git is recommended, as it allows for simple updates when a new version of InvenTree is released.
## Installation Guides
There are multiple ways to get an InvenTree server up and running, of various complexity (and robustness)!
### Docker
The recommended method of installing InvenTree is to use [docker](https://www.docker.com). InvenTree provides out-of-the-box support for docker and docker compose, which provides a simple, reliable and repeatable pipeline for integration into your production environment.
Refer to the following guides for further instructions:
- [**Docker development server setup guide**](./docker_dev.md)
- [**Docker production server setup guide**](./docker.md)
### Bare Metal
If you do not wish to use the docker container, you will need to manually install the required packages and follow through the installation guide.
Refer to the following guides for further instructions:
- [**Bare metal development server setup guide**](./development.md)
- [**Bare metal production server setup guide**](./install.md)
## Debug Mode
By default, the InvenTree web server is configured to run in [DEBUG mode](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-DEBUG).
Running in DEBUG mode provides many handy development features, however it is strongly recommended *NOT* to run in DEBUG mode in a production environment. This recommendation is made because DEBUG mode leaks a lot of information about your installation and may pose a security risk.
So, for a production setup, you should set `INVENTREE_DEBUG=false` in the [configuration options](./config.md).
### Potential Issues
Turning off DEBUG mode creates further work for the system administrator. In particular, when running in DEBUG mode, the InvenTree web server natively manages *static* and *media* files, which means that the InvenTree server can run "monolithically" without the need for a separate web server.
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details

95
docs/docs/start/migrate.md Normal file
View File

@ -0,0 +1,95 @@
---
title: Migrating Data
---
## Migrating Data to a Different Database
In the case that data needs to be migrated from one database installation to another, the following procedure can be used to export data, initialize the new database, and re-import the data. The following instructions apply to bare-metal and docker installations, although the particular commands required may vary slightly in each case.
!!! warning "Backup Database"
Ensure that the original database is securely backed up first!
!!! danger "Database Versions"
It is *crucial* that both InvenTree database installations are running the same version of InvenTree software! If this is not the case, data migration may fail, and there is a possibility that data corruption can occur. Ensure that the original database is up to date, by running `invoke update`.
### Export Data
Export the database contents to a JSON file using the following command:
```
invoke export-records -f data.json
```
This will create JSON file at the specified location which contains all database records.
!!! info "Specifying filename"
The filename of the exported file can be specified using the `-f` option. To see all available options, run `invoke export-records --help`
### Initialize New Database
Configure the new database using the normal processes (see [Configuration](./config.md))
!!! warning "InvenTree Version"
Ensure that the *new* installation is running *exactly* the same version of InvenTree as the installation from which you exported the data.
Then, ensure that the database schema are correctly initialized in the new database:
```
invoke update
```
This step ensures that the required database tables exist, and are at the correct schema version, which must be the case before data can be imported.
### Import Data
The new database should now be correctly initialized with the correct table structures requried to import the data. Run the following command to load the databased dump file into the new database.
!!! warning "Empty Database"
If the database is not *empty* (i.e. it contains data records) then the data import process will fail. If errors occur during the import process, run `invoke import-records` with the `-c` option to clear all existing data from the database.
```
invoke import-records -c -f data.json
```
!!! info "Import Filename"
A different filename can be specified using the `-f` option
!!! warning "Character Encoding"
If the character encoding of the data file does not exactly match the target database, the import operation may not succeed. In this case, some manual editing of the database JSON file may be required.
## Migrating Data to Newer Version
If you are updating from an older version of InvenTree to a newer version, the migration steps outlined above *do not apply*.
An update from an old version to a new one requires not only that the database *schema* are updated, but the *data* held within the database must be updated in the correct sequence.
Follow the sequence of steps below to ensure that the database records are updated correctly.
!!! warning "Backup Database"
When updating, it is always prudent to ensure that the database records are backed up first
### Stop InvenTree
Ensure that the InvenTree server and worker processes are not running.
!!! tip "Example: Docker"
If running under docker, run `docker compose down`
### Fetch New InvenTree Version
Download the specific version of InvenTree you wish to update to.
!!! tip "Example: Docker"
If running under docker, edit `docker-compose.yml` and then run `docker compose pull`
### Run Update Process
Run the update and migration script using `invoke update`. This ensures that the database schema and records are udpated in the correct order.
### Restart Server
Once the migration process completes, the database records are now updated! Restart the server and the process is complete.
!!! tip "Example: Docker"
If running under docker, run `docker compose up -d`

111
docs/docs/start/production.md Normal file
View File

@ -0,0 +1,111 @@
---
title: Production Server
---
## Production Server
!!! warning "Installation"
Before continuing, ensure that the [installation steps](./install.md) have been completed.
The following instructions provide a reasonably performant server, using [gunicorn](https://gunicorn.org/) as a webserver, and [supervisor](http://supervisord.org/) as a process manager.
For alternative deployment methods, django apps provide multiple deployment methods - see the [Django documentation](https://docs.djangoproject.com/en/2.2/howto/deployment/).
There are also numerous online tutorials describing how to deploy a Django application either locally or on an online platform.
### Gunicorn
The InvenTree web server is hosted using [Gunicorn](https://gunicorn.org/). Gunicorn is a Python WSGI server which provides a multi-worker server which is well suited to handling multiple simultaneous requests. Gunicorn is a solid choice for a production server which is easy to configure and performs well in a multi-user environment.
### Supervisor
[Supervisor](http://supervisord.org/) is a process control system which monitors and controls multiple background processes. It is used in the InvenTree production setup to ensure that the server and background worker processes are always running.
## Gunicorn
Gunicorn should have already been installed (within the python virtual environment) as part of the installation procedure.
A simple gunicorn configuration file is also provided. This configuration file can be edited if different server settings are required
### Test Gunicorn Server
First, let's confirm that the gunicorn server is operational.
!!! info "Virtual Environment"
Don't forget to activate the python virtual environment
```
cd /home/InvenTree
source ./env/bin/activate
cd src/InvenTree
/home/inventree/env/bin/gunicorn -c gunicorn.conf.py InvenTree.wsgi -b 127.0.0.1:8000
```
This should start the gunicorn server as a foreground process.
Check that you can access the InvenTree web server [in your browser](http://127.0.0.1:8000):
### Stop Gunicorn Server
Once the gunicorn server is operational, kill the server with <kbd>Ctrl</kbd>+<kbd>c</kbd>
## Supervisor
We will use [supervisor](http://supervisord.org/) as a process monitor, to ensure the web server and background worker processes are automatically started, and restarted if something goes wrong.
### Install Supervisor
!!! info "Sudo Actions"
Perform sudo actions from a separate shell, as 'inventree' user does not have sudo access
```
sudo apt-get install supervisor
```
### Configure Supervisor
!!! warning "Configuration Override"
If you already have supervisor installed on your system, you will not want to override your existing configuration file.
In this case, edit the existing configuration file at `/etc/supervisord.conf` to integrate the InvenTree processes
Copy the supervisor configuration file:
```
sudo cp /home/inventree/src/deploy/supervisord.conf /etc/supervisord.conf
```
### Start Supervisor Daemon
```
sudo supervisord
```
### Check Server
Check that the InvenTree [web server is running](http://localhost:8000).
### View Process Status
The process status can be viewed [in your web browser](http://localhost:9001).
## Production Ready
The InvenTree server (and background task manager) should now be running!
### Static and Media Files
In addition to the InvenTree server, you will need a method of delivering static and media files (this is *not* handled by the InvenTree server in a production environment).
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details
### Next Steps
You (or your system administrator) may wish to perform further steps such as placing the InvenTree server behind a reverse-proxy such as [nginx](https://www.nginx.com/).
As production environment options are many and varied, such tasks are outside the scope of this documentation.
There are many great online tutorials about running django applications in production!
As a starting point, you can refer to the [docker production example](./docker_prod.md) for a demonstration of running InvenTree behind a nginx proxy.

28
docs/docs/start/serving_files.md Normal file
View File

@ -0,0 +1,28 @@
---
title: Serving Static and Media Files
---
## Serving Files
In production, the InvenTree web server software *does not* provide hosting of static files, or user-uploaded (media) files.
When running in [production mode](./production.md) (i.e. the `INVENTREE_DEBUG` flag is disabled), a separate web server is required for serving *static* and *media* files. In `DEBUG` mode, the django webserver facilitates delivery of *static* and *media* files, but this is explicitly not suitable for a production environment.
!!! into "Read More"
You can find further information in the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/deployment/).
There are *many* different ways that a sysadmin might wish to handle this - and it depends on your particular installation requirements.
The [docker production example](./docker_prod.md) provides an example using [Nginx](https://www.nginx.com/) to serve *static* and *media* files, and redirecting other requests to the InvenTree web server itself.
You may use this as a jumping off point, or use an entirely different server setup.
#### 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.
#### Media Files
It is highly recommended that the *media* files are served in such a way that user authentication is required.
Refer to the [docker production example](./docker_prod.md) for a demonstration of using nginx to serve media files only to authenticated users, and forward authentication requests to the InvenTree web server.