From e73db9d2843d608e8f03001d594f99ca13d95413 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 29 May 2022 00:22:07 +1000 Subject: [PATCH 1/5] Simplify docker development instructions --- docs/start/docker_dev.md | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/docs/start/docker_dev.md b/docs/start/docker_dev.md index 853210e..08c1759 100644 --- a/docs/start/docker_dev.md +++ b/docs/start/docker_dev.md @@ -6,29 +6,32 @@ title: Docker Development Server You can use docker to launch and manage a development server, in a similar fashion to managing a production server. +The InvenTree dockerfile (`./Dockerfile`) uses a [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) process to allow both production and development setups from the same image. + There are some key differences compared to the [docker production setup](./docker_prod.md): - The docker image is built locally, rather than being downloaded from DockerHub -- The docker image points to the source code on your local machine, instead of cloning from GitHub +- The docker image points to the source code on your local machine (mounted as a 'volume' in the docker container) - The django webserver is used, instead of running behind Gunicorn - The server will automatically reload when code changes are detected !!! info "Static and Media Files" The development server runs in DEBUG mode, and serves static and media files natively. -The InvenTree dockerfile (`./docker/Dockerfile`) uses a [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) process to allow both production and development setups from the same image. The key difference is that the production image is pre-built using InvenTree source code from GitHub, while the development image uses the source code from your local machine (allowing live code updates). - !!! info "Hacker Mode" The following setup guide starts a development server which will reload "on the fly" as changes are made to the source code. This is designed for programmers and developers who wish to add and test new InvenTree features. ## Development Setup Guide -!!! info "Starting Point" - This setup guide assumes you are starting in the `./docker/` directory. +To get started with an InvenTree development setup, follow the simple steps outlined below. Before continuing, ensure that you have completed the following steps: -### Edit Environment Variables +- Downloaded the InvenTree source code to your local machine +- Installed docker on your local machine (install *Docker Desktop* on Windows) +- Have a terminal open to the root directory of the InvenTree source code -If required, the user may edit the environment variables, located in the `.env` file. +### Edit Environment Variables (Optional) + +If desired, the user may edit the environment variables, located in the `.env` file. !!! success "This step is optional" This step can be skipped, as the default variables will work just fine! @@ -36,16 +39,6 @@ If required, the user may edit the environment variables, located in the `.env` !!! info "Database Credentials" You may also wish to change the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`) from their default values -### Create Database - -Launch the postgresql database container, and create an empty database, with the following command: - -```bash -docker-compose run -d inventree-dev-db -``` - -This will start the `inventree-dev-db` container (in the background) and create an empty database. - ### Perform Initial Setup The database has now been created, but it is empty! Perform the initial database setup by running the following command: From b83aed9a8ad34f91e1544ee96ea75270b28df245 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 29 May 2022 00:47:04 +1000 Subject: [PATCH 2/5] Update docs for production image --- docs/start/config.md | 10 ++++++++ docs/start/docker_prod.md | 52 ++++++++++++++++++++------------------- 2 files changed, 37 insertions(+), 25 deletions(-) diff --git a/docs/start/config.md b/docs/start/config.md index ddaf0cf..06dc741 100644 --- a/docs/start/config.md +++ b/docs/start/config.md @@ -48,6 +48,16 @@ The following basic options are available: | INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | WARNING | | INVENTREE_PLUGINS_ENABLED | plugins_enabled | Enable plugin support | False | +## Administrator Account + +An administrator account can be specified using the following environment variables: + +| Environment Variable | Settings File | Description | Default | +| --- | --- | --- | --- | +| INVENTREE_ADMIN_USER | admin_user | Admin account username | *Not set* | +| INVENTREE_ADMIN_PASSWORD | admin_password | Admin account password | *Not set* | +| INVENTREE_ADMIN_EMAIL | admin_email |Admin account email address | *Not set* | + ## Secret Key InvenTree requires a secret key for providing cryptographic signing - this should be a secret (and unpredictable) value. diff --git a/docs/start/docker_prod.md b/docs/start/docker_prod.md index aefa67b..65e06e6 100644 --- a/docs/start/docker_prod.md +++ b/docs/start/docker_prod.md @@ -4,15 +4,17 @@ title: Docker Production Server ## Docker Production Server -Using the [InvenTree docker image](./docker.md) streamlines the setup process for an InvenTree production server. +Using the [InvenTree docker image](./docker.md) simplifies the setup process for an InvenTree production server. The following guide provides a streamlined production InvenTree installation, with minimal configuration required. +!!! info "Starting Point" + This setup guide should be considered a *starting point*. It is likely that your particular production requirements will vary from the example shown here. + ### Before You Start -#### Docker Compose - -This guide assumes that you are comfortable with the basic concepts of docker and docker-compose. +!!! warning "Docker Skills Required" + This guide assumes that you are reasonably comfortable with the basic concepts of docker and docker-compose. #### Docker Image @@ -20,15 +22,17 @@ This production setup guide uses the official InvenTree docker image, available #### Static and Media Files -The sample docker-compose configuration shown on this page uses nginx to serve static files and media files. If you change this configuration, you will need to ensure that static and media files are served correctly. When running with `debug=False`, django *will not serve these files* - see the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/). +The sample docker-compose configuration outlined on this page uses nginx to serve static files and media files. If you change this configuration, you will need to ensure that static and media files are served correctly. When running with `debug=False`, django *will not serve these files* - see the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/). #### Required Files The files required for this setup are provided with the InvenTree source, located in the `./docker/production` directory: -- **docker-compose.yml** : The docker compose script -- **.env** : Environment variables -- **nginx.prod.conf** : nginx proxy configuration file +| Filename | Description | +| --- | --- | +| docker-compose.yml | The docker compose script | +| .env | Environment variables | +| nginx.prod.conf | nginx proxy configuration file | This tutorial assumes you are working from the `./docker/production` directory. If this is not the case, ensure that these files are provided in your working directory. @@ -63,16 +67,13 @@ This container uses the official [nginx image](https://hub.docker.com/_/nginx). ### Data Volume -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. The location of this directory must be configured in the `.env` file. +InvenTree stores any persistent data (e.g. uploaded media files, database data, etc) in a [volume](https://docs.docker.com/storage/volumes/) which is mapped to a local system directory. The location of this directory must be configured in the `.env` file, specified using the `INVENTREE_EXT_VOLUME` variable. !!! info "Data Directory" Make sure you change the path to the local directory where you want persistent data to be stored. ## Production Setup Guide -!!! info "Starting Point" - This setup guide assumes you are starting in the `./docker/production/` directory. - ### Edit Environment Variables The first step is to edit the environment variables, located in the `.env` file. @@ -83,19 +84,10 @@ The first step is to edit the environment variables, located in the `.env` file. !!! warning "Database Credentials" You must also define the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`). You should ensure they are changed from the default values for added security -### Create Database -Launch the postgresql database container, and create an empty database, with the following command: +### Initial Database Setup -```bash -docker-compose run -d inventree-db -``` - -This will start the `inventree_db` container (in the background) and create an empty database. - -### Perform Database Setup - -The database has now been created, but it is empty! Perform the initial database setup by running the following command: +Perform the initial database setup by running the following command: ```bash docker-compose run inventree-server invoke update @@ -104,11 +96,12 @@ docker-compose run inventree-server invoke update This command performs the following steps: - Ensure required python packages are installed +- Create a new (empty) database - Perform the required schema updates to create the required database tables - Update translation files - Collect all required static files into a directory where they can be served by nginx -### Create Admin Account +### Create Administrator Account If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts: @@ -116,6 +109,14 @@ If you are creating the initial database, you need to create an admin (superuser docker-compose run inventree-server invoke superuser ``` +Alternatively, admin account details can be specifed in the `.env` file, removing the need for this manual step: + +| Variable | Description | +| --- | --- | +| INVENTREE_ADMIN_USER | Admin account username | +| INVENTREE_ADMIN_PASSWORD | Admin account password | +| INVENTREE_ADMIN_EMAIL | Admin account email address | + ### Start Docker Containers Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers: @@ -124,8 +125,9 @@ Now that the database has been created, migrations applied, and you have created docker-compose up -d ``` -This command launches the remaining containers: +This command launches the following containers: +- `inventree-db` - PostgreSQL database - `inventree-server` - InvenTree web server - `inventree-worker` - Background worker - `inventree-nginx` - Nginx reverse proxy From a9cc1ae9fb7c8045e6bc7f42b35f616f5134dbda Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 29 May 2022 07:54:22 +1000 Subject: [PATCH 3/5] Update base install requirements --- docs/start/install.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/start/install.md b/docs/start/install.md index 1909f9c..9e39bfa 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -15,8 +15,11 @@ Install required system packages (as superuser): ``` sudo apt-get update -sudo apt-get install python3 python3-dev -sudo apt-get install python3-pip python3-invoke python3-venv +sudo apt-get install \ + python3 python3-dev python3-pip python3-invoke python3-venv \ + git gcc g++ gettext gnupg \ + poppler-utils libpango-1.0-0 libpangoft2-1.0-0 \ + libjpeg-dev webp ``` !!! warning "Weasyprint" From 9306964652c37514a075d779f140705196978af9 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 29 May 2022 07:55:19 +1000 Subject: [PATCH 4/5] Add note about minimum python version --- docs/start/install.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/start/install.md b/docs/start/install.md index 9e39bfa..7fae7e0 100644 --- a/docs/start/install.md +++ b/docs/start/install.md @@ -13,6 +13,9 @@ Install required system packages (as superuser): !!! warning "OS Specific Requirements" The following packages are required on a debian system. A different distribution may require a slightly different set of packages +!!! info "Python Version" + InvenTree requires Python version 3.8 or newer + ``` sudo apt-get update sudo apt-get install \ From ce53c40bde4f80034ac69217562968cb7c0a98c6 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 29 May 2022 08:04:40 +1000 Subject: [PATCH 5/5] Add warning about scrubbing account data --- docs/start/docker_prod.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/start/docker_prod.md b/docs/start/docker_prod.md index 65e06e6..ad88000 100644 --- a/docs/start/docker_prod.md +++ b/docs/start/docker_prod.md @@ -117,6 +117,9 @@ Alternatively, admin account details can be specifed in the `.env` file, removin | INVENTREE_ADMIN_PASSWORD | Admin account password | | INVENTREE_ADMIN_EMAIL | Admin account email address | +!!! warning "Scrub Account Data" + Ensure that the admin account credentials are removed from the `.env` file after the first run, for security. + ### Start Docker Containers Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers: