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: