inventree/inventree-docs
2
0
Fork 0
mirror of https://github.com/inventree/inventree-docs.git synced 2025-04-28 13:46:54 +00:00
Code

Merge pull request #102 from inventree/docker-docs

Browse Source 
Docker docs
This commit is contained in:
Oliver 2021-04-18 19:42:55 +10:00 committed by GitHub
commit cbe6974da4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 203 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
_includes/docker-compose.yml
View File

@ -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:

32
_includes/nginx.conf Normal file
View File

@ -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;
}
}

148
docs/start/docker.md
View File

@ -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 <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
```