inventree/inventree-docs
2
0
Fork 0
mirror of https://github.com/inventree/inventree-docs.git synced 2025-04-28 13:46:54 +00:00
Code

Refactor installation instructions

Browse Source 
(cherry picked from commit 2eb4589b0176b7377135c4539531abde7d0a88b4)
This commit is contained in:
Oliver Walters 2021-04-08 21:03:45 +10:00
parent 2f3154fede
commit 2b3a0c7748
7 changed files with 351 additions and 312 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/start/config.md
View File

@ -81,36 +81,6 @@ The following database options can be configured:
| INVENTREE_DB_HOST | database.HOST | Database host address (if required) | | INVENTREE_DB_HOST | database.HOST | Database host address (if required) |
| INVENTREE_DB_PORT | database.PORT | Database host port (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 ### Allowed Hosts / CORS

214
docs/start/deploy.md
View File

@ -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
```

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

@ -0,0 +1,58 @@
---
title: Development Server
---
## Development Server
!!! warning "Installation"
Before continuing, ensure that the [installation steps](../install) 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.

277
docs/start/install.md
View File

@ -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" Install required system packages (as superuser).
Refer to the [deployment instructions](../deploy) to implement a much more robust server setup.
## 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. !!! 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.
Install invoke as follows: Create a user account from which we will run the server:
``` ```
pip3 install invoke sudo useradd --create-home inventree
``` ```
!!! warning "Invoke Version" InvenTree source code, log files, etc will be located under the `/home/inventree/` directory.
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 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 ### Create Required Directories
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:
``` ```
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 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" !!! success "Ready to Serve"
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`. 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. 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
```

49
docs/start/intro.md
View File

@ -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. 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 * SQLite
* PostgreSQL * PostgreSQL
* MariaDB * MariaDB
* MySQL * 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 ### 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). 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 ### Background Tasks
A separate application handles management of [background tasks](../../admin/tasks), separate to user-facing web requests. 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" !!! 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. 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: 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 ### 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 ### 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. This will place the current shell session inside a virtual environment - the terminal should display the ``(env)`` prefix.
## Downloading Source Code ## 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: 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). 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 ## Installation Guides
There are multiple ways to get an InvenTree server up and running, of various complexity (and robustness)! 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 ### 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.

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

@ -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

7
mkdocs.yml
View File

@ -42,12 +42,11 @@ nav:
- What's New: releases/new.md - What's New: releases/new.md
- FAQ: faq.md - FAQ: faq.md
- Contribute: contribute.md - Contribute: contribute.md
- Getting Started: - Installation:
- Introduction: start/intro.md - Introduction: start/intro.md
- Docker Installation: start/docker.md
- Manual Installation: start/install.md
- Configuration: start/config.md - Configuration: start/config.md
- Development: start/install.md
- Production: start/deploy.md
- Docker: start/docker.md
- Updating: start/update.md - Updating: start/update.md
- Migrating: start/migrate.md - Migrating: start/migrate.md
- Parts: - Parts: