Initial commit

- Copied from inventree.github.io

docs/start/config.md

@@ -0,0 +1,114 @@
+---
+title: Database Configuration
+layout: page
+---
+
+## 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.
+
+### Configuration File
+
+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 configuration file launches a *DEBUG* configuration with a simple SQLITE database backend. This default configuration file is shown below:
+
+``` yaml
+{% include 'config.yaml' %}
+```
+
+### Database Options
+
+InvenTree provides support for multiple database backends - any backend supported natively by Django can be used. 
+
+Database options are specified under the *database* heading in the configuration file. Any option available in the Django documentation can be used here - it is passed through transparently to the management scripts.
+
+<hr>
+
+**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. 
+
+<hr>
+
+**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*
+
+To install these required packages, run the following command:
+
+```
+invoke 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"
+    When creating the MySQL database, the adminstrator must ensure that the collation option is set to <b>utf8_unicode_520_ci</b> 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.
+
+<hr>
+
+**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
+
+To install these required packages, run the following commands:
+
+```
+invoke 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.
+
+### 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.
+
+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)
+
+### Static File Storage
+
+By default, static files are stored in the local directory `./inventree_media`. This directory should be changed in the config file based on the particular installation requirements.
+
+### Uploaded File Storage
+
+By default, uploaded media files are stored in the local directory `./inventree_media`. This directory should be changed in the config file based on the particular installation requirements.
+
+### 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.
+
+### Sentry.io Integration
+
+InvenTree supports [sentry.io](https://sentry.io) integration using the native django/sentry bindings. If you have a sentry.io account, create a new dsn and provide this in the `config.yaml` file.
+
+### LaTeX Support
+
+To enable genration of [LaTeX](https://en.wikipedia.org/wiki/LaTeX) reports, latex support must be enabled here.
+
+- **enabled** : Set to True to enable LaTeX support
+- **interpreter** : Select the LaTeX interpreter to be used (must be installed on the local machine!)
+
+### Authentication Backends
+
+Custom authentication backends can be used by specifying them here
+
+### Middleware
+
+Custom middleware layers can specified here.

docs/start/deploy.md

@@ -0,0 +1,77 @@
+---
+title: Deploy InvenTree
+layout: page
+---
+
+## 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.
+
+### 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:
+
+```
+invoke 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`:
+
+```
+invoke server -a 192.168.120.1:8000
+```
+
+## 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
+```
+
+### 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:
+
+```
+invoke 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
+```

docs/start/install.md

@@ -0,0 +1,171 @@
+---
+title: Install InvenTree
+layout: page
+---
+
+## Introduction
+
+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).
+
+### Supported Databases
+
+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.
+
+### 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](start/deploy).
+
+## Setup
+
+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. 
+
+!!! warning "Windows"
+    If you are using the Windows operating system, it is recommended that you use the <a href='https://docs.microsoft.com/en-us/windows/wsl/install-win10'>WSL (Windows Subsystem for Linux) framework</a>
+
+### Requirements
+
+To install InvenTree you will need python3 (>3.6) installed, as well as PIP (the Python package manager).
+
+Install these required programs (e.g. using apt or similar) before running the setup scripts.
+
+For example:
+
+```
+sudo apt-get update
+sudo apt-get install python3 python3-dev python3-pip
+```
+
+!!! 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
+
+### 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
+```
+
+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.
+
+Install invoke as follows:
+
+```
+pip3 install invoke
+```
+
+To display a list of the available configuration scripts, run the following command:
+
+```
+invoke --list
+```
+
+## 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)*.
+
+## 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):
+
+```
+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.
+
+### 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.
+
+For further information on installation configuration, refer to the [Configuration](start/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:
+
+```
+invoke migrate
+```
+
+This performs the initial database migrations, creating the required tables, etc.
+
+The database should now be installed!
+
+### Create Admin Account
+
+Create an initial superuser (administrator) account for the InvenTree instance:
+
+```
+invoke superuser
+```
+
+### Run 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:
+
+```
+invoke server
+```
+
+For more server options, run:
+
+```
+invoke server -h
+```
+
+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/)
+
+### Run Production Server
+
+For a production install, refer to [deployment instructions](start/deploy).

docs/start/migrate.md

@@ -0,0 +1,40 @@
+---
+title: Migrating Data
+layout: page
+---
+
+## Migrating Data
+
+In the case that data needs to be migrated from one database installation to another, the following procedure can be used to export data, initialize the new database, and re-import the data.
+
+!!! warning "Backup Database"
+	Ensure that the original database is securely backed up first!
+
+### Export Data
+
+```
+python3 InvenTree/manage.py dumpdata --exclude contenttypes --exclude auth.permission --indent 2 > data.json
+```
+
+This will export all data (including user information) to a json data file.
+
+### Initialize New Database
+
+Configure the new database using the normal processes (see [Configuration](start/config))
+
+Then, ensure that the database schema are correctly initialized in the new database:
+
+```
+python3 InvenTree/manage.py makemigrations
+python3 InvenTree/manage.py migrate --run-syncdb
+```
+
+### Import Data
+
+The new database should now be correctly initialized with the correct table structures requried to import the data. Run the following command to load the databased dump file into the new database.
+
+```
+python3 InvenTree/manage.py loaddata data.json
+```
+!!! info "Character Encoding"
+	If the character encoding of the data file does not exactly match the target database, the import operation may not succeed. In this case, some manual editing of the database JSON file may be required.

docs/start/update.md

@@ -0,0 +1,44 @@
+---
+title: Update InvenTree
+layout: page
+---
+
+## Update InvenTree
+
+Administrators wishing to update InvenTree to the latest version should follow the instructions below. The commands listed below should be run from the InvenTree root directory.
+
+!!! info "Update Database"
+	It is advisable to backup the InvenTree database before performing these steps. The particular backup procedure may depend on your installation details.
+
+### Stop InvenTree Server
+
+Ensure the InvenTree server is stopped. This will depend on the particulars of your database installation.
+
+### Update Source Code
+
+Update the InvenTree source code to the latest version (or a particular commit if required).
+
+For example, pull down the latest InvenTree sourcecode using Git:
+
+```
+git pull origin master
+```
+
+### Perform Database Migrations
+
+Updating the database is as simple as calling the `update` script:
+
+```
+invoke update
+```
+
+This command performs the following steps:
+
+* Ensure all rquired packages are installed and up to date
+* Perform required database schema changes
+* Run the user through any steps which require interaction
+* Collect any new or updated static files
+
+### Restart Server
+
+Ensure the InvenTree server is restarted. This will depend on the particulars of your database installation.