From 3db774d1fe5d43758514f57f784c3e24451f6a15 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Tue, 16 Feb 2021 21:29:53 +1100 Subject: [PATCH 01/28] Add docs for email backend --- _includes/config.yaml | 23 +++++++++++++++++++++++ docs/start/config.md | 20 +++++++++++++++++++- 2 files changed, 42 insertions(+), 1 deletion(-) diff --git a/_includes/config.yaml b/_includes/config.yaml index 18e3197..38b46f7 100644 --- a/_includes/config.yaml +++ b/_includes/config.yaml @@ -56,6 +56,29 @@ currencies: - NZD - USD +# Email backend configuration +# Ref: https://docs.djangoproject.com/en/dev/topics/email/ +# Available options: +# host: Email server host address +# port: Email port +# username: Account username +# password: Account password +# prefix: Email subject prefix +# tls: Enable TLS support +# ssl: Enable SSL support + +# Alternatively, these options can all be set using environment variables +# Refer to the InvenTree documentation for more information + +email: + host: '' + port: 25 + username: '' + password: '' + prefix: '[InvenTree] ' + tls: False + ssl: False + # Set debug to False to run in production mode debug: True diff --git a/docs/start/config.md b/docs/start/config.md index 6df457a..4159664 100644 --- a/docs/start/config.md +++ b/docs/start/config.md @@ -69,7 +69,7 @@ Database options are specified under the *database* heading in the configuration The following database options can be configured: -| Environment Variable | Settings File | Description | +| Environment Variable | COnfig File | Description | | --- | --- | --- | | INVENTREE_DB_ENGINE | database.ENGINE | Database backend | | INVENTREE_DB_NAME | database.NAME | Database name | @@ -121,6 +121,24 @@ It is then up to the database adminstrator to create a new PostgreSQL database t The database options (in the `config.yaml` file) then need to be adjusted to communicate the PostgreSQL backend. Refer to the [Django docs](https://docs.djangoproject.com/en/dev/ref/databases/) for further information. +### Email Backend + +InvenTree email settings must be correctly configured to allow sending emails. + +Email options are specified under the *email* heading in the configuration file. Alternatively email settings can be set via environment variables. + +The following email options can be configured: + +| Environment Variable | Config File | Description | +| --- | --- | --- | +| INVENTREE_EMAIL_HOST | email.host | Email service host address | +| INVENTREE_EMAIL_PORT | email.port | Email service host port | +| INVENTREE_EMAIL_USERNAME | email.username | Account username | +| INVENTREE_EMAIL_PASSWORD | email.password | Account password | +| INVENTREE_EMAIL_PREFIX | email.prefix | Email subject prefix - default is "[InvenTree] " | +| INVENTREE_EMAIL_TLS | email.tls | Enable TLS support | +| INVENTREE_EMAIL_SSL | email.ssl | Enable SSL support | + ### Allowed Hosts / CORS By default, all hosts are allowed, and CORS requests are enabled from any origin. **This is not secure and should be adjusted for your installation**. These options can be changed in the configuration file. From 6096b82ae12bd1e0fefa23d6248cdee435781a31 Mon Sep 17 00:00:00 2001 From: Oliver Date: Wed, 7 Apr 2021 21:11:05 +1000 Subject: [PATCH 02/28] Update 0.1.8.md --- docs/releases/0.1.8.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/releases/0.1.8.md b/docs/releases/0.1.8.md index 5df9720..add1a44 100644 --- a/docs/releases/0.1.8.md +++ b/docs/releases/0.1.8.md @@ -37,4 +37,5 @@ title: Release 0.1.8 | --- | --- | | [#1407](https://github.com/inventree/InvenTree/pull/1407) | Fixes unncessary column requirement when importing BOM | | [#1430](https://github.com/inventree/InvenTree/pull/1430) | Fixes error thrown when migrating from very old data set | +| [#1441](https://github.com/inventree/InvenTree/pull/1441) | Fixes template rendering error if git not available on system path | From 9e2e1e1a3aefac091aa66c06d7d6a0a92e66211a Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Tue, 23 Mar 2021 20:32:55 +1100 Subject: [PATCH 03/28] Update FAQ section (cherry picked from commit ced3f794fa56ebb915d0047fc8e2613d51112dda) --- docs/faq.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/faq.md b/docs/faq.md index 73bbe37..bf0fc10 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -15,3 +15,19 @@ Before [raising an issue](https://github.com/inventree/inventree/issues), try ha or Ctrl + F5 + +### Command 'inv' / 'invoke' not found + +If the `inv` or `invoke` command does not work, it means that the [invoke](https://pypi.org/project/invoke/) python library has not been correctly installed. + +Update the installed python packages with PIP: + +``` +pip3 install -U -r requirements.txt +``` + +### ModuleNotFoundError: No module named 'django' + +Most likely you are trying to run the InvenTree server from outside the context of the virtual environment where the required python libraries are installed. + +Always activate the virtual environment before running server commands! \ No newline at end of file From bb99884d6832623d991a54466ead5ab07dde06d2 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Wed, 24 Mar 2021 21:20:40 +1100 Subject: [PATCH 04/28] Begin deployment docs (cherry picked from commit dd27ae2dd83256799147ab06f8f57b4d1f920d8e) --- docs/faq.md | 4 ++ docs/start/deploy.md | 72 ++++++++++++++++++++++ docs/start/install.md | 130 ++-------------------------------------- docs/start/intro.md | 135 ++++++++++++++++++++++++++++++++++++++++++ docs/start/tasks.md | 6 ++ mkdocs.yml | 5 +- 6 files changed, 226 insertions(+), 126 deletions(-) create mode 100644 docs/start/intro.md create mode 100644 docs/start/tasks.md diff --git a/docs/faq.md b/docs/faq.md index bf0fc10..f0d70fe 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -16,6 +16,10 @@ or Ctrl + F5 +### Problems Installing on Windows + +InvenTree installation is not officially supported natively on Windows. Install using the WSL framework. + ### Command 'inv' / 'invoke' not found If the `inv` or `invoke` command does not work, it means that the [invoke](https://pypi.org/project/invoke/) python library has not been correctly installed. diff --git a/docs/start/deploy.md b/docs/start/deploy.md index 4d94b17..6f0292f 100644 --- a/docs/start/deploy.md +++ b/docs/start/deploy.md @@ -10,6 +10,78 @@ Django apps provide multiple deployment methods - see the [Django documentation] There are also numerous online tutorials describing how to deploy a Django application either locally or on an online platform. +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. + +## Initial Setup + +### Install System Packages + +Install required system packages (as superuser). + +First, install required system packages as per the [OS requirements](../intro#os-requirements). + +Then, install the supervisor process manager: + +``` +sudo apt-get install supervisor +``` + +### Create InvenTree User + +It is highly recommended that the InvenTree server is not run under root. Create a user account from which we will run the server: + +``` +sudo useradd --create-home 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 +``` + +### Download Source Code + +Download InvenTree source code, into the `./src` directory: + +``` +cd /home/inventree +git clone https://github.com/inventree/inventree src +``` + +### Create Virtual Environment + +Create a python virtual environment for installting required Python packages and binaries: + +``` +python3 -m venv env +source ./env/bin/activate +``` + +The shell prompt should now display the `(env)` prefix. + +### Install Python Packages + +``` +pip3 install -U -r src/requirements.txt +``` + +This command will install all of the python binaries and library files required for the InvenTree installation. + +### Create Required Directories + +``` +mkdir log static media +``` + +This step creates directories required by InvenTree: + +* **log** - Store InvenTree log files +* **static** - Location of static files for the web server +* **media** - Location of uploaded media files + ### Development Server The InvenTree development server is useful for testing and configuration - and it may be wholly sufficient for a small-scale installation. diff --git a/docs/start/install.md b/docs/start/install.md index 5305b06..d1a14b6 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -1,135 +1,17 @@ --- -title: Install InvenTree +title: Installation Instructions --- -## Introduction +## Development Server -The InvenTree server application communicates with a backend database, and serves data to the user(s) via a web framework and an API. Before users can interact with the InvenTree system, the server must be installed and properly configured, and then the server process must be started (at a network location which is accessible to the users). +The following installation instructions can be used to install InvenTree and run a server which provides a simple development environment. -### Supported Databases +!!! warning "Deployment" + Refer to the [deployment instructions](../deploy) to implement a much more robust server setup. -InvenTree can be used by any database backend which is supported by the [Django framework](https://docs.djangoproject.com/en/3.0/ref/databases/): +## Download Code -* SQLite -* PostgreSQL -* MariaDB -* MySQL -* Oracle -Database selection should be determined by your particular installation requirements. By default, InvenTree uses SQLite which provides a simple file-based database that allows a quick setup for development and testing. - -### Serving Data - -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](../deploy). - -## OS Requirements - -To install a complete *development* environment for InvenTree, follow the steps presented below. A production environment will require further work as per the particular application requirements. - -Installing and running InvenTree should be possible on most operating systems, as it requires only cross-platform Python libraries. - -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. - -### Linux - -The InvenTree documentation assumes that the operating system is a Linux variant. To install the required python packages to get started on a Linux system, run the following commands: - -``` -sudo apt-get update -sudo apt-get install python3 python3-dev -sudo apt-get install python3-pip python3-invoke -``` - -!!! warning "Sudo" - `apt-get` commands will (most likely) be required to run under sudo. Take care not to run the installation scripts under sudo, as this may alter the system python path and cause the InvenTree installation to not work correctly - -### Windows - -InvenTree can be installed and run from the Windows command line, assuming the following binaries are available in the system PATH: - -- python3 -- pip3 -- invoke - -!!! info "WSL" - - Alternatively, if you are running under the Windows operating system you can install and run InvenTree using the [WSL (Windows Subsystem for Linux)](https://docs.microsoft.com/en-us/windows/wsl/install-win10) framework. Running under WSL provides a Linux compatible layer which simplifies InvenTree installation. - -### FreeBSD - -If you are running the FreeBSD operating system, run the following commands to install the required Python packages: - -``` -pkg install python -pkg install py37-pip -pkg install py37-wheel -pkg install py37-invoke -``` - -## Download Source Code - -Download the InvenTree source code to a local directory. It is recommended to perform this step using git, as this allows the InvenTree installation to be easily updated to the latest version. - -``` -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). - -Once the source is downloaded, cd into the source directory: - -``` -cd /path/to/inventree/ -``` - -*(substitute /path/to/inventree/ with the directory where you have downloaded the source code)*. - -## Python Setup - -To install InvenTree you will need python3 (>3.6) installed, as well as PIP (the Python package manager), and the Invoke tool. - -!!! warning "Python Version" - InvenTree requrires Python 3.6 (or newer). If your system has an older version of Python installed, you will need to follow the update instructions for your OS. - -### Python 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). - -To configure Inventree inside a virtual environment, ``cd`` into the inventree base directory and run the following commands: - -``` -sudo apt-get install python3-venv -python3 -m venv inventree-env -source inventree-env/bin/activate -``` - -!!! note "Activate Virtual Environment" - if - ``` - source inventree-env/bin/activate - ``` - is not working try - ``` - . inventree-env/bin/activate - ``` - -!!! note "Virtual Environment on Windows" - To create and activate a virtual environment in Windows, run the following commands: - ``` - py -m venv inventree-env - .\inventree-env\Scripts\activate - ``` - - Refer to the [official Python documentation](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) to setup a virtual environment on Windows. - -This will place the current shell session inside a virtual environment - the terminal should display the ``(inventree-env)`` prefix. - -!!! warning "Activate virtual environment" - Remember to activate the virtual environment when starting each shell session, before running Inventree commands. This will ensure that the correct environment is being used. - -### Invoke InvenTree setup is performed using the [invoke](https://www.pyinvoke.org/) Python build tool. Various useful scripts are defined in the `tasks.py` file. diff --git a/docs/start/intro.md b/docs/start/intro.md new file mode 100644 index 0000000..6b48b35 --- /dev/null +++ b/docs/start/intro.md @@ -0,0 +1,135 @@ +--- +title: Setup Introduction +--- + +## 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 to store stock information. The database backend must be installed and configured separately to the InvenTree application. + +InvenTree can be used by any database backend which is supported by the [Django framework](https://docs.djangoproject.com/en/3.0/ref/databases/): + +* SQLite +* PostgreSQL +* MariaDB +* MySQL +* Oracle + +Database selection should be determined by your particular installation requirements. By default, InvenTree uses SQLite which provides a simple file-based database that allows a quick setup for development and testing. + +### 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](../deploy). + + +### Background Tasks + +A separate application handles management of [background tasks](../tasks), 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. + +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. + +The following minimum packages are required to be installed on a system level: + +### Debian + +``` +sudo apt-get update +sudo apt-get install python3 python3-dev +sudo apt-get install python3-pip python3-invoke python3-venv +``` + +### FreeBSD + +``` +pkg install python +pkg install py37-pip +pkg install py37-wheel +pkg install py37-invoke +``` + +## Python Requirements + +InvenTree runs on [Python](https://python.org). + +!!! warning "Python Version" + InvenTree requrires Python 3.6 (or newer). If your system has an older version of Python installed, you will need to follow the update instructions for your OS. + +### 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). + +!!! note "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 +``` + +!!! note "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. + +## Downloading 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). + +## Development Setup + +To setup a *simple* development server, refer to the [development instructions](../install). + +These instructions are useful for those wishing to run a development server. This setup may suffice for a small-scale installation with only a small number of users. + +However for a robust server setup which supports high traffic and multiple users, it is highly recommended that the [deployment guide](../deploy) is followed instead. + +## Deployment Guide + +To properly deploy a robust InvenTree server setup, refer to the [deployment instructions](../deploy). + diff --git a/docs/start/tasks.md b/docs/start/tasks.md new file mode 100644 index 0000000..38dfa8f --- /dev/null +++ b/docs/start/tasks.md @@ -0,0 +1,6 @@ +--- +title: Background Tasks +--- + +## Background Tasks + diff --git a/mkdocs.yml b/mkdocs.yml index 7485840..bb61afe 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,9 +43,10 @@ nav: - FAQ: faq.md - Contribute: contribute.md - Getting Started: - - Installation: start/install.md - - Configuration: start/config.md + - Introduction: start/intro.md + - Development: start/install.md - Deploying: start/deploy.md + - Configure: start/config.md - Updating: start/update.md - Migrating: start/migrate.md - Parts: From 3fddd8d2dad7cb50d8c6a92f1868b2867fe01eea Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Wed, 24 Mar 2021 22:23:59 +1100 Subject: [PATCH 05/28] More docs (cherry picked from commit 6386f6921377448a1472145a55f6cd386959b298) --- docs/start/deploy.md | 76 ++++++++++++++++++++++++++++++++++++------- docs/start/install.md | 18 ---------- docs/start/intro.md | 4 +++ 3 files changed, 68 insertions(+), 30 deletions(-) diff --git a/docs/start/deploy.md b/docs/start/deploy.md index 6f0292f..360bc21 100644 --- a/docs/start/deploy.md +++ b/docs/start/deploy.md @@ -12,9 +12,8 @@ There are also numerous online tutorials describing how to deploy a Django appli 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. -## Initial Setup -### Install System Packages +## Install System Packages Install required system packages (as superuser). @@ -26,6 +25,22 @@ Then, install the supervisor process manager: sudo apt-get install supervisor ``` +Next, install the system packages required for your particular database: + +### MySQL + +``` +sudo apt-get install mysql-server libmysqlclient-dev +``` + +### Postgresql + +``` +sudo apt-get install postgresql postgresql-contrib libpq-dev +``` + +### Initial Setup + ### Create InvenTree User It is highly recommended that the InvenTree server is not run under root. Create a user account from which we will run the server: @@ -62,18 +77,10 @@ source ./env/bin/activate The shell prompt should now display the `(env)` prefix. -### Install Python Packages - -``` -pip3 install -U -r src/requirements.txt -``` - -This command will install all of the python binaries and library files required for the InvenTree installation. - ### Create Required Directories ``` -mkdir log static media +mkdir log static media backup ``` This step creates directories required by InvenTree: @@ -81,8 +88,53 @@ This step creates directories required by InvenTree: * **log** - Store InvenTree log files * **static** - Location of static files for the web server * **media** - Location of uploaded media files +* **backup** - Location of database backup files -### Development Server +## Install InvenTree Packages + +The Python packages required by the InvenTree server must be installed into the virtual environment. + +Run the `invoke install` command (from within the src directory): + +``` +cd src +invoke install +``` + +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). + +Additionally, this step creates a *SECRET_KEY* file which is used for the django authentication framework. + +!!! warning "Keep it secret, keep it safe" + The SECRET_KEY file should never be shared or made public. + +You will also need to install the python packages required for your particular database backend: + +### MySQL + +``` +pip3 install mysqlclient +``` + +### Postgresql + +``` +pip3 install psycopg2 +``` + +## Configure InvenTree Options + +Once the required software packages are installed, the database and server options must be configured. + +Edit the configuration file at `/home/inventree/src/InvenTree/config.yaml`. + +!!! info "Config Guidelines" + Refer to the [configuration guidelines](../config) for full details. + +!!! warning "Configure Database" + Ensure database settings are correctly configured in `config.yaml` before proceeding to the next step! + +# Development Server The InvenTree development server is useful for testing and configuration - and it may be wholly sufficient for a small-scale installation. diff --git a/docs/start/install.md b/docs/start/install.md index d1a14b6..2e87ea1 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -30,24 +30,6 @@ To display a list of the available configuration scripts, run the following comm inv --list ``` -## Installation - -Now that the source code is downloaded (and optionally you have configured a Python virtual environment), the Python packages required to run InvenTree can be installed. InvenTree is a Python/Django application and relies on the pip package manager. All packages required to develop and test InvenTree are installed via pip. Package requirements can be found in ``requirements.txt``. - - -To setup the InvenTree environment, run the following commands (from the InvenTree source directory): - -``` -inv install -``` - -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). - -Additionally, this step creates a *SECRET_KEY* file which is used for the django authentication framework. - -!!! warning "Keep it secret, keep it safe" - The SECRET_KEY file should never be shared or made public. - ### Database Configuration Once the required packages are installed, the database configuration must be adjusted to suit your particular needs. InvenTree provides a simple default setup which should work *out of the box* for testing and debug purposes. diff --git a/docs/start/intro.md b/docs/start/intro.md index 6b48b35..cf76da2 100644 --- a/docs/start/intro.md +++ b/docs/start/intro.md @@ -74,6 +74,10 @@ InvenTree runs on [Python](https://python.org). !!! warning "Python Version" InvenTree requrires Python 3.6 (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 + ### 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. From 92ed90490773274dbe217bf39e9bc9003aa8b5ea Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Wed, 24 Mar 2021 22:42:32 +1100 Subject: [PATCH 06/28] Updates (cherry picked from commit f919ca2eed0852faea77e9cf0e5e0b4a882bb14f) --- docs/faq.md | 16 +++++++++++++++- docs/start/deploy.md | 20 ++++++++++++++------ docs/start/install.md | 5 ----- 3 files changed, 29 insertions(+), 12 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index f0d70fe..e8c6f9d 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -34,4 +34,18 @@ pip3 install -U -r requirements.txt Most likely you are trying to run the InvenTree server from outside the context of the virtual environment where the required python libraries are installed. -Always activate the virtual environment before running server commands! \ No newline at end of file +Always activate the virtual environment before running server commands! + +### Background Worker "Not Running" + +The background worker process must be started separately to the web-server application. + +From the top-level source directory, run the following command from a separate terminal, while the server is already running: + +``` +invoke worker +``` + +!!! info "Supervisor" + +A better option is to manage the background worker process using a process manager such as supervisor. Refer to the [deployment guide](../start/deploy). diff --git a/docs/start/deploy.md b/docs/start/deploy.md index 360bc21..d50fb00 100644 --- a/docs/start/deploy.md +++ b/docs/start/deploy.md @@ -19,12 +19,6 @@ Install required system packages (as superuser). First, install required system packages as per the [OS requirements](../intro#os-requirements). -Then, install the supervisor process manager: - -``` -sudo apt-get install supervisor -``` - Next, install the system packages required for your particular database: ### MySQL @@ -134,6 +128,10 @@ Edit the configuration file at `/home/inventree/src/InvenTree/config.yaml`. !!! warning "Configure Database" Ensure database settings are correctly configured in `config.yaml` before proceeding to the next step! +## Create Database + +!!! todo "TODO" + # Development Server The InvenTree development server is useful for testing and configuration - and it may be wholly sufficient for a small-scale installation. @@ -159,6 +157,16 @@ inv server -a 192.168.120.1:8000 !!! warning "Not For Production" It should be noted that the *development server* provided with django / InvenTree is probably not suitable for your production environment. Instead, use a proper web-server (such as Gunicorn, below). +## Install Supervisor + +!!! todo "More details here" + +Install the supervisor process manager: + +``` +sudo apt-get install supervisor +``` + ## Gunicorn Following is a simple tutorial on serving InvenTree 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. diff --git a/docs/start/install.md b/docs/start/install.md index 2e87ea1..c12f89a 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -36,11 +36,6 @@ Once the required packages are installed, the database configuration must be adj As part of the previous *install* step, a configuration file (**config.yaml**) is created. The configuration file provides administrators control over various setup options without digging into the Django *settings.py* script. The default setup uses a local sqlite database with *DEBUG* mode enabled. -For further information on installation configuration, refer to the [Configuration](../config) section. - -!!! warning "Configure Database" - Ensure database settings are correctly configured in `config.yaml` before proceeding to the next step! - ### Initialize Database Once install settings are correctly configured (in *config.yaml*) run the initial setup script: From 2f3154fedefcee2868ce1a9590196e6681d7cbe7 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Tue, 30 Mar 2021 21:19:50 +1100 Subject: [PATCH 07/28] Rearrange docs (cherry picked from commit b2667d52a37036d579030b9f3de0cded341e700e) --- docs/admin/tasks.md | 23 +++++++++++++++++++++++ docs/start/config.md | 23 +++++++---------------- docs/start/docker.md | 5 +++++ docs/start/intro.md | 22 ++++++++++++++++++---- docs/start/tasks.md | 6 ------ docs/start/update.md | 3 +++ mkdocs.yml | 6 ++++-- 7 files changed, 60 insertions(+), 28 deletions(-) create mode 100644 docs/admin/tasks.md create mode 100644 docs/start/docker.md delete mode 100644 docs/start/tasks.md diff --git a/docs/admin/tasks.md b/docs/admin/tasks.md new file mode 100644 index 0000000..369f8f3 --- /dev/null +++ b/docs/admin/tasks.md @@ -0,0 +1,23 @@ +--- +title: Background Tasks +--- + +## Background Tasks + +In addition to managing the database and providing a web interface, InvenTree runs various background tasks; + +### Blocking Operations + +Some tasks (such as sending emails or performing bulk database actions) may take a significant amount of time. Instead of delaying the response to the user, these tasks are handled by the background task manager. + +### Periodic Tasks + +Some tasks must be performed on a periodic basis. + +## Django Q + +InvenTree uses the [django-q](https://django-q.readthedocs.io/en/latest/) background task manager. + +## Admin Interface + +Scheduled tasks can be viewed in the InvenTree admin interface. diff --git a/docs/start/config.md b/docs/start/config.md index b997061..7b4d301 100644 --- a/docs/start/config.md +++ b/docs/start/config.md @@ -6,7 +6,10 @@ title: 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. -The Django configuration parameters are found in the normal place (*settings.py*). However the settings presented in this file should not be adjusted as they will alter the core behaviour of the InvenTree application. +InvenTree system settings can be specified in a configuration file, or via environment variables. + +!!! info "Environment Variables" + Settings specified using environment variables take priority ### Configuration File @@ -90,12 +93,6 @@ MySQL database backend is supported with the native Django implemetation. To run * libmysqlclient-dev - *Required for connecting to the MySQL database in Python* * (pip) mysqlclient - *Python package for communication with MySQL database* -To install these required packages, run the following command: - -``` -inv mysql -``` - It is then up to the database adminstrator to create a new MySQL database to store inventree data, in addition to a username/password to access the data. !!! info "MySQL Collation" @@ -111,12 +108,6 @@ PostgreSQL database backend is supported with the native Django implementation. * libpq-dev * (pip3) psycopg2 -To install these required packages, run the following commands: - -``` -inv postgresql -``` - It is then up to the database adminstrator to create a new PostgreSQL database to store inventree data, in addition to a username/password to access the data. The database options (in the `config.yaml` file) then need to be adjusted to communicate the PostgreSQL backend. Refer to the [Django docs](https://docs.djangoproject.com/en/dev/ref/databases/) for further information. @@ -132,19 +123,19 @@ For further information, refer to the following documentation: ### Static File Storage -By default, static files are stored in the local directory `./inventree_static`. This directory should be changed by specifying the `static_root` option in the config file based on the particular installation requirements. +By default, static files are stored in the local directory `/home/inventree/static`. This directory should be changed by specifying 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. ### Uploaded File Storage -By default, uploaded media files are stored in the local directory `./inventree_media`. This directory should be changed by specifying the `media_root` option in the config file based on the particular installation requirements. +By default, uploaded media files are stored in the local directory `/home/inventree/media`. This directory should be changed by specifying 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. ### Backup Location -The default behaviour of the database backup is to generate backup files for database tables and media files to the user's temporary directory. The target directory can be overridden by setting the `backup_dir` parameter in the config file. +The default behaviour of the database backup is to generate backup files for database tables and media files to `/home/inventree/backup`. The target directory can be overridden by setting the `backup_dir` parameter in the config file. Alternatively this location can be specified with the `INVENTREE_BACKUP_DIR` environment variable. diff --git a/docs/start/docker.md b/docs/start/docker.md new file mode 100644 index 0000000..8904eb9 --- /dev/null +++ b/docs/start/docker.md @@ -0,0 +1,5 @@ +--- +title: Docker Setup +--- + +## Docker Setup \ No newline at end of file diff --git a/docs/start/intro.md b/docs/start/intro.md index cf76da2..9983e5f 100644 --- a/docs/start/intro.md +++ b/docs/start/intro.md @@ -37,7 +37,7 @@ Once a database is setup, you need a way of accessing the data. InvenTree provid ### Background Tasks -A separate application handles management of [background tasks](../tasks), separate to user-facing web requests. +A separate application handles management of [background tasks](../../admin/tasks), separate to user-facing web requests. ## OS Requirements @@ -125,15 +125,29 @@ 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). -## Development Setup +## Installation Guides + +There are multiple ways to get an InvenTree server up and running, of various complexity (and robustness)! + +### Development Server To setup a *simple* development server, refer to the [development instructions](../install). These instructions are useful for those wishing to run a development server. This setup may suffice for a small-scale installation with only a small number of users. -However for a robust server setup which supports high traffic and multiple users, it is highly recommended that the [deployment guide](../deploy) is followed instead. +!!! warning "Not for production" + The development server is not to be used for a production environment. -## Deployment Guide +For a robust server setup which supports high traffic and multiple users, it is highly recommended that the [deployment guide](../deploy) is followed instead. + +### Production Server + +A production server install requires greater consideration. To properly deploy a robust InvenTree server setup, refer to the [deployment instructions](../deploy). +### Docker + +InvenTree can be installed using docker, if that's your thing. + +Refer to the [docker instructions](../docker). diff --git a/docs/start/tasks.md b/docs/start/tasks.md deleted file mode 100644 index 38dfa8f..0000000 --- a/docs/start/tasks.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Background Tasks ---- - -## Background Tasks - diff --git a/docs/start/update.md b/docs/start/update.md index 032f3f6..e0fe291 100644 --- a/docs/start/update.md +++ b/docs/start/update.md @@ -13,6 +13,9 @@ Administrators wishing to update InvenTree to the latest version should follow t 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). diff --git a/mkdocs.yml b/mkdocs.yml index bb61afe..409e135 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,9 +44,10 @@ nav: - Contribute: contribute.md - Getting Started: - Introduction: start/intro.md + - Configuration: start/config.md - Development: start/install.md - - Deploying: start/deploy.md - - Configure: start/config.md + - Production: start/deploy.md + - Docker: start/docker.md - Updating: start/update.md - Migrating: start/migrate.md - Parts: @@ -88,6 +89,7 @@ nav: - Import Data: admin/import.md - Python Shell: admin/shell.md - Error Logs: admin/logs.md + - Background Tasks: admin/tasks.md - Extend: - API: extend/api.md - Python Interface: extend/python.md From 2b3a0c774806febdbd2bed521f9932c9e7335085 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Thu, 8 Apr 2021 21:03:45 +1000 Subject: [PATCH 08/28] Refactor installation instructions (cherry picked from commit 2eb4589b0176b7377135c4539531abde7d0a88b4) --- docs/start/config.md | 30 ---- docs/start/deploy.md | 214 ----------------------------- docs/start/development.md | 58 ++++++++ docs/start/install.md | 279 ++++++++++++++++++++++++++++++++------ docs/start/intro.md | 49 ++++--- docs/start/production.md | 26 ++++ mkdocs.yml | 7 +- 7 files changed, 351 insertions(+), 312 deletions(-) delete mode 100644 docs/start/deploy.md create mode 100644 docs/start/development.md create mode 100644 docs/start/production.md diff --git a/docs/start/config.md b/docs/start/config.md index 7b4d301..d568def 100644 --- a/docs/start/config.md +++ b/docs/start/config.md @@ -81,36 +81,6 @@ The following database options can be configured: | INVENTREE_DB_HOST | database.HOST | Database host address (if required) | | INVENTREE_DB_PORT | database.PORT | Database host port (if required) | -Instructions for particular database backends are provided below: - -#### SQLite -By default, InvenTree uses an sqlite database file : `inventree_db.sqlite3`. This provides a simple, portable database file that is easy to use for debug and testing purposes. - -#### MySQL -MySQL database backend is supported with the native Django implemetation. To run InvenTree with the MySQL backend, a number of extra packages need to be installed: - -* mysql-server - *MySQL backend server* -* libmysqlclient-dev - *Required for connecting to the MySQL database in Python* -* (pip) mysqlclient - *Python package for communication with MySQL database* - -It is then up to the database adminstrator to create a new MySQL database to store inventree data, in addition to a username/password to access the data. - -!!! info "MySQL Collation" - When creating the MySQL database, the adminstrator must ensure that the collation option is set to **utf8_unicode_520_ci** to ensure that InvenTree features function correctly. - -The database options (in the `config.yaml` file) then need to be adjusted to communicate the MySQL backend. Refer to the [Django docs](https://docs.djangoproject.com/en/dev/ref/databases/) for further information. - -#### PostgreSQL -PostgreSQL database backend is supported with the native Django implementation. Note that to use this backend, the following system packages must be installed: - -* postgresql -* postgresql-contrib -* libpq-dev -* (pip3) psycopg2 - -It is then up to the database adminstrator to create a new PostgreSQL database to store inventree data, in addition to a username/password to access the data. - -The database options (in the `config.yaml` file) then need to be adjusted to communicate the PostgreSQL backend. Refer to the [Django docs](https://docs.djangoproject.com/en/dev/ref/databases/) for further information. ### Allowed Hosts / CORS diff --git a/docs/start/deploy.md b/docs/start/deploy.md deleted file mode 100644 index d50fb00..0000000 --- a/docs/start/deploy.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Deploy InvenTree ---- - -## Deploying InvenTree - -The development server provided by the Django ecosystem may be fine for a testing environment or small contained setups. However special consideration must be given when deploying InvenTree in a real-world environment. - -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. - -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. - - -## Install System Packages - -Install required system packages (as superuser). - -First, install required system packages as per the [OS requirements](../intro#os-requirements). - -Next, install the system packages required for your particular database: - -### MySQL - -``` -sudo apt-get install mysql-server libmysqlclient-dev -``` - -### Postgresql - -``` -sudo apt-get install postgresql postgresql-contrib libpq-dev -``` - -### Initial Setup - -### Create InvenTree User - -It is highly recommended that the InvenTree server is not run under root. Create a user account from which we will run the server: - -``` -sudo useradd --create-home 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 -``` - -### Download Source Code - -Download InvenTree source code, into the `./src` directory: - -``` -cd /home/inventree -git clone https://github.com/inventree/inventree src -``` - -### Create Virtual Environment - -Create a python virtual environment for installting required Python packages and binaries: - -``` -python3 -m venv env -source ./env/bin/activate -``` - -The shell prompt should now display the `(env)` prefix. - -### Create Required Directories - -``` -mkdir log static media backup -``` - -This step creates directories required by InvenTree: - -* **log** - Store InvenTree log files -* **static** - Location of static files for the web server -* **media** - Location of uploaded media files -* **backup** - Location of database backup files - -## Install InvenTree Packages - -The Python packages required by the InvenTree server must be installed into the virtual environment. - -Run the `invoke install` command (from within the src directory): - -``` -cd src -invoke install -``` - -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). - -Additionally, this step creates a *SECRET_KEY* file which is used for the django authentication framework. - -!!! warning "Keep it secret, keep it safe" - The SECRET_KEY file should never be shared or made public. - -You will also need to install the python packages required for your particular database backend: - -### MySQL - -``` -pip3 install mysqlclient -``` - -### Postgresql - -``` -pip3 install psycopg2 -``` - -## Configure InvenTree Options - -Once the required software packages are installed, the database and server options must be configured. - -Edit the configuration file at `/home/inventree/src/InvenTree/config.yaml`. - -!!! info "Config Guidelines" - Refer to the [configuration guidelines](../config) for full details. - -!!! warning "Configure Database" - Ensure database settings are correctly configured in `config.yaml` before proceeding to the next step! - -## Create Database - -!!! todo "TODO" - -# Development Server - -The InvenTree development server is useful for testing and configuration - and it may be wholly sufficient for a small-scale installation. - -#### Running on a Local Machine - -To run the development server on a local machine, run the command: - -``` -inv server -a 127.0.0.1:8000 -``` - -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`: - -``` -inv server -a 192.168.120.1:8000 -``` - -!!! warning "Not For Production" - It should be noted that the *development server* provided with django / InvenTree is probably not suitable for your production environment. Instead, use a proper web-server (such as Gunicorn, below). - -## Install Supervisor - -!!! todo "More details here" - -Install the supervisor process manager: - -``` -sudo apt-get install supervisor -``` - -## Gunicorn - -Following is a simple tutorial on serving InvenTree 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. - -### Install Gunicorn - -Gunicorn can be installed using PIP: - -``` -pip3 install gunicorn -``` - -!!! warning "Python Environment" - Ensure that gunicorn is installed within the same python environment context as the InvenTree install - otherwise gunicorn will not be able to import the correct python modules. - -### Configure Static Directories - -Directories for storing *media* files and *static* files should be specified in the ``config.yaml`` configuration file. These directories are the ``MEDIA_ROOT`` and ``STATIC_ROOT`` paths required by the Django app. Ensure that both of these directories are correctly configured for your setup. - -### Collect Static Files - -The required static files must be collected into the specified ``STATIC_ROOT`` directory: - -``` -inv static -``` - -This command collects all of the required static files (including script and css files) into the specified directory ready to be served. - -### Configure Gunicorn - -The Gunicorn server can be configured with a simple configuration file (e.g. python script). An example configuration file is provided in ``InvenTree/gunicorn.conf.py`` - -``` python -{% include 'gunicorn.conf.py' %} -``` - -This file can be used to configure the Gunicorn server to match particular requirements. - -### Run Gunicorn - -``` -cd InvenTree -gunicorn -c gunicorn.conf.py InvenTree.wsgi -``` diff --git a/docs/start/development.md b/docs/start/development.md new file mode 100644 index 0000000..f1eca59 --- /dev/null +++ b/docs/start/development.md @@ -0,0 +1,58 @@ +--- +title: Development Server +--- + +## Development Server + +!!! warning "Installation" + Before continuing, ensure that the [installation steps](../install) have been completed. + +The following installation instructions can be used to launch a simple development server. + +!!! warning "Deployment" + Refer to the [deployment instructions](../deploy) 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) inv 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) inv 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) inv 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. diff --git a/docs/start/install.md b/docs/start/install.md index c12f89a..d086a52 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -1,82 +1,283 @@ --- -title: Installation Instructions +title: Deploy InvenTree --- -## Development Server +## Initial Setup -The following installation instructions can be used to install InvenTree and run a server which provides a simple development environment. +### Install System Packages -!!! warning "Deployment" - Refer to the [deployment instructions](../deploy) to implement a much more robust server setup. +Install required system packages (as superuser). -## Download Code +First, install required system packages as per the [OS requirements](../intro#os-requirements). +Next, install the system packages [required for your particular database](../intro#database-requirements). +### Create InvenTree User -InvenTree setup is performed using the [invoke](https://www.pyinvoke.org/) Python build tool. Various useful scripts are defined in the `tasks.py` file. - -Install invoke as follows: +!!! 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: ``` -pip3 install invoke +sudo useradd --create-home inventree ``` -!!! warning "Invoke Version" - InvenTree requires invoke version 1.4.0 or newer. Some platforms may be shipped with older versions of invoke! +InvenTree source code, log files, etc will be located under the `/home/inventree/` directory. -To display a list of the available configuration scripts, run the following command: +Switch to the `inventree` user so commands are performed in the correct context: ``` -inv --list +sudo su inventree ``` -### Database Configuration - -Once the required packages are installed, the database configuration must be adjusted to suit your particular needs. InvenTree provides a simple default setup which should work *out of the box* for testing and debug purposes. - -As part of the previous *install* step, a configuration file (**config.yaml**) is created. The configuration file provides administrators control over various setup options without digging into the Django *settings.py* script. The default setup uses a local sqlite database with *DEBUG* mode enabled. - -### Initialize Database - -Once install settings are correctly configured (in *config.yaml*) run the initial setup script: +### Create Required Directories ``` -inv migrate +cd /home/inventree +mkdir log static media backup ``` -This performs the initial database migrations, creating the required tables, etc. +This step creates directories required by InvenTree: -The database should now be installed! +* **log** - Store InvenTree log files +* **static** - Location of static files for the web server +* **media** - Location of uploaded media files +* **backup** - Location of database backup files + +### Download Source Code + +Download InvenTree source code, into the `./src` directory: + +``` +cd /home/inventree +git clone https://github.com/inventree/inventree src +``` + +### Create Virtual Environment + +Create a python virtual environment for installing required Python packages and binaries: + +``` +python3 -m venv env +source ./env/bin/activate +``` + +The shell prompt should now display the `(env)` prefix. + +### Install InvenTree Packages + +The Python packages required by the InvenTree server must be installed into the virtual environment. + +Run the `invoke install` command (from within the src directory): + +``` +(env) cd src +(env) invoke install +``` + +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: + +### SQLite + +SQLite uses a simple portable database file which is easy to use for debug and testing purposes. + +Install required packages as follows: + +``` +sudo apt-get install sqlite3 +``` + +A `.sqlite3` database file will be automatically created, at the location specified in the configuration options. No further steps necessary. + +### PostgreSQL + +Install required system packages: + +``` +sudo apt-get install postgresql postgresql-contrib libpq-dev +``` + +The PostgreSQL python binding must also be installed (into your virtual environment): + +``` +(env) pip3 install psycopg2 pgcli +``` + +Assuming the postgresql server is installed and running, switch to the `postgres` user and create a new database: + +``` +sudo su - postgres +``` + +You should now be in a shell session for the `postgres` user. Login to the database server as follows: + +``` +psql +``` + +Create a new database: + +``` +CREATE DATABASE inventree; +``` + +*Note: The name of the database will be required in the configuration section* + +Create a user account associated with the new database. + +``` +CREATE USER inventreeuser WITH PASSWORD "password"; +``` + +*Note: Choose different username and password values, and remember them for the configuration section*. + +Set the following database configuration options: + +``` +ALTER ROLE inventreeuser SET client_encoding TO 'utf8'; +ALTER ROLE inventreeuser SET default_transaction_isolation TO 'read committed'; +ALTER ROLE inventreeuser SET timezone TO 'UTC'; + +GRANT ALL PRIVILEGES ON DATABASE inventree TO inventreeuser; +``` + +Exit the postgresql shell: + +``` +\q +``` + +Exit out of the `postgres` user's shell: + +``` +exit +``` + +### MySQL / MariaDB + +To run InvenTree with the MySQL or MariaDB backends, a number of extra packages need to be installed: + +``` +sudo apt-get install mysql-server libmysqlclient-dev +``` + +Install the python bindings for MySQL: + +``` +(env) pip3 install mysqlclient mariadb +``` + + +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 'inventreeuser'@'%' IDENTIFIED WITH mysql_native_password BY 'inventree'; +mysql> GRANT ALL ON blog_data.* TO 'djangouser'@'%'; +mysql> FLUSH PRIVILEGES; +``` + +Exit the mysql shell: + +``` +mysql> EXIT; +``` + +## Configure InvenTree Options + +Once the required software packages are installed and the database has been created, the InvenTree server options must be configured. + +InvenTree configuration can be performed using environment variables, or the `config.yaml` file (or a combination of both). + +Edit the configuration file at `/home/inventree/src/InvenTree/config.yaml`. + +!!! info "Config Guidelines" + Refer to the [configuration guidelines](../config) for full details. + +!!! warning "Configure Database" + Ensure database settings are correctly configured before proceeding to the next 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. + +``` +(env) invoke update +``` ### Create Admin Account -Create an initial superuser (administrator) account for the InvenTree instance: +Create a superuser (admin) account for the InvenTree installation: ``` -inv superuser +(env) invoke superuser ``` -!!! warning "Solving Cairo Errors" - In the case the above command returns errors with the `Cairo` package, it implies that dependencies for the `weasyprint` package are not installed on the system. To solve them, run through the [weasyprint installation steps](https://weasyprint.readthedocs.io/en/stable/install.html) then re-run `inv install` and `inv superuser`. +!!! success "Ready to Serve" + The InvenTree database is now fully configured, and ready to go. -### Run Development Server +## 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. -To launch the development server, run the following commands: +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) for further information. + +### Production Server + +In a production environment, a more robust server setup is required. + +Refer to the [production server instructions](../production) for further information. + +## Install Gunicorn + +Gunicorn can be installed using PIP: ``` -inv server +pip3 install gunicorn ``` -For more server options, run: +!!! warning "Python Environment" + Ensure that gunicorn is installed within the same python environment context as the InvenTree install - otherwise gunicorn will not be able to import the correct python modules. -``` -inv server -h + +### Configure Gunicorn + +The Gunicorn server can be configured with a simple configuration file (e.g. python script). An example configuration file is provided in ``InvenTree/gunicorn.conf.py`` + +``` python +{% include 'gunicorn.conf.py' %} ``` -This will launch the InvenTree web interface at `http://127.0.0.1:8000`. For other options refer to the [django docs](https://docs.djangoproject.com/en/2.2/ref/django-admin/) +This file can be used to configure the Gunicorn server to match particular requirements. -### Run Production Server +### Run Gunicorn -For a production install, refer to [deployment instructions](../deploy). +``` +cd InvenTree +gunicorn -c gunicorn.conf.py InvenTree.wsgi +``` diff --git a/docs/start/intro.md b/docs/start/intro.md index 9983e5f..cc02582 100644 --- a/docs/start/intro.md +++ b/docs/start/intro.md @@ -12,15 +12,14 @@ The InvenTree server ecosystem consists of the following components: A persistent database is required to store stock information. The database backend must be installed and configured separately to the InvenTree application. -InvenTree can be used by any database backend which is supported by the [Django framework](https://docs.djangoproject.com/en/3.0/ref/databases/): +InvenTree can be used with any of the following database backends: * SQLite * PostgreSQL * MariaDB * MySQL -* Oracle -Database selection should be determined by your particular installation requirements. By default, InvenTree uses SQLite which provides a simple file-based database that allows a quick setup for development and testing. +Database selection should be determined by your particular installation requirements. ### Media Files @@ -34,7 +33,6 @@ The webserver code also provides a first-party API for performing database query 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](../deploy). - ### Background Tasks A separate application handles management of [background tasks](../../admin/tasks), separate to user-facing web requests. @@ -46,7 +44,8 @@ The InvenTree documentation assumes that the operating system is a debian based !!! 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. -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. +!!! 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. The following minimum packages are required to be installed on a system level: @@ -76,7 +75,16 @@ InvenTree runs on [Python](https://python.org). ### Invoke -InvenTree makes use of the [invoke](https://www.pyinvoke.org/) python toolkit for performing various administrative actions +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: + +``` +inv --list +``` ### Virtual Environment @@ -115,6 +123,7 @@ source env/bin/activate This will place the current shell session inside a virtual environment - the terminal should display the ``(env)`` prefix. + ## Downloading 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: @@ -125,29 +134,19 @@ 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). +!!! note "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)! -### Development Server - -To setup a *simple* development server, refer to the [development instructions](../install). - -These instructions are useful for those wishing to run a development server. This setup may suffice for a small-scale installation with only a small number of users. - -!!! warning "Not for production" - The development server is not to be used for a production environment. - -For a robust server setup which supports high traffic and multiple users, it is highly recommended that the [deployment guide](../deploy) is followed instead. - -### Production Server - -A production server install requires greater consideration. - -To properly deploy a robust InvenTree server setup, refer to the [deployment instructions](../deploy). - ### Docker -InvenTree can be installed using docker, if that's your thing. +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 [docker instructions](../docker). +Refer to the [docker setup instructions](../docker) for further information. + +### 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 [InvenTree installation instructions](../install) for more details. diff --git a/docs/start/production.md b/docs/start/production.md new file mode 100644 index 0000000..2c18e54 --- /dev/null +++ b/docs/start/production.md @@ -0,0 +1,26 @@ +--- +title: Production Server +--- + +## Production Server + +!!! warning "Installation" + Before continuing, ensure that the [installation steps](../install) 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. + +## Setup + +## Start Supervisor \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 409e135..14ed132 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,12 +42,11 @@ nav: - What's New: releases/new.md - FAQ: faq.md - Contribute: contribute.md - - Getting Started: + - Installation: - Introduction: start/intro.md + - Docker Installation: start/docker.md + - Manual Installation: start/install.md - Configuration: start/config.md - - Development: start/install.md - - Production: start/deploy.md - - Docker: start/docker.md - Updating: start/update.md - Migrating: start/migrate.md - Parts: From 0276f000f2174b343e2ab03ee8f1311e4c1aff66 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Thu, 8 Apr 2021 21:12:57 +1000 Subject: [PATCH 09/28] Add docs about specifying separate configuration file (cherry picked from commit 93c41351b848850eccadb991f4fee58d3c2e2225) --- docs/start/config.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/start/config.md b/docs/start/config.md index d568def..42d2e73 100644 --- a/docs/start/config.md +++ b/docs/start/config.md @@ -15,10 +15,11 @@ InvenTree system settings can be specified in a configuration file, or via envir 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``. -!!! info "Config file location" - The InvenTree config file is located at `./InvenTree/config.yaml` +The default InvenTree config file is located at `./InvenTree/config.yaml` -The default configuration file launches a *DEBUG* configuration with a simple SQLITE database backend. This default configuration file is shown below: +However, the config file can be placed elsewhere, and specified with the `INVENTREE_CONFIG_FILE` environment variable. + +The default configuration file file is shown below: ``` yaml {% include 'config.yaml' %} @@ -37,7 +38,7 @@ In addition to specifying InvenTree options via the `config.yaml` file, these op !!! warning Available Variables Some configuration options cannot be set via environment variables. Refer to the documentation below. -### Basic Options +## Basic Options The following basic options are available: @@ -46,7 +47,7 @@ The following basic options are available: | INVENTREE_DEBUG | debug | Enable debug mode | | INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | -### Secret Key +## Secret Key InvenTree requires a secret key for providing cryptographic signing - this should be a secret (and unpredictable) value. @@ -64,7 +65,7 @@ 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. -### Database Options +## Database Options InvenTree provides support for multiple database backends - any backend supported natively by Django can be used. @@ -82,7 +83,7 @@ The following database options can be configured: | INVENTREE_DB_PORT | database.PORT | Database host port (if required) | -### Allowed Hosts / CORS +## Allowed Hosts / CORS By default, all hosts are allowed, and CORS requests are enabled from any origin. **This is not secure and should be adjusted for your installation**. These options can be changed in the configuration file. @@ -91,6 +92,8 @@ 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 + ### Static File Storage By default, static files are stored in the local directory `/home/inventree/static`. This directory should be changed by specifying the `static_root` option in the config file based on the particular installation requirements. @@ -109,6 +112,8 @@ The default behaviour of the database backup is to generate backup files for dat Alternatively this location can be specified with the `INVENTREE_BACKUP_DIR` environment variable. +## Other Options + ### Authentication Backends Custom authentication backends can be used by specifying them here From 73bfd2c40f2d9927ec6e4d5c4080cb693a131409 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Thu, 8 Apr 2021 21:16:49 +1000 Subject: [PATCH 10/28] Update example confi gfile (cherry picked from commit a96845ee0289d0f01f1a0c2643a1c3bf8ea36950) --- _includes/config.yaml | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/_includes/config.yaml b/_includes/config.yaml index 18e3197..9e18adb 100644 --- a/_includes/config.yaml +++ b/_includes/config.yaml @@ -7,11 +7,9 @@ # with the prefix INVENTREE_DB_ # e.g INVENTREE_DB_NAME / INVENTREE_DB_USER / INVENTREE_DB_PASSWORD database: - # Default configuration - sqlite filesystem database - ENGINE: sqlite3 - NAME: '../inventree_default_db.sqlite3' - - # For more complex database installations, further parameters are required + # Uncomment (and edit) one of the database configurations below, + # or specify database options using environment variables + # Refer to the django documentation for full list of options # --- Available options: --- @@ -27,14 +25,22 @@ database: # --- Example Configuration - sqlite3 --- # ENGINE: sqlite3 - # NAME: '/path/to/database.sqlite3' + # NAME: '/home/inventree/database.sqlite3' # --- Example Configuration - MySQL --- - #ENGINE: django.db.backends.mysql + #ENGINE: mysql #NAME: inventree - #USER: inventree_username + #USER: inventree #PASSWORD: inventree_password - #HOST: '127.0.0.1' + #HOST: 'localhost' + #PORT: '3306' + + # --- Example Configuration - Postgresql --- + #ENGINE: postgresql + #NAME: inventree + #USER: inventree + #PASSWORD: inventree_password + #HOST: 'localhost' #PORT: '5432' # Select default system language (default is 'en-us') @@ -43,6 +49,7 @@ language: en-us # System time-zone (default is UTC) # Reference: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones # Select an option from the "TZ database name" column +# Use the environment variable INVENTREE_TIMEZONE timezone: UTC # List of currencies supported by default. @@ -57,6 +64,7 @@ currencies: - USD # Set debug to False to run in production mode +# Use the environment variable INVENTREE_DEBUG debug: True # Set debug_toolbar to True to enable a debugging toolbar for InvenTree @@ -65,6 +73,7 @@ debug: True debug_toolbar: False # Configure the system logging level +# Use environment variable INVENTREE_LOG_LEVEL # Options: DEBUG / INFO / WARNING / ERROR / CRITICAL log_level: WARNING @@ -86,13 +95,14 @@ cors: # - https://sub.example.com # MEDIA_ROOT is the local filesystem location for storing uploaded files -# By default, it is stored in a directory named 'inventree_media' local to the InvenTree directory -# This should be changed for a production installation -media_root: '../inventree_media' +# By default, it is stored under /home/inventree +# Use environment variable INVENTREE_MEDIA_ROOT +media_root: '/home/inventree/media' # STATIC_ROOT is the local filesystem location for storing static files -# By default it is stored in a directory named 'inventree_static' local to the InvenTree directory -static_root: '../inventree_static' +# By default, it is stored under /home/inventree +# Use environment variable INVENTREE_STATIC_ROOT +static_root: '/home/inventree/static' # Optional URL schemes to allow in URL fields # By default, only the following schemes are allowed: ['http', 'https', 'ftp', 'ftps'] @@ -105,7 +115,8 @@ static_root: '../inventree_static' # Backup options # Set the backup_dir parameter to store backup files in a specific location # If unspecified, the local user's temp directory will be used -#backup_dir: '/home/inventree/backup/' +# Use environment variable INVENTREE_BACKUP_DIR +backup_dir: '/home/inventree/backup/' # Permit custom authentication backends #authentication_backends: From f1faafe33471aaba43770c46ace8dbd1671e87ed Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Thu, 8 Apr 2021 21:21:30 +1000 Subject: [PATCH 11/28] Fix link --- docs/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index e8c6f9d..afc6999 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -48,4 +48,4 @@ invoke worker !!! info "Supervisor" -A better option is to manage the background worker process using a process manager such as supervisor. Refer to the [deployment guide](../start/deploy). +A better option is to manage the background worker process using a process manager such as supervisor. Refer to the [production server guide](../start/production). From f1b1554623e68f7edf7f6202226ed9b26f769121 Mon Sep 17 00:00:00 2001 From: Oliver Date: Sat, 10 Apr 2021 09:20:19 +1000 Subject: [PATCH 12/28] Update 0.1.8.md --- docs/releases/0.1.8.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/releases/0.1.8.md b/docs/releases/0.1.8.md index add1a44..e96c1e9 100644 --- a/docs/releases/0.1.8.md +++ b/docs/releases/0.1.8.md @@ -38,4 +38,6 @@ title: Release 0.1.8 | [#1407](https://github.com/inventree/InvenTree/pull/1407) | Fixes unncessary column requirement when importing BOM | | [#1430](https://github.com/inventree/InvenTree/pull/1430) | Fixes error thrown when migrating from very old data set | | [#1441](https://github.com/inventree/InvenTree/pull/1441) | Fixes template rendering error if git not available on system path | +| [#1446](https://github.com/inventree/InvenTree/pull/1446) | Fixes bug exporting BOM to YAML format | +| [#1449](https://github.com/inventree/InvenTree/pull/1449) | Fixes bug which prevented transfer of serialized stock items | From ee1ae6dd515d8354c3a202e00fffd0ab743ce9e7 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 11 Apr 2021 13:49:45 +1000 Subject: [PATCH 13/28] Updates --- docs/admin/logs.md | 4 +- docs/companies/manufacturer.md | 2 +- docs/companies/supplier.md | 2 +- docs/part/parameter.md | 2 +- docs/start/development.md | 4 +- docs/start/install.md | 178 ++++++++++++++------------------- docs/start/intro.md | 28 +----- docs/start/production.md | 72 ++++++++++++- docs/stock/owner.md | 2 +- mkdocs.yml | 4 +- 10 files changed, 160 insertions(+), 138 deletions(-) diff --git a/docs/admin/logs.md b/docs/admin/logs.md index 7e85668..95564cd 100644 --- a/docs/admin/logs.md +++ b/docs/admin/logs.md @@ -12,7 +12,7 @@ In the admin interface, select the "Errors" view: {% include 'img.html' %} {% endwith %} -!!! note "URL" +!!! info "URL" Alternatively, navigate to the error list view at /admin/error_report/error/ A list of error logs is presented. @@ -21,7 +21,7 @@ A list of error logs is presented. {% include 'img.html' %} {% endwith %} -!!! note "Deleting Logs" +!!! info "Deleting Logs" Error logs should be deleted periodically ## Reporting Errors diff --git a/docs/companies/manufacturer.md b/docs/companies/manufacturer.md index 86008b2..5dd4b75 100644 --- a/docs/companies/manufacturer.md +++ b/docs/companies/manufacturer.md @@ -15,7 +15,7 @@ To access the manufacturer page, click on the "Buy" navigation tab and click on Once the manufacturer page is loaded, click on the " New Manufacturer" button: the "Create new Manufacturer" form opens. Fill-in the manufacturer informations (`Company name` and `Company description` are required) then click on the "Submit" button. -!!! note "Manufacturer vs Supplier" +!!! info "Manufacturer vs Supplier" In the case the manufacturer sells directly to customers, you may want to enable the checkbox `is supplier` before submitting the form (you can also enable it later on). Purchase orders rely exclusively on [supplier parts](../supplier#supplier-parts), therefore the manufacturer will need to be set as a supplier too. ### Edit Manufacturer diff --git a/docs/companies/supplier.md b/docs/companies/supplier.md index b5d1565..f5208d1 100644 --- a/docs/companies/supplier.md +++ b/docs/companies/supplier.md @@ -15,7 +15,7 @@ To access the supplier page, click on the "Buy" navigation tab and click on "Sup Once the supplier page is loaded, click on the " New Supplier" button: the "Create new Supplier" form opens. Fill-in the supplier informations (`Company name` and `Company description` are required) then click on the "Submit" button. -!!! note "Supplier vs Manufacturer" +!!! info "Supplier vs Manufacturer" In the case the supplier is a manufacturer who sells directly to customers, you may want to enable the checkbox `is manufacturer` before submitting the form (you can also enable it later on). ### Edit Supplier diff --git a/docs/part/parameter.md b/docs/part/parameter.md index d8d1d2c..1af842b 100644 --- a/docs/part/parameter.md +++ b/docs/part/parameter.md @@ -42,5 +42,5 @@ Select the parameter `Template` you would like to use for this parameter, fill-o ### Parametric Tables -!!! note "Future Feature Proposal" +!!! info "Future Feature Proposal" Allow parts to be filtered using parameters. Narrow down the list of parameters to the parts found in each category. diff --git a/docs/start/development.md b/docs/start/development.md index f1eca59..2cf611e 100644 --- a/docs/start/development.md +++ b/docs/start/development.md @@ -7,10 +7,10 @@ title: Development Server !!! warning "Installation" Before continuing, ensure that the [installation steps](../install) have been completed. -The following installation instructions can be used to launch a simple development server. +InvenTree includes a simple server application, suitable for use in a development environment. !!! warning "Deployment" - Refer to the [deployment instructions](../deploy) to implement a much more robust server setup. + Refer to the [production server instructions](../production) to implement a much more robust server setup. ### Running on a Local Machine diff --git a/docs/start/install.md b/docs/start/install.md index d086a52..349b51a 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -4,13 +4,24 @@ title: Deploy InvenTree ## Initial Setup +Follow the instructions below to install the requried system packages, python modules, and InvenTree source code. + ### Install System Packages -Install required system packages (as superuser). +Install required system packages (as superuser): -First, install required system packages as per the [OS requirements](../intro#os-requirements). +!!! warning "OS Specific Requirements" + The following packages are required on a debian system. A different distribution may require a slightly different set of packages + +``` +sudo apt-get update +sudo apt-get install python3 python3-dev +sudo apt-get install python3-pip python3-invoke python3-venv +``` + +!!! 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. -Next, install the system packages [required for your particular database](../intro#database-requirements). ### Create InvenTree User @@ -20,7 +31,7 @@ Next, install the system packages [required for your particular database](../int Create a user account from which we will run the server: ``` -sudo useradd --create-home inventree +sudo useradd -m -d /home/inventree -s /bin/bash inventree ``` InvenTree source code, log files, etc will be located under the `/home/inventree/` directory. @@ -35,22 +46,20 @@ sudo su inventree ``` cd /home/inventree -mkdir log static media backup +mkdir log static data ``` This step creates directories required by InvenTree: -* **log** - Store InvenTree log files -* **static** - Location of static files for the web server -* **media** - Location of uploaded media files -* **backup** - Location of database backup files +* `/home/inventree/log` - Store InvenTree log files +* `/home/inventree/static` - Location of static files for the web server +* `/home/inventre/data` - Location of stored media and backup files ### Download Source Code Download InvenTree source code, into the `./src` directory: ``` -cd /home/inventree git clone https://github.com/inventree/inventree src ``` @@ -63,22 +72,19 @@ python3 -m venv env source ./env/bin/activate ``` -The shell prompt should now display the `(env)` prefix. +!!! 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. -Run the `invoke install` command (from within the src directory): - ``` -(env) cd src -(env) invoke install +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: @@ -89,6 +95,9 @@ SQLite uses a simple portable database file which is easy to use for debug and t Install required packages as follows: +!!! info "Sudo Actions" + Perform sudo actions from a separate shell, as 'inventree' user does not have sudo access + ``` sudo apt-get install sqlite3 ``` @@ -97,82 +106,72 @@ A `.sqlite3` database file will be automatically created, at the location specif ### 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): ``` -(env) pip3 install psycopg2 pgcli -``` - -Assuming the postgresql server is installed and running, switch to the `postgres` user and create a new database: - -``` -sudo su - postgres -``` - -You should now be in a shell session for the `postgres` user. Login to the database server as follows: - -``` -psql -``` - -Create a new database: - -``` -CREATE DATABASE inventree; -``` - -*Note: The name of the database will be required in the configuration section* - -Create a user account associated with the new database. - -``` -CREATE USER inventreeuser WITH PASSWORD "password"; -``` - -*Note: Choose different username and password values, and remember them for the configuration section*. - -Set the following database configuration options: - -``` -ALTER ROLE inventreeuser SET client_encoding TO 'utf8'; -ALTER ROLE inventreeuser SET default_transaction_isolation TO 'read committed'; -ALTER ROLE inventreeuser SET timezone TO 'UTC'; - -GRANT ALL PRIVILEGES ON DATABASE inventree TO inventreeuser; -``` - -Exit the postgresql shell: - -``` -\q -``` - -Exit out of the `postgres` user's shell: - -``` -exit +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 the python bindings for MySQL: +#### Install Python Bindings + +Install the python bindings for MySQL (into the python virtual environment). ``` -(env) pip3 install mysqlclient mariadb +pip3 install mysqlclient mariadb ``` +#### Create Database Assuming the MySQL server is installed and running, login to the MySQL server as follows: @@ -189,7 +188,7 @@ mysql> CREATE DATABASE inventree; Create a new user with complete access to the database: ``` -mysql> CREATE USER 'inventreeuser'@'%' IDENTIFIED WITH mysql_native_password BY 'inventree'; +mysql> CREATE USER 'myuser'@'%' IDENTIFIED WITH mysql_native_password BY 'mypass'; mysql> GRANT ALL ON blog_data.* TO 'djangouser'@'%'; mysql> FLUSH PRIVILEGES; ``` @@ -200,6 +199,9 @@ 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. @@ -212,7 +214,7 @@ Edit the configuration file at `/home/inventree/src/InvenTree/config.yaml`. Refer to the [configuration guidelines](../config) for full details. !!! warning "Configure Database" - Ensure database settings are correctly configured before proceeding to the next step! + 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 @@ -223,7 +225,8 @@ The database has been configured above, but is currently empty. Run the following command to initialize the database with the required tables. ``` -(env) invoke update +cd /home/inventree/src +invoke update ``` ### Create Admin Account @@ -231,7 +234,7 @@ Run the following command to initialize the database with the required tables. Create a superuser (admin) account for the InvenTree installation: ``` -(env) invoke superuser +invoke superuser ``` !!! success "Ready to Serve" @@ -252,32 +255,3 @@ Refer to the [development server instructions](../development) for further infor In a production environment, a more robust server setup is required. Refer to the [production server instructions](../production) for further information. - -## Install Gunicorn - -Gunicorn can be installed using PIP: - -``` -pip3 install gunicorn -``` - -!!! warning "Python Environment" - Ensure that gunicorn is installed within the same python environment context as the InvenTree install - otherwise gunicorn will not be able to import the correct python modules. - - -### Configure Gunicorn - -The Gunicorn server can be configured with a simple configuration file (e.g. python script). An example configuration file is provided in ``InvenTree/gunicorn.conf.py`` - -``` python -{% include 'gunicorn.conf.py' %} -``` - -This file can be used to configure the Gunicorn server to match particular requirements. - -### Run Gunicorn - -``` -cd InvenTree -gunicorn -c gunicorn.conf.py InvenTree.wsgi -``` diff --git a/docs/start/intro.md b/docs/start/intro.md index cc02582..6ec6603 100644 --- a/docs/start/intro.md +++ b/docs/start/intro.md @@ -44,28 +44,6 @@ The InvenTree documentation assumes that the operating system is a debian based !!! 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. -!!! 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. - -The following minimum packages are required to be installed on a system level: - -### Debian - -``` -sudo apt-get update -sudo apt-get install python3 python3-dev -sudo apt-get install python3-pip python3-invoke python3-venv -``` - -### FreeBSD - -``` -pkg install python -pkg install py37-pip -pkg install py37-wheel -pkg install py37-invoke -``` - ## Python Requirements InvenTree runs on [Python](https://python.org). @@ -92,7 +70,7 @@ Installing the required Python packages inside a virtual environment allows a lo You can read more about Python virtual environments [here](https://docs.python.org/3/tutorial/venv.html). -!!! note "Virtual Environment" +!!! 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: @@ -111,7 +89,7 @@ To configure Inventree inside a virtual environment, ``cd`` into the inventree b source env/bin/activate ``` -!!! note "Activate Virtual Environment" +!!! info "Activate Virtual Environment" if ``` source env/bin/activate @@ -134,7 +112,7 @@ 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). -!!! note "Updating via Git" +!!! 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 diff --git a/docs/start/production.md b/docs/start/production.md index 2c18e54..b3c4d20 100644 --- a/docs/start/production.md +++ b/docs/start/production.md @@ -21,6 +21,74 @@ The InvenTree web server is hosted using [Gunicorn](https://gunicorn.org/). Guni [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. -## Setup +## Gunicorn -## Start Supervisor \ No newline at end of file +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 Ctrl+c + +## 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! diff --git a/docs/stock/owner.md b/docs/stock/owner.md index ded2fc6..b37f68b 100644 --- a/docs/stock/owner.md +++ b/docs/stock/owner.md @@ -46,7 +46,7 @@ Setting the owner of stock location will automatically: * Set the owner of all children locations to the same owner. * Set the owner of all stock items at this location to the same owner. -!!! note +!!! info If the owner of a children location or a stock item is a subset of the specified owner (eg. a user linked to the specified group), the owner won't be updated. ### Set Stock Item Owner diff --git a/mkdocs.yml b/mkdocs.yml index 14ed132..27a368a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,9 +44,11 @@ nav: - Contribute: contribute.md - Installation: - Introduction: start/intro.md + - Configuration: start/config.md - Docker Installation: start/docker.md - Manual Installation: start/install.md - - Configuration: start/config.md + - Development Server: start/development.md + - Production Server: start/production.md - Updating: start/update.md - Migrating: start/migrate.md - Parts: From 3f2aa5ce84fa48d5cd0fd4ca4f80376596e7e796 Mon Sep 17 00:00:00 2001 From: Oliver Date: Sun, 11 Apr 2021 14:47:27 +1000 Subject: [PATCH 14/28] Update 0.1.8.md --- docs/releases/0.1.8.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/releases/0.1.8.md b/docs/releases/0.1.8.md index e96c1e9..688354c 100644 --- a/docs/releases/0.1.8.md +++ b/docs/releases/0.1.8.md @@ -4,7 +4,7 @@ title: Release 0.1.8 ## Release 0.1.8 -[Release 0.1.8](https://github.com/inventree/InvenTree/releases/tag/0.1.8) (WIP) provides a number of major new features and improvements, as well as some crucial bug fixes: +[Release 0.1.8](https://github.com/inventree/InvenTree/releases/tag/0.1.8) provides a number of major new features and improvements, as well as some crucial bug fixes: ## New Features From f19d3d722699727b361baa5088166a28bef8653f Mon Sep 17 00:00:00 2001 From: Oliver Date: Sun, 11 Apr 2021 14:47:43 +1000 Subject: [PATCH 15/28] Update new.md --- docs/releases/new.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/releases/new.md b/docs/releases/new.md index ed94512..9eeeba7 100644 --- a/docs/releases/new.md +++ b/docs/releases/new.md @@ -8,7 +8,7 @@ For information on the latest and greatest InvenTree features, refer to the rele | Release | Date | | ------- | ---- | -| [0.1.8](../0.1.8) | *In Development* | +| [0.1.8](../0.1.8) | April 2021 | | [0.1.7](../0.1.7) | March 2021 | | [0.1.6](../0.1.6) | February 2021 | | [0.1.5](../0.1.5) | January 2021 | From 726ca9cde20cf274a6cfad5898ba40fa1a0f1c2e Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 11 Apr 2021 14:50:23 +1000 Subject: [PATCH 16/28] Added docker install instructions --- _includes/docker-compose.yml | 100 +++++++++++++++++++++ docs/admin/tasks.md | 8 +- docs/start/docker.md | 166 ++++++++++++++++++++++++++++++++++- 3 files changed, 272 insertions(+), 2 deletions(-) create mode 100644 _includes/docker-compose.yml diff --git a/_includes/docker-compose.yml b/_includes/docker-compose.yml new file mode 100644 index 0000000..c0ad82a --- /dev/null +++ b/_includes/docker-compose.yml @@ -0,0 +1,100 @@ +version: "3.8" + +# Docker compose recipe for InvenTree +# - Runs PostgreSQL as the database backend +# - Runs Gunicorn as the web server +# - Runs nginx as a reverse proxy +# - Runs the background worker process + +# --------------------------------- +# IMPORTANT - READ BEFORE STARTING! +# --------------------------------- +# Before running, ensure that you change the "/path/to/data" directory, +# specified in the "volumes" section at the end of this file. +# This path determines where the InvenTree data will be stored! + +services: + # Database service + # Use PostgreSQL as the database backend + # Note: this can be changed to a different backend, + # just make sure that you change the INVENTREE_DB_xxx vars below + db: + image: postgres + container_name: inventree_db + ports: + - 5432/tcp + environment: + - PGDATA=/var/lib/postgresql/data/pgdb + - POSTGRES_USER=pguser + - POSTGRES_PASSWORD=pgpassword + volumes: + - data:/var/lib/postgresql/data/ + restart: unless-stopped + + # InvenTree web server services + # Uses gunicorn as the web server + inventree: + image: inventree/inventree:latest + container_name: inventree_server + expose: + - 8080 + depends_on: + - db + volumes: + - data:/home/inventree/data + - static:/home/inventree/static + environment: + - INVENTREE_DB_ENGINE=postgresql + - INVENTREE_DB_NAME=inventree + - INVENTREE_DB_USER=pguser + - INVENTREE_DB_PASSWORD=pgpassword + - INVENTREE_DB_PORT=5432 + - INVENTREE_DB_HOST=db + restart: unless-stopped + + # nginx acts as a reverse proxy + # static files are served by nginx + # web requests are redirected to gunicorn + nginx: + image: inventree/nginx:latest + container_name: inventree_proxy + depends_on: + - inventree + ports: + # Change "1337" to the port where you want InvenTree web server to be available + - 1337:80 + volumes: + - static:/home/inventree/static + + # background worker process handles long-running or periodic tasks + worker: + entrypoint: ./start_worker.sh + image: inventree/inventree:latest + container_name: inventree_worker + depends_on: + - db + - inventree + volumes: + - data:/home/inventree/data + - static:/home/inventree/static + environment: + - INVENTREE_DB_ENGINE=postgresql + - INVENTREE_DB_NAME=inventree + - INVENTREE_DB_USER=pguser + - INVENTREE_DB_PASSWORD=pgpassword + - INVENTREE_DB_PORT=5432 + - INVENTREE_DB_HOST=db + restart: unless-stopped + +volumes: + # Static files, shared between containers + static: + # Persistent data, stored externally + data: + driver: local + driver_opts: + type: none + o: bind + # This directory specified where InvenTree data are stored "outside" the docker containers + # Change this path to a local system path where you want InvenTree data stored + device: /path/to/data diff --git a/docs/admin/tasks.md b/docs/admin/tasks.md index 369f8f3..1881cbb 100644 --- a/docs/admin/tasks.md +++ b/docs/admin/tasks.md @@ -12,12 +12,18 @@ Some tasks (such as sending emails or performing bulk database actions) may take ### Periodic Tasks -Some tasks must be performed on a periodic basis. +Some tasks must be performed on a regular, periodic basis. ## Django Q InvenTree uses the [django-q](https://django-q.readthedocs.io/en/latest/) background task manager. +### Running Worker + +The Django Q work must run separately to the web server. This is started as a separate process, as part of the InvenTree installation instructions. + +If the worker is not running, a warning indicator is displayed in the InvenTree menu bar. + ## Admin Interface Scheduled tasks can be viewed in the InvenTree admin interface. diff --git a/docs/start/docker.md b/docs/start/docker.md index 8904eb9..b372c54 100644 --- a/docs/start/docker.md +++ b/docs/start/docker.md @@ -2,4 +2,168 @@ title: Docker Setup --- -## Docker Setup \ No newline at end of file +## Docker Image + +The most convenient method of installing and running InvenTree is to use the official [docker image](https://hub.docker.com/inventree/inventree). + +The InvenTree docker image contains all the required system packages, python modules, and configuration files for running InvenTree. + +## Docker Compose + +An example docker compose script is provided below, which provides a robust "out of the box" setup for running InvenTree. + +### Containers + +The following containers are created: + +#### PostgreSQL Database + +A postgresql database container which creates a postgres user:password combination (which can be changed) + +#### Web Server + +InvenTree web server running on a Gunicorn backend + +#### Background Worker + +InvenTree background worker process manager + +#### Nginx + +Nginx working as a reverse proxy, separating requests for static files and directing everything else to Gunicorn + +### Volumes + +There are two container volumes created: + +#### Data + +InvenTree stores data which is meant to be persistent (e.g. uploaded media files, database data, etc) in a volume which is mapped to a local system directory. + +!!! info "Data Directory" + Make sure you change the path to the local directory where you want persistent data to be stored. + +#### Static + +Static files are shared between multiple containers (but not exposed to the local file system). + +### Docker Compose File + +Use the following docker-compose file as a starting point: + +``` yaml +{% include 'docker-compose.yml' %} +``` + +## Initial Setup Process + +Follow the instructions below to initialize a complete docker deployment for InvenTree. + +!!! info "Directory" + It is assumed that all commands will be run from the directory where `docker-compose.yml` is located. + +### Configure Compose File + +Save and edit the `docker-compose.yml` file as required. + +The only **required** change is to ensure that the `/path/to/data` entry (at the end of the file) points to the correct directory on your local file system, where you want InvenTree data to be stored. + +### Build + +Build the docker containers: + +``` +docker-compose build +``` + +### Launch Database Server + +Before we can create the database, we need to launch the database server container: + +``` +docker-compose up -d db +``` + +This starts the database container. + +### Create Database + +Run the following command to open a shell session for the database: + +``` +docker-compose run inventree pgcli -h db -p 5432 -u pguser +``` + +!!! info "User" + If you have changed the `POSTGRES_USER` variable in the compose file, replace `pguser` with the different user. + +You will be prompted to enter the database user password (default="pgpassword", unless altered in the compose file). + +Next, run the following command in the database shell: + +``` +create database inventree; +``` + +Then exit the shell with Ctrl+d + +### Perform Database Migrations + +The database has been created, but it is empty! We need to perform the initial database migrations. + +``` +docker-compose run inventree invoke migrate +``` + +This will perform the required schema updates to create the required database tables. + +### Collect Static Files + +On first run, the required static files must be collected into the `static` volume: + +``` +docker-compose run inventree invoke static +``` + +### Create Admin Account + +You need to create an admin (superuser) account for the database. Run the command below, and follow the prompts: + +``` +docker-compose run inventree invoke superuser +``` + +### Configure InvenTree Options + +By default, all required InvenTree settings are specified in the docker compose file, with the `INVENTREE_DB_` prefix. + +You are free to skip this step, if these InvenTree settings meet your requirements. + +If you wish to tweak the InvenTree configuration options, you can either: + +#### Environment Variables + +Alter (or add) environment variables into the docker-compose `environment` section + +#### Configuration File + +A configuration file `config.yaml` has been created in the data volume (at the location specified on your local disk). + +Edit this file (as per the [configuration guidelines](../config)). + +### Run Web Server + +Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the web server: + +``` +docker-compose up -d +``` + +This command launches the remaining container processes: + +- `inventree` - InvenTree web server +- `worker` - Background worker +- `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) From a8b23c85713767749f9bc8c9682029cfc52aa1a3 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 11 Apr 2021 15:00:35 +1000 Subject: [PATCH 17/28] v0.2.0 release information --- docs/releases/0.2.0.md | 34 ++++++++++++++++++++++++++++++++++ docs/releases/new.md | 1 + docs/start/docker.md | 8 -------- docs/start/install.md | 2 +- 4 files changed, 36 insertions(+), 9 deletions(-) create mode 100644 docs/releases/0.2.0.md diff --git a/docs/releases/0.2.0.md b/docs/releases/0.2.0.md new file mode 100644 index 0000000..123f347 --- /dev/null +++ b/docs/releases/0.2.0.md @@ -0,0 +1,34 @@ +--- +title: Release 0.2.0 +--- + +## Release 0.2.0 + +[Release 0.2.0](https://github.com/inventree/InvenTree/releases/tag/0.2.0) introduces some major new features! + +## Background Worker + +This release adds a "background worker" - a separately managed process which allows long-running or asynchronous tasks to be handled separately to web server requests. + +This feature is critical for the InvenTree development path, allowing (in future releases) for complex tasks to be handled, such as email support, automatic report generation, and integration with third party services. + +For more information on the background worker, refer to the [background tasks documentation](../../admin/tasks). + +!!! info "Installation" + Instructions for managing the background worker process are included in the [installation guide](../../start/install). + +!!! warning "Upgrading" + If you are upgrading your InvenTree installation from an older version, you will need to ensure that you are also now running the background worker process! + +## Docker + +The other major feature that `0.2.0` introduces is an officical docker installation guide. + +The addition of the *Background Worker* process significantly increases the complexity of an InvenTree installation. Further, a robust *production grade* server requires a lot of work. + +To simplify this, an official InvenTree docker image is available on [DockerHub](https://hub.docker.com/inventree/inventree). + +!!! success "Docker Is the Way" + Docker is now the recommended way to install InvenTree + +Refer to the [docker setup guide](../../start/docker) for further information! diff --git a/docs/releases/new.md b/docs/releases/new.md index 9eeeba7..4c62088 100644 --- a/docs/releases/new.md +++ b/docs/releases/new.md @@ -8,6 +8,7 @@ For information on the latest and greatest InvenTree features, refer to the rele | Release | Date | | ------- | ---- | +| [0.2.0](../0.2.0) | April 2021 | | [0.1.8](../0.1.8) | April 2021 | | [0.1.7](../0.1.7) | March 2021 | | [0.1.6](../0.1.6) | February 2021 | diff --git a/docs/start/docker.md b/docs/start/docker.md index b372c54..7520594 100644 --- a/docs/start/docker.md +++ b/docs/start/docker.md @@ -68,14 +68,6 @@ Save and edit the `docker-compose.yml` file as required. The only **required** change is to ensure that the `/path/to/data` entry (at the end of the file) points to the correct directory on your local file system, where you want InvenTree data to be stored. -### Build - -Build the docker containers: - -``` -docker-compose build -``` - ### Launch Database Server Before we can create the database, we need to launch the database server container: diff --git a/docs/start/install.md b/docs/start/install.md index 349b51a..03044ec 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -1,5 +1,5 @@ --- -title: Deploy InvenTree +title: Install InvenTree --- ## Initial Setup From e75c8914d72c25463cc16f9c551bc9479eb9085b Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 11 Apr 2021 15:16:37 +1000 Subject: [PATCH 18/28] Add some badges to the index page --- docs/index.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/index.md b/docs/index.md index 7fcd762..bfb44bc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,10 @@ title: InvenTree ## InvenTree - Intuitive Inventory Management +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Docker Pulls](https://img.shields.io/docker/pulls/inventree/inventree)](https://hub.docker.com/inventree/inventree) +[![Coverage Status](https://coveralls.io/repos/github/inventree/InvenTree/badge.svg)](https://coveralls.io/github/inventree/InvenTree) + InvenTree is an open-source inventory management system which provides intuitive parts management and stock control. InvenTree is designed to be lightweight and easy to use for SME or hobbyist applications, where many existing stock management solutions are bloated and cumbersome to use. However, powerful business logic works in the background to ensure that stock tracking history is maintained, and users have ready access to stock level information. From 82750ab5af3930df5de8bb47ea2aa3dc0646cde0 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 11 Apr 2021 15:20:28 +1000 Subject: [PATCH 19/28] Updated bages --- docs/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index bfb44bc..4c8afe6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,8 +5,9 @@ title: InvenTree ## InvenTree - Intuitive Inventory Management [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![GitHub Repo stars](https://img.shields.io/github/stars/inventree/inventree?label=View%20On%20GitHub&style=social)](https://github.com/inventree/inventree) [![Docker Pulls](https://img.shields.io/docker/pulls/inventree/inventree)](https://hub.docker.com/inventree/inventree) -[![Coverage Status](https://coveralls.io/repos/github/inventree/InvenTree/badge.svg)](https://coveralls.io/github/inventree/InvenTree) + InvenTree is an open-source inventory management system which provides intuitive parts management and stock control. From 1f5479adc6cd58488051e5ca7295636e8c40e0d3 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 11 Apr 2021 16:57:05 +1000 Subject: [PATCH 20/28] Remove reference to third-party docker --- docs/extend/integrate.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/extend/integrate.md b/docs/extend/integrate.md index 7d5c771..eb6812b 100644 --- a/docs/extend/integrate.md +++ b/docs/extend/integrate.md @@ -13,7 +13,3 @@ A list of known third-party InvenTree extensions is provided below. If you have ### PK2InvenTree [PK2InvenTree](https://github.com/rgilham/PK2InvenTree) is an open-source tool for migrating an existing [PartKeepr](https://github.com/partkeepr/PartKeepr) database to InvenTree. - -### inventree-docker - -[inventree-docker](https://github.com/Zeigren/inventree-docker) provides Docker support for InvenTree \ No newline at end of file From 1e2f386dc5b90856d064fde31cb887aa0ecd99d5 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 11 Apr 2021 16:59:46 +1000 Subject: [PATCH 21/28] Fix docker hub link --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 4c8afe6..9b30739 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,7 @@ title: InvenTree [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![GitHub Repo stars](https://img.shields.io/github/stars/inventree/inventree?label=View%20On%20GitHub&style=social)](https://github.com/inventree/inventree) -[![Docker Pulls](https://img.shields.io/docker/pulls/inventree/inventree)](https://hub.docker.com/inventree/inventree) +[![Docker Pulls](https://img.shields.io/docker/pulls/inventree/inventree)](https://hub.docker.com/r/inventree/inventree) InvenTree is an open-source inventory management system which provides intuitive parts management and stock control. From d8a3e8a3419c7b3417c74ca1fe8e5f34b2511109 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 11 Apr 2021 17:02:15 +1000 Subject: [PATCH 22/28] Fix heading --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 9b30739..9bed41c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,7 @@ title: InvenTree --- -## InvenTree - Intuitive Inventory Management +## Intuitive Inventory Management [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![GitHub Repo stars](https://img.shields.io/github/stars/inventree/inventree?label=View%20On%20GitHub&style=social)](https://github.com/inventree/inventree) From aeaa37a96878400951c70a75008f81ad9ba72a0a Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 11 Apr 2021 17:11:30 +1000 Subject: [PATCH 23/28] Fix links --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 9bed41c..3b0db6b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,7 +25,7 @@ Refer to the [features](./features) page for a rundown on the features that Inve ## Getting Started -Refer to the [installation guide](./start/install) for instructions on installing InvenTree. The server where InvenTree is to be installed will need to meet some basic package requirements, and a certain level of system administration understanding is assumed. +Refer to the [installation guide](./start/intro) for instructions on installing InvenTree. The server where InvenTree is to be installed will need to meet some basic package requirements, and a certain level of system administration understanding is assumed. ## Get the App From 2c0ed9e1263de817f23dd9b990a65c67a4b9fe43 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 11 Apr 2021 19:37:40 +1000 Subject: [PATCH 24/28] Docs for v0.2.1 --- docs/releases/0.2.1.md | 15 +++++++++++++++ docs/releases/new.md | 1 + 2 files changed, 16 insertions(+) create mode 100644 docs/releases/0.2.1.md diff --git a/docs/releases/0.2.1.md b/docs/releases/0.2.1.md new file mode 100644 index 0000000..879123e --- /dev/null +++ b/docs/releases/0.2.1.md @@ -0,0 +1,15 @@ +--- +title: Release 0.2.1 +--- + +## Release 0.2.1 + +[Release 0.2.1](https://github.com/inventree/InvenTree/releases/tag/0.2.1) provides a number of major new features and improvements, as well as some crucial bug fixes: + +## New Features + +## Major Bug Fixes + +| PR | Description | +| --- | --- | +| [#1453](https://github.com/inventree/InvenTree/pull/1453) | Adds *detail* API endpoint for the `PartParameter` model, which was previously missing. | diff --git a/docs/releases/new.md b/docs/releases/new.md index 4c62088..cfec771 100644 --- a/docs/releases/new.md +++ b/docs/releases/new.md @@ -8,6 +8,7 @@ For information on the latest and greatest InvenTree features, refer to the rele | Release | Date | | ------- | ---- | +| [0.2.1](../0.2.1) | *In Development* | | [0.2.0](../0.2.0) | April 2021 | | [0.1.8](../0.1.8) | April 2021 | | [0.1.7](../0.1.7) | March 2021 | From 113d0b941442bdaf1c17fca0a6253520aadf3fda Mon Sep 17 00:00:00 2001 From: Oliver Date: Tue, 13 Apr 2021 08:50:04 +1000 Subject: [PATCH 25/28] Update 0.2.0.md --- docs/releases/0.2.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/releases/0.2.0.md b/docs/releases/0.2.0.md index 123f347..b8e9d27 100644 --- a/docs/releases/0.2.0.md +++ b/docs/releases/0.2.0.md @@ -26,7 +26,7 @@ The other major feature that `0.2.0` introduces is an officical docker installat The addition of the *Background Worker* process significantly increases the complexity of an InvenTree installation. Further, a robust *production grade* server requires a lot of work. -To simplify this, an official InvenTree docker image is available on [DockerHub](https://hub.docker.com/inventree/inventree). +To simplify this, an official InvenTree docker image is available on [DockerHub](https://hub.docker.com/r/inventree/inventree). !!! success "Docker Is the Way" Docker is now the recommended way to install InvenTree From d72ea19b77ca1c512408d8a5b61c0fac6dd3b2e3 Mon Sep 17 00:00:00 2001 From: Oliver Date: Tue, 13 Apr 2021 15:45:58 +1000 Subject: [PATCH 26/28] Update intro.md --- docs/start/intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/start/intro.md b/docs/start/intro.md index 6ec6603..f258744 100644 --- a/docs/start/intro.md +++ b/docs/start/intro.md @@ -49,7 +49,7 @@ The InvenTree documentation assumes that the operating system is a debian based InvenTree runs on [Python](https://python.org). !!! warning "Python Version" - InvenTree requrires Python 3.6 (or newer). If your system has an older version of Python installed, you will need to follow the update instructions for your OS. + InvenTree requrires Python 3.7 (or newer). If your system has an older version of Python installed, you will need to follow the update instructions for your OS. ### Invoke From c6f662ce69e48ec4299ce5e18b66e7a034310ac6 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Tue, 13 Apr 2021 20:16:59 +1000 Subject: [PATCH 27/28] Update email docs --- _includes/config.yaml | 12 +++++++----- docs/admin/email.md | 13 +++++++++++++ docs/start/config.md | 39 +++++++++++++++++++++++++++------------ mkdocs.yml | 1 + 4 files changed, 48 insertions(+), 17 deletions(-) create mode 100644 docs/admin/email.md diff --git a/_includes/config.yaml b/_includes/config.yaml index fe93c09..e9f32f3 100644 --- a/_includes/config.yaml +++ b/_includes/config.yaml @@ -74,15 +74,17 @@ currencies: # tls: Enable TLS support # ssl: Enable SSL support -# Alternatively, these options can all be set using environment variables +# Alternatively, these options can all be set using environment variables, +# with the INVENTREE_EMAIL_ prefix: +# e.g. INVENTREE_EMAIL_HOST / INVENTREE_EMAIL_PORT / INVENTREE_EMAIL_USERNAME # Refer to the InvenTree documentation for more information email: + # backend: 'django.core.mail.backends.smtp.EmailBackend' host: '' port: 25 username: '' password: '' - prefix: '[InvenTree] ' tls: False ssl: False @@ -118,9 +120,9 @@ cors: # - https://sub.example.com # MEDIA_ROOT is the local filesystem location for storing uploaded files -# By default, it is stored under /home/inventree +# By default, it is stored under /home/inventree/data/media # Use environment variable INVENTREE_MEDIA_ROOT -media_root: '/home/inventree/media' +media_root: '/home/inventree/data/media' # STATIC_ROOT is the local filesystem location for storing static files # By default, it is stored under /home/inventree @@ -139,7 +141,7 @@ static_root: '/home/inventree/static' # Set the backup_dir parameter to store backup files in a specific location # If unspecified, the local user's temp directory will be used # Use environment variable INVENTREE_BACKUP_DIR -backup_dir: '/home/inventree/backup/' +backup_dir: '/home/inventree/data/backup/' # Permit custom authentication backends #authentication_backends: diff --git a/docs/admin/email.md b/docs/admin/email.md new file mode 100644 index 0000000..3d9d93e --- /dev/null +++ b/docs/admin/email.md @@ -0,0 +1,13 @@ +--- +title: Email Configured +--- + +## Email Settings + +InvenTree can be configured to send emails to users, for various purposes. + +To enable this, email configuration settings must be supplied to the InvenTree [configuration options](../../start/config#email-settings). + +!!! info "Password Reset" + The *Password Reset* functionality requires the email backend to be correctly configured. + diff --git a/docs/start/config.md b/docs/start/config.md index 42d2e73..891d364 100644 --- a/docs/start/config.md +++ b/docs/start/config.md @@ -42,10 +42,10 @@ In addition to specifying InvenTree options via the `config.yaml` file, these op The following basic options are available: -| Environment Variable | Settings File | Description | -| --- | --- | --- | -| INVENTREE_DEBUG | debug | Enable debug mode | -| INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | +| Environment Variable | Settings File | Description | Default | +| --- | --- | --- | --- | +| INVENTREE_DEBUG | debug | Enable debug mode | True | +| INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | WARNING | ## Secret Key @@ -73,15 +73,30 @@ Database options are specified under the *database* heading in the configuration The following database options can be configured: -| Environment Variable | Settings File | Description | -| --- | --- | --- | -| INVENTREE_DB_ENGINE | database.ENGINE | Database backend | -| INVENTREE_DB_NAME | database.NAME | Database name | -| INVENTREE_DB_USER | database.USER | Database username (if required) | -| INVENTREE_DB_PASSWORD | database.PASSWORD | Database password (if required) | -| INVENTREE_DB_HOST | database.HOST | Database host address (if required) | -| INVENTREE_DB_PORT | database.PORT | Database host port (if required) | +| Environment Variable | Settings File | Description | Default | +| --- | --- | --- | --- | +| INVENTREE_DB_ENGINE | database.ENGINE | Database backend | *Not set* | +| INVENTREE_DB_NAME | database.NAME | Database name | *Not set* | +| INVENTREE_DB_USER | database.USER | Database username (if required) | *Not set* | +| INVENTREE_DB_PASSWORD | database.PASSWORD | Database password (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* | +## Email Settings + +To enable [email functionality](../../admin/email), email settings must be configured here, either via environment variables or within the configuration file. + +The following email settings are available: + +| Environment Variable | Settings 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 set* | +| INVENTREE_EMAIL_PORT | email.port | Email server port | 25 | +| INVENTREE_EMAIL_USERNAME | email.username | Email account username | *Not set* | +| INVENTREE_EMAIL_PASSWORD | email.password | Email account password | *Not set* | +| INVENTREE_EMAIL_TLS | email.tls | Enable TLS support | False | +| INVENTREE_EMAIL_SSL | email.ssl | Enable SSL support | False | ## Allowed Hosts / CORS diff --git a/mkdocs.yml b/mkdocs.yml index 27a368a..06e8610 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -90,6 +90,7 @@ nav: - Import Data: admin/import.md - Python Shell: admin/shell.md - Error Logs: admin/logs.md + - Email: admin/email.md - Background Tasks: admin/tasks.md - Extend: - API: extend/api.md From 2cf1c858b748ee9d7e5a58fc91f35de4c8f3e99f Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Tue, 13 Apr 2021 20:24:07 +1000 Subject: [PATCH 28/28] update release notes --- docs/releases/0.2.1.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/releases/0.2.1.md b/docs/releases/0.2.1.md index 879123e..2e6af70 100644 --- a/docs/releases/0.2.1.md +++ b/docs/releases/0.2.1.md @@ -8,6 +8,13 @@ title: Release 0.2.1 ## New Features +### Email Support + +[#1304](https://github.com/inventree/InvenTree/pull/1304) adds support for email support. Initially, this is used for sending users emails to perform a password reset + +!!! warning "Configuration Required" + Refer to the [email configuration options](../../start/config/#email-settings). + ## Major Bug Fixes | PR | Description |