From 726ca9cde20cf274a6cfad5898ba40fa1a0f1c2e Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 11 Apr 2021 14:50:23 +1000 Subject: [PATCH] Added docker install instructions --- _includes/docker-compose.yml | 100 +++++++++++++++++++++ docs/admin/tasks.md | 8 +- docs/start/docker.md | 166 ++++++++++++++++++++++++++++++++++- 3 files changed, 272 insertions(+), 2 deletions(-) create mode 100644 _includes/docker-compose.yml diff --git a/_includes/docker-compose.yml b/_includes/docker-compose.yml new file mode 100644 index 0000000..c0ad82a --- /dev/null +++ b/_includes/docker-compose.yml @@ -0,0 +1,100 @@ +version: "3.8" + +# Docker compose recipe for InvenTree +# - Runs PostgreSQL as the database backend +# - Runs Gunicorn as the web server +# - Runs nginx as a reverse proxy +# - Runs the background worker process + +# --------------------------------- +# IMPORTANT - READ BEFORE STARTING! +# --------------------------------- +# Before running, ensure that you change the "/path/to/data" directory, +# specified in the "volumes" section at the end of this file. +# This path determines where the InvenTree data will be stored! + +services: + # Database service + # Use PostgreSQL as the database backend + # Note: this can be changed to a different backend, + # just make sure that you change the INVENTREE_DB_xxx vars below + db: + image: postgres + container_name: inventree_db + ports: + - 5432/tcp + environment: + - PGDATA=/var/lib/postgresql/data/pgdb + - POSTGRES_USER=pguser + - POSTGRES_PASSWORD=pgpassword + volumes: + - data:/var/lib/postgresql/data/ + restart: unless-stopped + + # InvenTree web server services + # Uses gunicorn as the web server + inventree: + image: inventree/inventree:latest + container_name: inventree_server + expose: + - 8080 + depends_on: + - db + volumes: + - data:/home/inventree/data + - static:/home/inventree/static + environment: + - INVENTREE_DB_ENGINE=postgresql + - INVENTREE_DB_NAME=inventree + - INVENTREE_DB_USER=pguser + - INVENTREE_DB_PASSWORD=pgpassword + - INVENTREE_DB_PORT=5432 + - INVENTREE_DB_HOST=db + restart: unless-stopped + + # nginx acts as a reverse proxy + # static files are served by nginx + # web requests are redirected to gunicorn + nginx: + image: inventree/nginx:latest + container_name: inventree_proxy + depends_on: + - inventree + ports: + # Change "1337" to the port where you want InvenTree web server to be available + - 1337:80 + volumes: + - static:/home/inventree/static + + # background worker process handles long-running or periodic tasks + worker: + entrypoint: ./start_worker.sh + image: inventree/inventree:latest + container_name: inventree_worker + depends_on: + - db + - inventree + volumes: + - data:/home/inventree/data + - static:/home/inventree/static + environment: + - INVENTREE_DB_ENGINE=postgresql + - INVENTREE_DB_NAME=inventree + - INVENTREE_DB_USER=pguser + - INVENTREE_DB_PASSWORD=pgpassword + - INVENTREE_DB_PORT=5432 + - INVENTREE_DB_HOST=db + restart: unless-stopped + +volumes: + # Static files, shared between containers + static: + # Persistent data, stored externally + data: + driver: local + driver_opts: + type: none + o: bind + # This directory specified where InvenTree data are stored "outside" the docker containers + # Change this path to a local system path where you want InvenTree data stored + device: /path/to/data diff --git a/docs/admin/tasks.md b/docs/admin/tasks.md index 369f8f3..1881cbb 100644 --- a/docs/admin/tasks.md +++ b/docs/admin/tasks.md @@ -12,12 +12,18 @@ Some tasks (such as sending emails or performing bulk database actions) may take ### Periodic Tasks -Some tasks must be performed on a periodic basis. +Some tasks must be performed on a regular, periodic basis. ## Django Q InvenTree uses the [django-q](https://django-q.readthedocs.io/en/latest/) background task manager. +### Running Worker + +The Django Q work must run separately to the web server. This is started as a separate process, as part of the InvenTree installation instructions. + +If the worker is not running, a warning indicator is displayed in the InvenTree menu bar. + ## Admin Interface Scheduled tasks can be viewed in the InvenTree admin interface. diff --git a/docs/start/docker.md b/docs/start/docker.md index 8904eb9..b372c54 100644 --- a/docs/start/docker.md +++ b/docs/start/docker.md @@ -2,4 +2,168 @@ title: Docker Setup --- -## Docker Setup \ No newline at end of file +## Docker Image + +The most convenient method of installing and running InvenTree is to use the official [docker image](https://hub.docker.com/inventree/inventree). + +The InvenTree docker image contains all the required system packages, python modules, and configuration files for running InvenTree. + +## Docker Compose + +An example docker compose script is provided below, which provides a robust "out of the box" setup for running InvenTree. + +### Containers + +The following containers are created: + +#### PostgreSQL Database + +A postgresql database container which creates a postgres user:password combination (which can be changed) + +#### Web Server + +InvenTree web server running on a Gunicorn backend + +#### Background Worker + +InvenTree background worker process manager + +#### Nginx + +Nginx working as a reverse proxy, separating requests for static files and directing everything else to Gunicorn + +### Volumes + +There are two container volumes created: + +#### Data + +InvenTree stores data which is meant to be persistent (e.g. uploaded media files, database data, etc) in a volume which is mapped to a local system directory. + +!!! info "Data Directory" + Make sure you change the path to the local directory where you want persistent data to be stored. + +#### Static + +Static files are shared between multiple containers (but not exposed to the local file system). + +### Docker Compose File + +Use the following docker-compose file as a starting point: + +``` yaml +{% include 'docker-compose.yml' %} +``` + +## Initial Setup Process + +Follow the instructions below to initialize a complete docker deployment for InvenTree. + +!!! info "Directory" + It is assumed that all commands will be run from the directory where `docker-compose.yml` is located. + +### Configure Compose File + +Save and edit the `docker-compose.yml` file as required. + +The only **required** change is to ensure that the `/path/to/data` entry (at the end of the file) points to the correct directory on your local file system, where you want InvenTree data to be stored. + +### Build + +Build the docker containers: + +``` +docker-compose build +``` + +### Launch Database Server + +Before we can create the database, we need to launch the database server container: + +``` +docker-compose up -d db +``` + +This starts the database container. + +### Create Database + +Run the following command to open a shell session for the database: + +``` +docker-compose run inventree pgcli -h db -p 5432 -u pguser +``` + +!!! info "User" + If you have changed the `POSTGRES_USER` variable in the compose file, replace `pguser` with the different user. + +You will be prompted to enter the database user password (default="pgpassword", unless altered in the compose file). + +Next, run the following command in the database shell: + +``` +create database inventree; +``` + +Then exit the shell with Ctrl+d + +### Perform Database Migrations + +The database has been created, but it is empty! We need to perform the initial database migrations. + +``` +docker-compose run inventree invoke migrate +``` + +This will perform the required schema updates to create the required database tables. + +### Collect Static Files + +On first run, the required static files must be collected into the `static` volume: + +``` +docker-compose run inventree invoke static +``` + +### Create Admin Account + +You need to create an admin (superuser) account for the database. Run the command below, and follow the prompts: + +``` +docker-compose run inventree invoke superuser +``` + +### Configure InvenTree Options + +By default, all required InvenTree settings are specified in the docker compose file, with the `INVENTREE_DB_` prefix. + +You are free to skip this step, if these InvenTree settings meet your requirements. + +If you wish to tweak the InvenTree configuration options, you can either: + +#### Environment Variables + +Alter (or add) environment variables into the docker-compose `environment` section + +#### Configuration File + +A configuration file `config.yaml` has been created in the data volume (at the location specified on your local disk). + +Edit this file (as per the [configuration guidelines](../config)). + +### Run Web Server + +Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the web server: + +``` +docker-compose up -d +``` + +This command launches the remaining container processes: + +- `inventree` - InvenTree web server +- `worker` - Background worker +- `nginx` - Nginx reverse proxy + +!!! success "Up and Running!" + You should now be able to view the InvenTree login screen at [http://localhost:1337](http://localhost:1337)