From 96021bf79a9b457d183f644e6c3272683ec3258a Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 18 Apr 2021 16:28:01 +1000 Subject: [PATCH 1/4] Improvements for docker documentation (cherry picked from commit a619e92ca8946c336116dfd0cb1e5ef4cb3c9588) --- _includes/docker-compose.yml | 71 +++++++++++++++++++----------------- _includes/nginx.conf | 24 ++++++++++++ docs/start/docker.md | 59 ++++++++++++++++++++++++++---- 3 files changed, 113 insertions(+), 41 deletions(-) create mode 100644 _includes/nginx.conf diff --git a/_includes/docker-compose.yml b/_includes/docker-compose.yml index c0ad82a..31b43ba 100644 --- a/_includes/docker-compose.yml +++ b/_includes/docker-compose.yml @@ -12,6 +12,7 @@ version: "3.8" # 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 @@ -19,12 +20,13 @@ services: # Note: this can be changed to a different backend, # just make sure that you change the INVENTREE_DB_xxx vars below db: + container_name: db image: postgres - container_name: inventree_db ports: - 5432/tcp environment: - PGDATA=/var/lib/postgresql/data/pgdb + # The pguser and pgpassword values must be the same in the other containers - POSTGRES_USER=pguser - POSTGRES_PASSWORD=pgpassword volumes: @@ -33,62 +35,63 @@ services: # InvenTree web server services # Uses gunicorn as the web server - inventree: + web: + container_name: web image: inventree/inventree:latest - container_name: inventree_server expose: - - 8080 + - 8000 depends_on: - db volumes: - data:/home/inventree/data - static:/home/inventree/static environment: - - INVENTREE_DB_ENGINE=postgresql - - INVENTREE_DB_NAME=inventree + # Default environment variables are configured to match the 'db' container + # Database permissions + - INVENTREE_DB_USER=pguser + - INVENTREE_DB_PASSWORD=pgpassword + restart: unless-stopped + + # background worker process handles long-running or periodic tasks + worker: + container_name: worker + image: inventree/inventree:latest + entrypoint: ./start_worker.sh + depends_on: + - db + - web + volumes: + - data:/home/inventree/data + - static:/home/inventree/static + environment: + # Default environment variables are configured to match the 'db' container + # Database permissions - 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 + # NOTE: You will need to provide a working nginx.conf file! nginx: - image: inventree/nginx:latest - container_name: inventree_proxy + container_name: nginx + image: nxinx depends_on: - - inventree + - web 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 + # Provide nginx.conf file to the container + # Refer to the provided example file as a starting point + - ./nginx.conf:/etc/nginx/templates/default.conf.template:ro + # Static data volume is mounted to /var/www/static + - static:/var/www/static restart: unless-stopped volumes: - # Static files, shared between containers - static: + # NOTE: Change /path/to/data to a directory on your local machine # Persistent data, stored externally data: driver: local @@ -98,3 +101,5 @@ volumes: # 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 diff --git a/_includes/nginx.conf b/_includes/nginx.conf new file mode 100644 index 0000000..af681b0 --- /dev/null +++ b/_includes/nginx.conf @@ -0,0 +1,24 @@ +upstream inventree { + # Should point to the InvenTree web server container + server web:8000; +} + +server { + + # Listen for connection on (internal) port 80 + listen 80; + + location / { + proxy_pass http://inventree; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header Host $host; + proxy_redirect off; + client_max_body_size 100M; + } + + # Redirect any requests for static files + location /static/ { + alias /var/www/static/; + } + +} \ No newline at end of file diff --git a/docs/start/docker.md b/docs/start/docker.md index 275a37c..a016551 100644 --- a/docs/start/docker.md +++ b/docs/start/docker.md @@ -8,29 +8,52 @@ The most convenient method of installing and running InvenTree is to use the off The InvenTree docker image contains all the required system packages, python modules, and configuration files for running InvenTree. +!!! info "Configuration Files" + All of the configuration files discussed below are available under the *docker* subdirectory of the [InvenTree source code](https://github.com/inventree/inventree) + ## 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) +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 -InvenTree web server running on a Gunicorn backend +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 -InvenTree background worker process manager +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 +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* ### Volumes @@ -47,14 +70,22 @@ InvenTree stores data which is meant to be persistent (e.g. uploaded media files Static files are shared between multiple containers (but not exposed to the local file system). +## Environment Variables + +The InvenTree web server requires a number of configuration options to be specified to connect to the database. These are provided to the docker container(s) using the `environment:` section for each container + +In the default configuration, only the following environment variables are required for the `web` and `worker` containers: + +- **INVENTREE_DB_USER** - Database username (default=pguser) +- **INVENTREE_DB_PASSWORD** - Database password (default=pgpassword) + +!!! warning "Altering Database Configuration" + If the database image is altered from the default postgresql image, then the InvenTree environment variables must be adjusted to match. + ### 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. @@ -159,3 +190,15 @@ This command launches the remaining container processes: !!! success "Up and Running!" You should now be able to view the InvenTree login screen at [http://localhost:1337](http://localhost:1337) + +## Database Access + +## Production Serevr + +## Development Server + +## Updating InvenTree + +## SEcret Key + +## Settings file \ No newline at end of file From 2b02c3164ad5397a272efd47599680f35cd44ec3 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 18 Apr 2021 18:41:56 +1000 Subject: [PATCH 2/4] Expanded docker documentation --- _includes/nginx.conf | 2 +- docs/start/docker.md | 133 +++++++++++++++++++++++++++++++++---------- 2 files changed, 103 insertions(+), 32 deletions(-) diff --git a/_includes/nginx.conf b/_includes/nginx.conf index af681b0..1688c1e 100644 --- a/_includes/nginx.conf +++ b/_includes/nginx.conf @@ -1,6 +1,6 @@ upstream inventree { # Should point to the InvenTree web server container - server web:8000; + server inventree:8000; } server { diff --git a/docs/start/docker.md b/docs/start/docker.md index a016551..1ee6928 100644 --- a/docs/start/docker.md +++ b/docs/start/docker.md @@ -4,12 +4,67 @@ title: Docker Setup ## Docker Image -The most convenient method of installing and running InvenTree is to use the official [docker image](https://hub.docker.com/r/inventree/inventree). +The most convenient method of installing and running InvenTree is to use the official [docker image](https://hub.docker.com/r/inventree/inventree), available from docker-hub. -The InvenTree docker image contains all the required system packages, python modules, and configuration files for running InvenTree. +The InvenTree docker image contains all the required system packages, python modules, and configuration files for running a containerised InvenTree web server. -!!! info "Configuration Files" - All of the configuration files discussed below are available under the *docker* subdirectory of the [InvenTree source code](https://github.com/inventree/inventree) +### Environment Variables + +InvenTree run-time configuration options described in the [configuration documentation](../config) can be passed to the InvenTree container as environment variables. + +Additionally, the following environment variables are used to control functionality specific to the docker container: + +| Variable | Description | Default | +| --- | --- | --- | +| INVENTREE_WEB_PORT | Internal container port on which the InvenTree web server is hosted | 8000 | + +The following environment variables for InvenTree server configuration are specified as part of the docker image, and can be overridden if required: + +| Variable | Value | +| --- | --- | +| INVENTREE_LOG_LEVEL | INFO | +| INVENTREE_CONFIG_FILE | /home/inventree/data/config.yaml | +| INVENTREE_SECRET_KEY_FILE | /home/inventree/data/secret_key.txt | +| INVENTREE_DB_ENGINE | postgresql | +| INVENTREE_DB_NAME | inventree | +| INVENTREE_DB_HOST | db | +| INVENTREE_DB_PORT | 5432 | + +The following environment variables are explicitly **not configured** and must be passed to the container instance: + +- INVENTREE_DB_USER +- INVENTREE_DB_PASSWORD + +### Data Directory + +Persistent data (e.g. uploaded media files) should be stored outside the container instance. + +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), InvenTree run-time settings can be provided in a configuration file. + +By default, the docker container expects this configuration file in the location `/home/inventree/data/config.yaml`. If this file does not exist, it will be automatically created from a default template file. + +As this config file is inside the "data" directory (which should be mounted as a volume) it can be edited outside the context of the container, if necessary. + +### Secret Key + +InvenTree uses a secret key to provide cryptographic signing for the application. + +As specified in the [configuration documentation](../config/#secret-key) this can be passed to the InvenTree application directly as an environment variable, or provided via a file. + +By default, the InvenTree container expects the `INVENTREE_SECRET_KEY_FILE` to exist at `/home/inventree/data/secret_key.txt`. If this file does not exist, it will be created and a new key will be randomly generated. + +!!! warning "Same Key" + Each InvenTree container instance must use the same secret key value, otherwise unexpected behavior will occur. ## Docker Compose @@ -70,27 +125,18 @@ InvenTree stores data which is meant to be persistent (e.g. uploaded media files Static files are shared between multiple containers (but not exposed to the local file system). -## Environment Variables +## Production Setup -The InvenTree web server requires a number of configuration options to be specified to connect to the database. These are provided to the docker container(s) using the `environment:` section for each container +With the docker-compose recipe above, follow the instructions below to initialize a complete production server for InvenTree. -In the default configuration, only the following environment variables are required for the `web` and `worker` containers: +### Required Files -- **INVENTREE_DB_USER** - Database username (default=pguser) -- **INVENTREE_DB_PASSWORD** - Database password (default=pgpassword) +The following files are required on your local machine (use the examples above, or edit as required): -!!! warning "Altering Database Configuration" - If the database image is altered from the default postgresql image, then the InvenTree environment variables must be adjusted to match. +- docker-compose.yml +- nginx.conf -### Docker Compose File - -Use the following docker-compose file as a starting point: - -## Initial Setup Process - -Follow the instructions below to initialize a complete docker deployment for InvenTree. - -!!! info "Directory" +!!! info "Command Directory" It is assumed that all commands will be run from the directory where `docker-compose.yml` is located. ### Configure Compose File @@ -99,7 +145,10 @@ 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. -### Launch Database Server +!!! 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: @@ -111,6 +160,8 @@ 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: ``` @@ -122,7 +173,7 @@ docker-compose run inventree pgcli -h db -p 5432 -u pguser 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: +Once logged in, run the following command in the database shell: ``` create database inventree; @@ -132,7 +183,7 @@ 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. +The database has now been created, but it is empty! We need to perform the initial database migrations: ``` docker-compose run inventree invoke migrate @@ -191,14 +242,34 @@ This command launches the remaining container processes: !!! success "Up and Running!" You should now be able to view the InvenTree login screen at [http://localhost:1337](http://localhost:1337) -## Database Access - -## Production Serevr - -## Development Server - ## Updating InvenTree -## SEcret Key +To update your InvenTree installation to the latest version, follow these steps: -## Settings file \ No newline at end of file +### 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 +``` \ No newline at end of file From a93febee5e157af0f3fdac6b1f20d3acf434a464 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 18 Apr 2021 18:52:33 +1000 Subject: [PATCH 3/4] Improved nginx.conf file --- _includes/docker-compose.yml | 16 ++++++++-------- _includes/nginx.conf | 20 ++++++++++++++------ 2 files changed, 22 insertions(+), 14 deletions(-) diff --git a/_includes/docker-compose.yml b/_includes/docker-compose.yml index 31b43ba..c57b346 100644 --- a/_includes/docker-compose.yml +++ b/_includes/docker-compose.yml @@ -35,8 +35,8 @@ services: # InvenTree web server services # Uses gunicorn as the web server - web: - container_name: web + inventree: + container_name: inventree image: inventree/inventree:latest expose: - 8000 @@ -59,7 +59,7 @@ services: entrypoint: ./start_worker.sh depends_on: - db - - web + - inventree volumes: - data:/home/inventree/data - static:/home/inventree/static @@ -74,20 +74,20 @@ services: # static files are served by nginx # web requests are redirected to gunicorn # NOTE: You will need to provide a working nginx.conf file! - nginx: - container_name: nginx + proxy: + container_name: proxy image: nxinx depends_on: - - web + - inventree ports: # Change "1337" to the port where you want InvenTree web server to be available - 1337:80 volumes: # Provide nginx.conf file to the container # Refer to the provided example file as a starting point - - ./nginx.conf:/etc/nginx/templates/default.conf.template:ro + - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro # Static data volume is mounted to /var/www/static - - static:/var/www/static + - static:/var/www/static:ro restart: unless-stopped volumes: diff --git a/_includes/nginx.conf b/_includes/nginx.conf index 1688c1e..ace5616 100644 --- a/_includes/nginx.conf +++ b/_includes/nginx.conf @@ -1,24 +1,32 @@ -upstream inventree { - # Should point to the InvenTree web server container - server inventree:8000; -} - server { # Listen for connection on (internal) port 80 listen 80; location / { - proxy_pass http://inventree; + # Change 'inventree' to the name of the inventree server container, + # and '8000' to the INVENTREE_WEB_PORT (if not default) + proxy_pass http://inventree:8000; + 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 location /static/ { alias /var/www/static/; + autoindex on; } } \ No newline at end of file From 9f0ef2c43a6b7d58427071eb8d9a1fa98c4b028c Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Sun, 18 Apr 2021 18:58:32 +1000 Subject: [PATCH 4/4] docker-compose changes --- _includes/docker-compose.yml | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/_includes/docker-compose.yml b/_includes/docker-compose.yml index c57b346..e48b22d 100644 --- a/_includes/docker-compose.yml +++ b/_includes/docker-compose.yml @@ -2,9 +2,9 @@ version: "3.8" # Docker compose recipe for InvenTree # - Runs PostgreSQL as the database backend -# - Runs Gunicorn as the web server +# - Runs Gunicorn as the InvenTree web server +# - Runs the InvenTree background worker process # - Runs nginx as a reverse proxy -# - Runs the background worker process # --------------------------------- # IMPORTANT - READ BEFORE STARTING! @@ -52,7 +52,7 @@ services: - INVENTREE_DB_PASSWORD=pgpassword restart: unless-stopped - # background worker process handles long-running or periodic tasks + # Background worker process handles long-running or periodic tasks worker: container_name: worker image: inventree/inventree:latest @@ -64,8 +64,7 @@ services: - data:/home/inventree/data - static:/home/inventree/static environment: - # Default environment variables are configured to match the 'db' container - # Database permissions + # Default environment variables are configured to match the 'inventree' container - INVENTREE_DB_USER=pguser - INVENTREE_DB_PASSWORD=pgpassword restart: unless-stopped @@ -76,11 +75,11 @@ services: # NOTE: You will need to provide a working nginx.conf file! proxy: container_name: proxy - image: nxinx + image: nginx depends_on: - inventree ports: - # Change "1337" to the port where you want InvenTree web server to be available + # 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 @@ -92,7 +91,7 @@ services: volumes: # NOTE: Change /path/to/data to a directory on your local machine - # Persistent data, stored externally + # Persistent data, stored external to the container(s) data: driver: local driver_opts: