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: