From 5cb82079d3caab8a37ffcf13778c331481fc9956 Mon Sep 17 00:00:00 2001 From: Matthias Mair Date: Sun, 16 Oct 2022 00:54:57 +0200 Subject: [PATCH] Package installer docs (#368) * Add docs for package install * fix grammar error * fix link * remove vscode file * Add extra pip env * Add debug output * add docs for database * add section about envs * some more general architecture comments * grammar * add comment about auto-pushing --- .gitignore | 2 +- docs/start/install.md | 3 ++ docs/start/installer.md | 115 ++++++++++++++++++++++++++++++++++++++++ docs/start/intro.md | 7 +++ mkdocs.yml | 1 + 5 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 docs/start/installer.md diff --git a/.gitignore b/.gitignore index d75949c..3b07513 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,4 @@ env/ # Temp files releases.json -.vscode \ No newline at end of file +.vscode/ \ No newline at end of file diff --git a/docs/start/install.md b/docs/start/install.md index a4d5df5..bce25e8 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -7,6 +7,9 @@ title: Install InvenTree !!! tip "Docker Guide" This guide is for a *bare metal* InvenTree installation. If you want to install using Docker (the recommended approach) refer to the [Docker Guide](./docker.md) +!!! tip "Installer" + There is an [installer](./installer.md) available - we recommend using that method. + Follow the instructions below to install the required system packages, python modules, and InvenTree source code. ### Install System Packages diff --git a/docs/start/installer.md b/docs/start/installer.md new file mode 100644 index 0000000..f5e0539 --- /dev/null +++ b/docs/start/installer.md @@ -0,0 +1,115 @@ +--- +title: InvenTree Installer +--- + +## Install +The package installer places the app files in `/opt/inventree`, the configs in `/etc/inventree` and data (static, media and database) in `/opt/inventree/data` (see [Moving Data](#moving-data) for details). + +Supported OSs are Debian 11 and Ubuntu 20.04 LTS. + +### Quick Script + +```bash +curl https://raw.githubusercontent.com/InvenTree/InvenTree/master/contrib/install.sh | sudo sh +``` + +This script does all manual steps without any input. The installation might take 5-10 minutes to finish. + +### Manual Install + +The steps below are for Ubuntu 20.04 LTS, the current instructions for Ubuntu and Debian can be found [here](https://packager.io/gh/inventree/InvenTree). + +Add the key needed for validating the packages. +```bash +wget -qO- https://dl.packager.io/srv/inventree/InvenTree/key | sudo apt-key add - +``` + +Add the package list to the package manager source list. +```bash +sudo wget -O /etc/apt/sources.list.d/inventree.list https://dl.packager.io/srv/inventree/InvenTree/stable/installer/ubuntu/20.04.repo +``` + +Update the local package index. +```bash +sudo apt-get update +``` + +Install the InvenTree package itself. This step might take multiple minutes. +```bash +sudo apt-get install inventree +``` + +### Options + +#### Debug Outputs +Extra debug messages are printed if the environment variable `SETUP_DEBUG` is set. This exposes passwords. + +#### External Calls +By default, a public AWS service is used to resolve the public IP address of the server. To prevent this the environment variable `SETUP_NO_CALLS` must be set to `true`. + +#### Admin User +By default, an admin user is automatically generated with username `admin`, mail `admin@example.com` and a dynamic password that is saved to `/etc/inventree/admin_password`. +These values can be customised with the environment variables `INVENTREE_ADMIN_USER`, `INVENTREE_ADMIN_EMAIL` and `INVENTREE_ADMIN_PASSWORD`. +To stop the automatic generation of an admin user, generate an empty file needs to be placed at `/etc/inventree/admin_password`. + +#### Webconfig +By default, InvenTree is served internally on port 6000 and then proxied via Nginx. The config is placed in `/etc/nginx/sites-enabled/inventree.conf` and overwritten on each update. The location can be set with the environment variable `SETUP_NGINX_FILE`. +This only serves an HTTP version of InvenTree, to use HTTPS (recommended for production) or customise any further an additional config file should be used. + +#### Extra python packages +Extra python packages can be installed by setting the enviroment variable `SETUP_EXTRA_PIP`. + +#### Database Options +The used database backend can be configured with enviroment variables (before the first setup) or in the config file after the installation. Check the [configuration section](./config.md#database-options) for more information. + +## Moving Data +To change the data storage location, link the new location to `/opt/inventree/data`. +A rough outline of steps to achieve this could be: +- shut down the app service(s) `inventree` and webserver `nginx` +- copy data to the new location +- check everything was transferred successfully +- delete the old location +- create a symlink from the old location to the new one +- start up the services again + +## Updating InvenTree + +To update InvenTree run `apt update inventree` - this might need to be run as a sudo user. + +## Controlling InvenTree + +### Services +InvenTree installs multiple services that can be controlled with your local system runner (`service` or `systemctl`). +The service `inventree` controls everything, `inventree-web` the (internal) webserver and `inventree-worker` the background worker(s). + +More instances of the worker can be instantiated from the command line. This is only meant for advanced users. +This sample script launches 3 services. By default, 1 is launched. +```bash +inventree scale worker=3 +``` + +### Environment Variables + +The CLI can be used to permanently modify the environment variables used while executing the app server or workers. + +To set variables use +```bash +inventree config:set ENV_VAR=123 +``` + +To read out all variables use +```bash +inventree config +``` + +!!! warning "Keep things repeatable" + All CLI settings are lost when the package is uninstalled. + Use the config file where possible as it is kept on uninstall and can easily be synced across instances. Environment variables are a good place for passwords (but not the secret_key). + +## Architecture + +The packages are provided by [packager.io](https://packager.io/). They are built each time updates are pushed to GitHub and released about 10 minutes later. The local package index must be updated to see the new release in the package manager. + +The package sets up [services](#controlling-inventree) that run the needed processes as the unprivileged user `inventree`. This keeps the privileges of InvenTree as low as possible. + +A CLI is provided to interface with low-level management functions like [variable management](#enviroment-variables), log access, commands, process scaling, etc. diff --git a/docs/start/intro.md b/docs/start/intro.md index 595da83..21d2ea8 100644 --- a/docs/start/intro.md +++ b/docs/start/intro.md @@ -2,6 +2,13 @@ title: Setup Introduction --- +!!! info "Fast install" + A quick-and-easy install can be done done with the following one-liner. + ```bash + curl https://raw.githubusercontent.com/InvenTree/InvenTree/master/contrib/install.sh | sh + ``` + Read more about the [installer](./installer.md). + ## Introduction InvenTree can be self-hosted with minimal system requirements. Multiple database back-ends are supported, allowing for flexibility where required. diff --git a/mkdocs.yml b/mkdocs.yml index 8da99f0..99acab5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,6 +70,7 @@ nav: - Production: start/docker_prod.md - Bare Metal: - Introduction: start/install.md + - Installer: start/installer.md - Development: start/development.md - Production: start/production.md - Migrating Data: start/migrate.md