From fdf4ac5c7649c539120be7bffabf3cb96820f9f8 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Tue, 15 Jun 2021 23:13:02 +1000 Subject: [PATCH 1/7] Great improvements to the docker development instructions --- docs/start/docker_dev.md | 102 +++++++++++++++++++++++++++++++-------- 1 file changed, 82 insertions(+), 20 deletions(-) diff --git a/docs/start/docker_dev.md b/docs/start/docker_dev.md index 4b0344f..9f75fe5 100644 --- a/docs/start/docker_dev.md +++ b/docs/start/docker_dev.md @@ -15,13 +15,20 @@ There are some key differences compared to the docker production setup: The [InvenTree docker image](https://github.com/inventree/InvenTree/blob/master/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). -### Docker Compose +## Docker Compose -A docker compose script for running a development server is provided at `docker/docker-compose.dev.yml`: +A docker compose script for running a development server is provided in the source repository at [./docker/docker-compose.dev.yml](https://github.com/inventree/InvenTree/blob/master/docker/docker-compose.dev.yml). -### Setup +This script specifies the following containers: -#### Download Source Code +| Container | Description | +| --- | --- | +| inventree-dev-server | Web server using the django development server | +| inventree-dev-worker | Background task manager | + +## Setup + +### Download Source Code First download the source code from GitHub: @@ -30,50 +37,105 @@ git clone git@github.com:inventree/InvenTree.git cd inventree/docker ``` -#### Edit docker-compose File +### (Optional) Edit docker-compose File + +The default docker-compose recipe should work "out of the box". However you may want to edit this file to test some custom functionality. Now, edit the `docker-compose.dev.yml` file (in the `docker` subdirectory), ensuring that the `src` volume points to the directory on your local machine where you have just cloned the source code. -#### Launch Development Server +!!! warning "Beware Changes" + Ensure that you do not commit any changes to the docker-compose.dev.yml file to git! + +### (Optional) Edit Environment Variables + +Environment variables for the development server docker images are set in the file [dev-config.env](https://github.com/inventree/InvenTree/blob/master/docker/dev-config.env). + +In the default configuration these should not need to be adjusted. + +### Launch Development Server Launch the development server with the following command: ``` -docker-compose -f docker-compose.dev.yml up -d inventree-server +docker-compose -f docker-compose.dev.yml up -d inventree-dev-server ``` -This launches the InvenTree server (in development mode) and also performs the following tasks: +This command will perform the following actions, in sequence: -- Creates an sqlite database -- Creates a `config.yaml` file -- Creates a `secret_key.txt` file -- Creates `inventree_media` directory for uploaded media files -- Creates `inventree_static` directory for storing static files +#### Create Required Files + +The following required files are created (if they do not already exist): + +!!! success "File Creation" + The following files are created (paths are relative to the top-level InvenTree source directory). + +| File | Description | +| --- | --- | +| ./dev/config.yaml | InvenTree configuration file | +| ./dev/secret_key.txt | Secret key file | +| ./dev/media | Directory for storing uploaded media files | +| ./dev/static | Directory for storing static files | +| ./dev/env | Python virtual environment | + +#### Install Required Python Packages + +The required python packages will be installed into the `./dev/env/` directory. !!! info "Wait for Install" The first time the server is launched, it will take a few minutes to install the required python packages. -Check that the server is running at [http://localhost:8000](http://localhost:8000) +#### Perform Database Migrations -#### Create Superuser +Database schema migrations are automatically performed. -Once the development server is running, create a superuser (admin) account: +#### Launch Development Server + +Once the required python packages are installed, the development web server is then started. + +!!! success "Check Connection" + Check that the server is running at [http://localhost:8000](http://localhost:8000) before proceeding. + +### Create Superuser + +Once the development server is running, you can now create a superuser (admin) account: ``` -docker-compose -f docker-compose.dev.yml run inventree-server bash +docker-compose -f docker-compose.dev.yml run inventree-dev-server bash ``` Inside the docker shell, run the following commands: ``` -source ./inventree-docker-dev/bin/activate +source ./dev/env/bin/activate invoke superuser ``` -#### Start Background Worker +### Start Background Worker + +The InvenTree web server should now be running - but the background worker has not yet been started: To launch the backround worker process: ``` -docker-compose -f docker-compose.dev.yml up -d inventree-worker +docker-compose -f docker-compose.dev.yml up -d inventree-dev-worker +``` + +## Restarting Services + +Once initial setup is complete, restarting the services is much simpler: + +### Start InvenTree Services + +To restart the InvenTree development server, simply run the following command: + +``` +docker-compose -f docker-compose.dev.yml up -d +``` + +### Stop InvenTree Services + +To stop the InvenTree development server, simply run the following command: + +``` +docker-compose -f docker-compose-dev.yml down ``` From 50d9b32f7371a2298cf5f9c788af0e62aabc617b Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Tue, 15 Jun 2021 23:17:05 +1000 Subject: [PATCH 2/7] Adds note about editing source files --- docs/start/docker_dev.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/start/docker_dev.md b/docs/start/docker_dev.md index 9f75fe5..7f2588a 100644 --- a/docs/start/docker_dev.md +++ b/docs/start/docker_dev.md @@ -139,3 +139,19 @@ To stop the InvenTree development server, simply run the following command: ``` docker-compose -f docker-compose-dev.yml down ``` + +## Editing InvenTree Source + +Any changes made to the InvenTree source code are automatically detected by the services running under docker. + +Thus, you can freely edit the InvenTree source files in your editor of choice. + +### Database Updates + +Any updates which require a database schema change must be reflected in the database itself. + +To run database migrations inside the docker container, run the following command: + +``` +docker-compose -f docker-compose.dev.yml run inventree-dev-server invoke update +``` From 1e3d32c5ca9302f2fa54e00625cdbde7fd3ecb95 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Tue, 15 Jun 2021 23:45:34 +1000 Subject: [PATCH 3/7] Reorganize installation guide pages --- docs/start/docker.md | 224 +----------------------------------- docs/start/docker_dev.md | 10 +- docs/start/docker_prod.md | 232 ++++++++++++++++++++++++++++++++++++++ docs/start/intro.md | 15 ++- mkdocs.yml | 7 +- 5 files changed, 256 insertions(+), 232 deletions(-) create mode 100644 docs/start/docker_prod.md diff --git a/docs/start/docker.md b/docs/start/docker.md index 53eae8c..2847cd5 100644 --- a/docs/start/docker.md +++ b/docs/start/docker.md @@ -63,227 +63,15 @@ By default, the InvenTree container expects the `INVENTREE_SECRET_KEY_FILE` to e !!! warning "Same Key" Each InvenTree container instance must use the same secret key value, otherwise unexpected behavior will occur. -## Docker Compose -It is strongly recommended that you use a [docker-compose](https://docs.docker.com/compose/) script to manage your InvenTree docker image. +## Docker Setup Guides -An example docker compose script is provided below, which provides a robust "out of the box" setup for running InvenTree. +With these basics in mind, refer to the following installation guides: -Firstly, here is the complete `docker-compose.yml` file which can be used "as is" or as a starting point for a custom setup: +### Development Server -``` yaml -{% include 'docker-compose.yml' %} -``` +Refer to the [docker development server setup guide](./docker_dev.md) for instructions on configuring a development server using docker. -### Containers +### Production Server -The following containers are created: - -#### PostgreSQL Database - -A postgresql database container which creates a postgres user:password combination (which can be changed). This uses the official [PostgreSQL image](https://hub.docker.com/_/postgres). - -*__Note__: An empty database must be manually created as part of the setup (below)*. - -#### Web Server - -Runs an InvenTree web server instance, powered by a Gunicorn web server. In the default configuration, the web server listens on port `8000`. - -#### Background Worker - -Runs the InvenTree background worker process. This spins up a second instance of the *inventree* container, with a different entrypoint command. - -#### Nginx - -Nginx working as a reverse proxy, separating requests for static files and directing everything else to Gunicorn. - -This container uses the official [nginx image](https://hub.docker.com/_/nginx). - -An nginx configuration file must be provided to the image. Use the example configuration below as a starting point: - -``` -{% include 'nginx.conf' %} -``` - -*__Note__: You must save this conf file in the same directory as your docker-compose.yml file* - -!!! info "Proxy Pass" - If you change the name (or port) of the InvenTree web server container, you will need to also adjust the `proxy_pass` setting in the nginx.conf file! - -### 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). - -## Production Setup - -With the docker-compose recipe above, follow the instructions below to initialize a complete production server for InvenTree. - -### Required Files - -The following files are required on your local machine (use the examples above, or edit as required): - -- docker-compose.yml -- nginx.conf - -!!! info "Command 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. - -!!! info "Database Credentials" - You may also wish to change the default postgresql username and password! - -### Launch Database Container - -Before we can create the database, we need to launch the database server container: - -``` -docker-compose up -d inventree-db -``` - -This starts the database container. - -### Create Database - -As this is the first time we are interacting with the docker containers, the InvenTree database has not yet been created. - -Run the following command to open a shell session for the database: - -``` -docker-compose run inventree-server pgcli -h inventree-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). - -Once logged in, run the following command in the database shell: - -``` -create database inventree; -``` - -Then exit the shell with Ctrl+d - -### Perform Database Migrations - -The database has now been created, but it is empty! We need to perform the initial database migrations: - -``` -docker-compose run inventree-server 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-server 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-server 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.md)). - -### 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 containers: - -- `inventree-server` - InvenTree web server -- `inventree-worker` - Background worker -- `inventree-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) - -## Updating InvenTree - -To update your InvenTree installation to the latest version, follow these steps: - -### Stop Containers - -Stop all running containers as below: - -``` -docker-compose down -``` - -### Update Images - -Pull down the latest version of the InvenTree docker image - -``` -docker-compose pull -``` - -This ensures that the InvenTree containers will be running the latest version of the InvenTree source code. - -### Start Containers - -Now restart the containers. - -As part of the server initialization process, data migrations and static file updates will be performed automatically. - -``` -docker-compose up -d -``` - -## Data Backup - -Database and media files are stored external to the container, in the volume location specified in the `docker-compose.yml` file. It is strongly recommended that a backup of the files in this volume is performed on a regular basis. - -### Exporting Database as JSON - -To export the database to an agnostic JSON file, perform the following command: - -``` -docker-compose run inventree-server invoke export-records /home/inventree/data/data.json -``` - -This will export database records to the file `data.json` in your mounted volume directory. +Refer to the [docker production server setup guide](./docker_prod.md) for instructions on configuring a production server using docker. diff --git a/docs/start/docker_dev.md b/docs/start/docker_dev.md index 7f2588a..9004cb2 100644 --- a/docs/start/docker_dev.md +++ b/docs/start/docker_dev.md @@ -1,12 +1,12 @@ --- -title: Docker Development Setup +title: Docker Development Server --- -## Docker Development Setup +## Docker Development Server -You can also use docker to launch and manage a development server, in a similar fashion to managing a production server. +You can use docker to launch and manage a development server, in a similar fashion to managing a production server. -There are some key differences compared to the docker production setup: +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 @@ -33,7 +33,7 @@ This script specifies the following containers: First download the source code from GitHub: ``` -git clone git@github.com:inventree/InvenTree.git +git clone git@github.com:inventree/InvenTree.git inventree cd inventree/docker ``` diff --git a/docs/start/docker_prod.md b/docs/start/docker_prod.md new file mode 100644 index 0000000..c8e624c --- /dev/null +++ b/docs/start/docker_prod.md @@ -0,0 +1,232 @@ +--- +title: Docker Production Server +--- + +## Docker Production Server + +Using the [InvenTree docker image](./docker.md) streamlines the setup process for an InvenTree production server. + +## Docker Compose + +It is strongly recommended that you use a [docker-compose](https://docs.docker.com/compose/) script to manage your InvenTree docker image. + +An example docker compose script is provided below, which provides a robust "out of the box" setup for running InvenTree. + +Firstly, here is the complete `docker-compose.yml` file which can be used "as is" or as a starting point for a custom setup: + +``` yaml +{% include 'docker-compose.yml' %} +``` + +### Containers + +The following containers are created: + +#### PostgreSQL Database + +A postgresql database container which creates a postgres user:password combination (which can be changed). This uses the official [PostgreSQL image](https://hub.docker.com/_/postgres). + +*__Note__: An empty database must be manually created as part of the setup (below)*. + +#### Web Server + +Runs an InvenTree web server instance, powered by a Gunicorn web server. In the default configuration, the web server listens on port `8000`. + +#### Background Worker + +Runs the InvenTree background worker process. This spins up a second instance of the *inventree* container, with a different entrypoint command. + +#### Nginx + +Nginx working as a reverse proxy, separating requests for static files and directing everything else to Gunicorn. + +This container uses the official [nginx image](https://hub.docker.com/_/nginx). + +An nginx configuration file must be provided to the image. Use the example configuration below as a starting point: + +``` +{% include 'nginx.conf' %} +``` + +*__Note__: You must save this conf file in the same directory as your docker-compose.yml file* + +!!! info "Proxy Pass" + If you change the name (or port) of the InvenTree web server container, you will need to also adjust the `proxy_pass` setting in the nginx.conf file! + +### 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). + +## Production Setup + +With the docker-compose recipe above, follow the instructions below to initialize a complete production server for InvenTree. + +### Required Files + +The following files are required on your local machine (use the examples above, or edit as required): + +- docker-compose.yml +- nginx.conf + +!!! info "Command 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. + +!!! info "Database Credentials" + You may also wish to change the default postgresql username and password! + +### Launch Database Container + +Before we can create the database, we need to launch the database server container: + +``` +docker-compose up -d inventree-db +``` + +This starts the database container. + +### Create Database + +As this is the first time we are interacting with the docker containers, the InvenTree database has not yet been created. + +Run the following command to open a shell session for the database: + +``` +docker-compose run inventree-server pgcli -h inventree-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). + +Once logged in, run the following command in the database shell: + +``` +create database inventree; +``` + +Then exit the shell with Ctrl+d + +### Perform Database Migrations + +The database has now been created, but it is empty! We need to perform the initial database migrations: + +``` +docker-compose run inventree-server 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-server 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-server 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.md)). + +### 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 containers: + +- `inventree-server` - InvenTree web server +- `inventree-worker` - Background worker +- `inventree-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) + +## Updating InvenTree + +To update your InvenTree installation to the latest version, follow these steps: + +### Stop Containers + +Stop all running containers as below: + +``` +docker-compose down +``` + +### Update Images + +Pull down the latest version of the InvenTree docker image + +``` +docker-compose pull +``` + +This ensures that the InvenTree containers will be running the latest version of the InvenTree source code. + +### Start Containers + +Now restart the containers. + +As part of the server initialization process, data migrations and static file updates will be performed automatically. + +``` +docker-compose up -d +``` + +## Data Backup + +Database and media files are stored external to the container, in the volume location specified in the `docker-compose.yml` file. It is strongly recommended that a backup of the files in this volume is performed on a regular basis. + +### Exporting Database as JSON + +To export the database to an agnostic JSON file, perform the following command: + +``` +docker-compose run inventree-server invoke export-records /home/inventree/data/data.json +``` + +This will export database records to the file `data.json` in your mounted volume directory. diff --git a/docs/start/intro.md b/docs/start/intro.md index ebaea15..3784077 100644 --- a/docs/start/intro.md +++ b/docs/start/intro.md @@ -101,8 +101,7 @@ source 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 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: @@ -123,8 +122,16 @@ There are multiple ways to get an InvenTree server up and running, of various co The recommended method of installing InvenTree is to use [docker](https://www.docker.com). InvenTree provides out-of-the-box support for docker and docker-compose, which provides a simple, reliable and repeatable pipeline for integration into your production environment. -Refer to the [docker setup instructions](./docker.md) for further information. +Refer to the following guides for further instructions: + +- [**Docker development server setup guide**](./docker_dev.md) +- [**Docker production server setup guide**](./docker.md) ### Bare Metal -If you do not wish to use the docker container, you will need to manually install the required packages and follow through the installation guide. Refer to the [InvenTree installation instructions](../install) for more details. +If you do not wish to use the docker container, you will need to manually install the required packages and follow through the installation guide. + +Refer to the following guides for further instructions: + +- [**Bare metal development server setup guide**](./development.md) +- [**Bare metal production server setup guide**](./install.md) diff --git a/mkdocs.yml b/mkdocs.yml index d6bfd1f..cb04ef4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,11 +47,8 @@ nav: - Installation: - Introduction: start/intro.md - Configuration: start/config.md - - Docker Installation: start/docker.md - - Docker Development: start/docker_dev.md - - Manual Installation: start/install.md - - Development Server: start/development.md - - Production Server: start/production.md + - Docker Setup: start/docker.md + - Bare Metal Setup: start/install.md - Updating: start/update.md - Migrating: start/migrate.md - Parts: From 1f31985c147a50a8bfd089a162c4b3f53d727415 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Tue, 15 Jun 2021 23:48:01 +1000 Subject: [PATCH 4/7] Add comment --- docs/start/docker_dev.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/start/docker_dev.md b/docs/start/docker_dev.md index 9004cb2..9309f32 100644 --- a/docs/start/docker_dev.md +++ b/docs/start/docker_dev.md @@ -110,6 +110,8 @@ source ./dev/env/bin/activate invoke superuser ``` +Once you have entered the credentials for the superuser account, type `exit` to exit the bash shell. + ### Start Background Worker The InvenTree web server should now be running - but the background worker has not yet been started: From c6b3422dde910e5810aa3c8fcfa97ffff1f66139 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Wed, 16 Jun 2021 22:32:29 +1000 Subject: [PATCH 5/7] Updates to docker docs --- docs/start/docker.md | 4 ---- docs/start/docker_prod.md | 28 ++++++++++++++++++---------- 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/start/docker.md b/docs/start/docker.md index 2847cd5..6508ea1 100644 --- a/docs/start/docker.md +++ b/docs/start/docker.md @@ -40,10 +40,6 @@ InvenTree data are stored inside the container at `/home/inventree/data`. This directory should be mounted as a volume which points to a directory on your local machine. -### Static Directory - -Static files are stored internal to the container instance, at the location `/home/inventree/static` - ### Configuration File As discussed in the [configuration documentation](./config.md), InvenTree run-time settings can be provided in a configuration file. diff --git a/docs/start/docker_prod.md b/docs/start/docker_prod.md index c8e624c..3c72b86 100644 --- a/docs/start/docker_prod.md +++ b/docs/start/docker_prod.md @@ -22,6 +22,13 @@ Firstly, here is the complete `docker-compose.yml` file which can be used "as is The following containers are created: +| Container | Description | +| --- | --- | +| inventree-db | PostgreSQL database | +| inventree-server | Gunicorn web server | +| invenrtee-worker | django-q background worker | +| inventree-proxy | nginx proxy | + #### PostgreSQL Database A postgresql database container which creates a postgres user:password combination (which can be changed). This uses the official [PostgreSQL image](https://hub.docker.com/_/postgres). @@ -38,7 +45,7 @@ Runs the InvenTree background worker process. This spins up a second instance of #### Nginx -Nginx working as a reverse proxy, separating requests for static files and directing everything else to Gunicorn. +Nginx working as a reverse proxy, separating requests for static and media files, and directing everything else to Gunicorn. This container uses the official [nginx image](https://hub.docker.com/_/nginx). @@ -53,20 +60,21 @@ An nginx configuration file must be provided to the image. Use the example confi !!! info "Proxy Pass" If you change the name (or port) of the InvenTree web server container, you will need to also adjust the `proxy_pass` setting in the nginx.conf file! -### Volumes - -There are two container volumes created: - -#### Data +### 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. !!! info "Data Directory" Make sure you change the path to the local directory where you want persistent data to be stored. -#### Static +The InvenTree docker server will manage the following directories and files within the 'data' volume: -Static files are shared between multiple containers (but not exposed to the local file system). +| Path | Description | +| --- | --- | +| ./config.yaml | InvenTree server configuration file | +| ./secret_key.txt | Secret key file | +| ./media | Directory for storing uploaded media files | +| ./static | Directory for storing static files | ## Production Setup @@ -76,8 +84,8 @@ With the docker-compose recipe above, follow the instructions below to initializ The following files are required on your local machine (use the examples above, or edit as required): -- docker-compose.yml -- nginx.conf +- [docker-compose.yml](https://github.com/inventree/InvenTree/blob/master/docker/docker-compose.yml) +- [nginx.conf](https://github.com/inventree/InvenTree/blob/master/docker/nginx.conf) !!! info "Command Directory" It is assumed that all commands will be run from the directory where `docker-compose.yml` is located. From e1df21aa7acbd64a1585ae1507b3c59c8dca79fd Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Wed, 16 Jun 2021 22:53:00 +1000 Subject: [PATCH 6/7] More updates - Add section on "DEBUG" mode - Update nginx.conf - Update docker-compose.yml --- _includes/docker-compose.yml | 18 +++++++++--------- _includes/nginx.conf | 28 ++++++++++++++++++++++++---- docs/start/intro.md | 30 ++++++++++++++++++++++++++++++ 3 files changed, 63 insertions(+), 13 deletions(-) diff --git a/_includes/docker-compose.yml b/_includes/docker-compose.yml index 9e77dd1..8c2a0b4 100644 --- a/_includes/docker-compose.yml +++ b/_includes/docker-compose.yml @@ -30,6 +30,7 @@ services: - POSTGRES_USER=pguser - POSTGRES_PASSWORD=pgpassword volumes: + # Map 'data' volume such that postgres database is stored externally - data:/var/lib/postgresql/data/ restart: unless-stopped @@ -43,8 +44,8 @@ services: depends_on: - inventree-db volumes: + # Data volume must map to /home/inventree/data - data:/home/inventree/data - - static:/home/inventree/static environment: # Default environment variables are configured to match the 'db' container # Note: If you change the database image, these will need to be adjusted @@ -66,8 +67,8 @@ services: - inventree-db - inventree-server volumes: + # Data volume must map to /home/inventree/data - data:/home/inventree/data - - static:/home/inventree/static environment: # Default environment variables are configured to match the 'db' container # Note: If you change the database image, these will need to be adjusted @@ -81,7 +82,8 @@ services: restart: unless-stopped # nginx acts as a reverse proxy - # static files are served by nginx + # static files are served directly by nginx + # media files are served by nginx, although authentication is redirected to inventree-server # web requests are redirected to gunicorn # NOTE: You will need to provide a working nginx.conf file! inventree-proxy: @@ -93,11 +95,11 @@ services: # Change "1337" to the port that you want InvenTree web server to be available on - 1337:80 volumes: - # Provide nginx.conf file to the container + # Provide ./nginx.conf file to the container # Refer to the provided example file as a starting point - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro - # Static data volume is mounted to /var/www/static - - static:/var/www/static:ro + # nginx proxy needs access to static and media files + - data:/var/www restart: unless-stopped volumes: @@ -110,6 +112,4 @@ volumes: 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 - # Static files, shared between containers - static: \ No newline at end of file + device: /path/to/data \ No newline at end of file diff --git a/_includes/nginx.conf b/_includes/nginx.conf index a9eff10..2703787 100644 --- a/_includes/nginx.conf +++ b/_includes/nginx.conf @@ -1,3 +1,4 @@ + server { # Listen for connection on (internal) port 80 @@ -10,17 +11,17 @@ server { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Host $host; - + proxy_redirect off; - + client_max_body_size 100M; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; - + proxy_buffering off; proxy_request_buffering off; - + } # Redirect any requests for static files @@ -34,4 +35,23 @@ server { add_header Cache-Control "public"; } + # Redirect any requests for media files + location /media/ { + alias /var/www/media/; + + # Media files require user authentication + auth_request /auth; + } + + # Use the 'user' API endpoint for auth + location /auth { + internal; + + proxy_pass http://inventree-server:8000/auth/; + + proxy_pass_request_body off; + proxy_set_header Content-Length ""; + proxy_set_header X-Original-URI $request_uri; + } + } \ No newline at end of file diff --git a/docs/start/intro.md b/docs/start/intro.md index 3784077..12dccf8 100644 --- a/docs/start/intro.md +++ b/docs/start/intro.md @@ -135,3 +135,33 @@ Refer to the following guides for further instructions: - [**Bare metal development server setup guide**](./development.md) - [**Bare metal production server setup guide**](./install.md) + +## Debug Mode + +By default, the InvenTree web server is configured to run in [DEBUG mode](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-DEBUG). + +Running in DEBUG mode provides many handy development features, however it is strongly recommended *NOT* to run in DEBUG mode in a production environment. This recommendation is made because DEBUG mode leaks a lot of information about your installation and may pose a security risk. + +So, for a production setup, you should set `INVENTREE_DEBUG=false` in the [configuration options](./config.md). + +### Potential Issues + +However, turning off DEBUG mode creates further work for the system administrator. In particular, when running in DEBUG mode, the InvenTree web server natively manages *static* and *media* files, which means that the InvenTree server can run "monolithically" without the need for a separate web server. + +With DEBUG mode turned off, a separate web server is required for serving *static* and *media* files. You can find further information in the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/deployment/). + +There are *many* different ways that a sysadmin might wish to handle this. + +The [docker production example](./docker_prod.md) provides an example using [Nginx](https://www.nginx.com/) to serve *static* and *media* files, and redirecting other requests to the InvenTree web server itself. + +You may use this as a jumping off point, or use an entirely different server setup. + +#### Static Files + +Static files can be served without any need for authentication. In fact, they must be accessible *without* authentication, otherwise the unauthenticated views (such as the login screen) will not function correctly. + +#### Media Files + +It is highly recommended that the *media* files are served in such a way that user authentication is required. + +Refer to the [docker production example](./docker_prod.md) for a demonstration of using nginx to serve media files only to authenticated users, and forward authentication requests to the InvenTree web server. From 00720a24007b7df4b144f487e40807cb194006a8 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Wed, 16 Jun 2021 22:56:46 +1000 Subject: [PATCH 7/7] Add a note about "next steps" for a bare-metal setup --- docs/start/production.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/start/production.md b/docs/start/production.md index 1e72e57..29b650b 100644 --- a/docs/start/production.md +++ b/docs/start/production.md @@ -92,3 +92,13 @@ The process status can be viewed [in your web browser](http://localhost:9001). ## Production Ready The InvenTree server (and background task manager) should now be running! + +### Next Steps + +You (or your system administrator) may wish to perform further steps such as placing the InvenTree server behind a reverse-proxy such as [nginx](https://www.nginx.com/). + +As production environment options are many and varied, such tasks are outside the scope of this documentation. + +There are many great online tutorials about running django applications in production! + +As a starting point, you can refer to the [docker production example](./docker_prod.md) for a demonstration of running InvenTree behind a nginx proxy.