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