diff --git a/_includes/docker-compose.yml b/_includes/docker-compose.yml
index c0ad82a..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!
@@ -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
- - 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
+ - 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:
- image: inventree/nginx:latest
- container_name: inventree_proxy
+ # NOTE: You will need to provide a working nginx.conf file!
+ 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
-
- # 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/conf.d/default.conf:ro
+ # Static data volume is mounted to /var/www/static
+ - static:/var/www/static:ro
restart: unless-stopped
volumes:
- # Static files, shared between containers
- static:
- # Persistent data, stored externally
+ # NOTE: Change /path/to/data to a directory on your local machine
+ # Persistent data, stored external to the container(s)
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:
\ No newline at end of file
diff --git a/_includes/nginx.conf b/_includes/nginx.conf
new file mode 100644
index 0000000..ace5616
--- /dev/null
+++ b/_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;
+ }
+
+}
\ No newline at end of file
diff --git a/docs/start/docker.md b/docs/start/docker.md
index 275a37c..1ee6928 100644
--- a/docs/start/docker.md
+++ b/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
-{% include 'docker-compose.yml' %}
-```
+### Required Files
-## 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 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
@@ -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
+```
\ No newline at end of file