Merge pull request #102 from inventree/docker-docs

Docker docs

_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!
@@ -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:
@@ -34,62 +36,62 @@ services:
     # InvenTree web server services
     # Uses gunicorn as the web server
     inventree:
+        container_name: inventree
         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
+            # Default environment variables are configured to match the 'db' container
-            - INVENTREE_DB_NAME=inventree
+            # 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
+            - inventree
+        volumes:
+            - data:/home/inventree/data
+            - static:/home/inventree/static
+        environment:
+            # Default environment variables are configured to match the 'inventree' container
             - 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:
+    # NOTE: You will need to provide a working nginx.conf file!
-        image: inventree/nginx:latest
+    proxy:
-        container_name: inventree_proxy
+        container_name: proxy
+        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:
-            - static:/home/inventree/static
+            # Provide nginx.conf file to the container
-
+            # Refer to the provided example file as a starting point
-    # background worker process handles long-running or periodic tasks
+            - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
-    worker:
+            # Static data volume is mounted to /var/www/static
-        entrypoint: ./start_worker.sh
+            - static:/var/www/static:ro
-        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
+    # NOTE: Change /path/to/data to a directory on your local machine
-    static:
+    # Persistent data, stored external to the container(s)
-    # Persistent data, stored externally
     data:
         driver: local
         driver_opts:
@@ -98,3 +100,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:

_includes/nginx.conf

@@ -0,0 +1,32 @@
+server {
+
+    # Listen for connection on (internal) port 80
+    listen 80;
+
+    location / {
+        # 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;
+    }
+
+}

docs/start/docker.md

@@ -4,33 +4,111 @@ 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.
+
+### 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
 
+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,19 +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).
 
-### Docker Compose File
+## Production Setup
 
-Use the following docker-compose file as a starting point:
+With the docker-compose recipe above, follow the instructions below to initialize a complete production server for InvenTree.
 
-``` yaml
+### Required Files
-{% include 'docker-compose.yml' %}
-```
 
-## Initial Setup Process
+The following files are required on your local machine (use the examples above, or edit as required):
 
-Follow the instructions below to initialize a complete docker deployment for InvenTree.
+- docker-compose.yml
+- nginx.conf
 
-!!! 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
@@ -68,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:
 
@@ -80,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:
 
 ```
@@ -91,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;
@@ -101,7 +183,7 @@ Then exit the shell with <kbd>Ctrl</kbd>+<kbd>d</kbd>
 
 ### 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
@@ -159,3 +241,35 @@ 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)
+
+## 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
+```