Introduction

Introduction¶

A functional InvenTree server can be hosted with minimal setup requirements. Multiple installation methods and database back-ends are supported, allowing for flexibility where required.

Production Ready

InvenTree is designed to be a production-ready application, and can be deployed in a variety of environments. The following instructions are designed to help you get started with a production setup. For a development setup, refer to the devcontainer setup guide.

Installation Methods¶

To quickly jump to a specific installation method, refer to the following links:

Docker Recommended

The recommended method of installing InvenTree is to follow our docker setup guide. 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.

Configuration Options¶

Independent of the preferred installation method, InvenTree provides a number of configuration options which can be used to customize the server environment.

System Components¶

The InvenTree server ecosystem consists of the following components:

Database¶

A persistent database is required for data storage. By default, InvenTree is configured to use PostgreSQL - and this is the recommended database backend to use. However, InvenTree can also be configured to connect to any database backend supported by Django

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 provides access to the API for performing database query actions.

InvenTree uses Gunicorn as the web server - a Python WSGI HTTP server.

Background Tasks¶

A separate application handles management of background tasks, separate to user-facing web requests. The background task manager is required to perform asynchronous tasks, such as sending emails, generating reports, and other long-running tasks.

InvenTree uses django-q2 as the background task manager.

File Storage¶

Uploaded media files (images, attachments, reports, etc) and static files (javascript, html) are stored to a persistent storage volume. A file server is required to serve these files to the user.

InvenTree uses Caddy as a file server, which is configured to serve both static and media files. Additionally, Caddy provides SSL termination and reverse proxy services.

OS Requirements¶

The InvenTree documentation assumes that the operating system is a debian based Linux OS. Some installation steps may differ for different systems.

Installing on Windows

To install on a Windows system, you should install WSL, and then follow installation procedure from within the WSL environment.

Docker

Installation on any OS is simplified by following the docker setup guide.

Python Requirements¶

InvenTree requires a minimum Python version of 3.9. 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 python toolkit for performing various administrative actions.

Invoke Version

InvenTree requires invoke version 2.0.0 or newer. Some platforms may be shipped with older versions of invoke!

Updating Invoke

To update your invoke version, run pip install -U invoke

To display a list of the available InvenTree administration actions, run the following commands from the top level source directory:

invoke --list

This provides a list of the available invoke commands - also displayed below:

Available tasks:

  backup               Backup the database and media files.
  clean-settings       Clean the setting tables of old settings.
  delete-data          Delete all database records!
  export-records       Export all database records to a file.
  frontend-build       Build frontend.
  frontend-check       Check if frontend is available.
  frontend-compile     Generate react frontend.
  frontend-dev         Start frontend development server.
  frontend-download    Download a pre-build frontend from GitHub if you dont
                       want to install nodejs on your machine.
  frontend-install     Install frontend requirements.
  frontend-trans       Compile frontend translations.
  gunicorn             Launch a gunicorn webserver.
  import-fixtures      Import fixture data into the database.
  import-records       Import database records from a file.
  install              Installs required python packages.
  migrate              Performs database migrations.
  plugins              Installs all plugins as specified in 'plugins.txt'.
  rebuild-models       Rebuild database models with MPTT structures.
  rebuild-thumbnails   Rebuild missing image thumbnails.
  remove-mfa           Remove MFA for a user.
  render-js-files      Render templated javascript files (used for static
                       testing).
  restore              Restore the database and media files.
  schema               Export current API schema.
  server               Launch a (development) server using Django's in-built
                       webserver.
  setup-dev            Sets up everything needed for the dev environment.
  setup-test           Setup a testing environment.
  showmigrations       Show the migration status of the database.
  static               Copies required static files to the STATIC_ROOT
                       directory, as per Django requirements.
  superuser            Create a superuser/admin account for the database.
  test                 Run unit-tests for InvenTree codebase.
  test-translations    Add a fictional language to test if each component is
                       ready for translations.
  translate            Rebuild translation source files. Advanced use only!
  translate-stats      Collect translation stats.
  update               Update InvenTree installation.
  version              Show the current version of InvenTree.
  wait                 Wait until the database connection is ready.
  worker               Run the InvenTree background worker process.

Default task: version

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.

Virtual Environment

The installation instruction 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

Or, if that does not work, 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, 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.

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.

Debug Mode¶

By default, a production InvenTree installation is configured to run with DEBUG mode disabled.

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.

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.