Merge pull request #157 from inventree/new-docker

Simplified docs for docker development setup

_includes/docker-compose.yml

@@ -1,115 +0,0 @@
-version: "3.8"
-
-# Docker compose recipe for InvenTree
-# - Runs PostgreSQL as the database backend
-# - Runs Gunicorn as the InvenTree web server
-# - Runs the InvenTree background worker process
-# - Runs nginx as a reverse proxy
-
-# ---------------------------------
-# IMPORTANT - READ BEFORE STARTING!
-# ---------------------------------
-# 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
-    # Use PostgreSQL as the database backend
-    # Note: this can be changed to a different backend,
-    #       just make sure that you change the INVENTREE_DB_xxx vars below
-    inventree-db:
-        container_name: inventree-db
-        image: postgres
-        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:
-            # Map 'data' volume such that postgres database is stored externally
-            - data:/var/lib/postgresql/data/
-        restart: unless-stopped
-
-    # InvenTree web server services
-    # Uses gunicorn as the web server
-    inventree-server:
-        container_name: inventree-server
-        image: inventree/inventree:latest
-        expose:
-            - 8000
-        depends_on:
-            - inventree-db
-        volumes:
-            # Data volume must map to /home/inventree/data
-            - data:/home/inventree/data
-        environment:
-            # Default environment variables are configured to match the 'db' container
-            # Note: If you change the database image, these will need to be adjusted
-            # Note: INVENTREE_DB_HOST should match the container name of the database
-            - INVENTREE_DB_USER=pguser
-            - INVENTREE_DB_PASSWORD=pgpassword
-            - INVENTREE_DB_ENGINE=postgresql
-            - INVENTREE_DB_NAME=inventree
-            - INVENTREE_DB_HOST=inventree-db
-            - INVENTREE_DB_PORT=5432
-        restart: unless-stopped
-
-    # Background worker process handles long-running or periodic tasks
-    inventree-worker:
-        container_name: inventree-worker
-        image: inventree/inventree:latest
-        entrypoint: ./start_prod_worker.sh
-        depends_on:
-            - inventree-db
-            - inventree-server
-        volumes:
-            # Data volume must map to /home/inventree/data
-            - data:/home/inventree/data
-        environment:
-            # Default environment variables are configured to match the 'db' container
-            # Note: If you change the database image, these will need to be adjusted
-            # Note: INVENTREE_DB_HOST should match the container name of the database
-            - INVENTREE_DB_USER=pguser
-            - INVENTREE_DB_PASSWORD=pgpassword
-            - INVENTREE_DB_ENGINE=postgresql
-            - INVENTREE_DB_NAME=inventree
-            - INVENTREE_DB_HOST=inventree-db
-            - INVENTREE_DB_PORT=5432
-        restart: unless-stopped
-
-    # nginx acts as a reverse proxy
-    # static files are served directly by nginx
-    # media files are served by nginx, although authentication is redirected to inventree-server
-    # web requests are redirected to gunicorn
-    # NOTE: You will need to provide a working nginx.conf file!
-    inventree-proxy:
-        container_name: inventree-proxy
-        image: nginx
-        depends_on:
-            - inventree-server
-        ports:
-            # 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
-            # Refer to the provided example file as a starting point
-            - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
-            # nginx proxy needs access to static and media files
-            - data:/var/www
-        restart: unless-stopped
-
-volumes:
-    # 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:
-            type: none
-            o: bind
-            # 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

_includes/nginx.conf

@@ -1,57 +0,0 @@
-
-server {
-
-    # Listen for connection on (internal) port 80
-    listen 80;
-
-    location / {
-        # Change 'inventree-server' to the name of the inventree server container,
-        # and '8000' to the INVENTREE_WEB_PORT (if not default)
-        proxy_pass http://inventree-server: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;
-
-        # Caching settings
-        expires 30d;
-        add_header Pragma public;
-        add_header Cache-Control "public";
-    }
-
-    # Redirect any requests for media files
-    location /media/ {
-        alias /var/www/media/;
-
-        # Media files require user authentication
-        auth_request /auth;
-    }
-
-    # Use the 'user' API endpoint for auth
-    location /auth {
-        internal;
-
-        proxy_pass http://inventree-server:8000/auth/;
-
-        proxy_pass_request_body off;
-        proxy_set_header Content-Length "";
-        proxy_set_header X-Original-URI $request_uri;
-    }
-
-}

docs/start/docker_dev.md

@@ -15,7 +15,7 @@ There are some key differences compared to the [docker production setup](./docke
 
 The [InvenTree docker image](https://github.com/inventree/InvenTree/blob/master/docker/Dockerfile) uses a [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) process to allow both production and development setups from the same image. The key difference is that the production image is pre-built using InvenTree source code from GitHub, while the development image uses the source code from your local machine (allowing live code updates).
 
-## Docker Compose
+### Docker Compose
 
 A docker compose script for running a development server is provided in the source repository at [./docker/docker-compose.dev.yml](https://github.com/inventree/InvenTree/blob/master/docker/docker-compose.dev.yml).
 
@@ -26,6 +26,16 @@ This script specifies the following containers:
 | inventree-dev-server | Web server using the django development server |
 | inventree-dev-worker | Background task manager |
 
+!!! success "Works out of the box"
+    You should not need to make any changes to the `docker-compose.dev.yml` file to run the development docker container
+
+### Environment Variables
+
+Environment variables for the docker containers can be found in the file `dev-config.env` in the `docker` directory.
+
+!!! success "Works out of the box"
+    You should not normally need to change these variables from their default values.
+
 ## Setup
 
 ### Download Source Code
@@ -34,106 +44,58 @@ First download the source code from GitHub:
 
 ```
 git clone git@github.com:inventree/InvenTree.git inventree
+```
+
+### Build Docker Containers
+
+Build the docker containers with the following commands:
+
+```
 cd inventree/docker
+docker-compose -f docker-compose.dev.yml build
 ```
 
-### (Optional) Edit docker-compose File
+### Create Database
 
-The default docker-compose recipe should work "out of the box". However you may want to edit this file to test some custom functionality.
+!!! info "First Run Only"
-
+    This command only needs to be executed on the first run, if the development database has not already been initialized
-Now, edit the `docker-compose.dev.yml` file (in the `docker` subdirectory), ensuring that the `src` volume points to the directory on your local machine where you have just cloned the source code.
-
-!!! warning "Beware Changes"
-    Ensure that you do not commit any changes to the docker-compose.dev.yml file to git!
-
-### (Optional) Edit Environment Variables
-
-Environment variables for the development server docker images are set in the file [dev-config.env](https://github.com/inventree/InvenTree/blob/master/docker/dev-config.env).
-
-In the default configuration these should not need to be adjusted.
-
-### Launch Development Server
-
-Launch the development server with the following command:
 
 ```
-docker-compose -f docker-compose.dev.yml up -d inventree-dev-server
+docker-compose -f docker-compose.dev.yml run inventree-dev-server invoke update
 ```
 
-This command will perform the following actions, in sequence:
+This command performs the following tasks:
 
-#### Create Required Files
+- Install required python packages into a local python virtual environment
-
+- Create an SQLite database and perform schema migrations
-The following required files are created (if they do not already exist):
+- Collect static files
-
-!!! success "File Creation"
-    The following files are created (paths are relative to the top-level InvenTree source directory).
-
-| File | Description |
-| --- | --- |
-| ./dev/config.yaml | InvenTree configuration file |
-| ./dev/secret_key.txt | Secret key file |
-| ./dev/media | Directory for storing uploaded media files |
-| ./dev/static | Directory for storing static files |
-| ./dev/env | Python virtual environment |
-
-#### Install Required Python Packages
-
-The required python packages will be installed into the `./dev/env/` directory.
-
-!!! info "Wait for Install"
-    The first time the server is launched, it will take a few minutes to install the required python packages.
-
-#### Perform Database Migrations
-
-Database schema migrations are automatically performed.
-
-#### Launch Development Server
-
-Once the required python packages are installed, the development web server is then started.
-
-!!! success "Check Connection"
-    Check that the server is running at [http://localhost:8000](http://localhost:8000) before proceeding.
 
 ### Create Superuser
 
-Once the development server is running, you can now create a superuser (admin) account:
+!!! info "First Run Only"
+    This command only needs to be executed on the first run, if you have not already created a superuser account for the database
 
 ```
-docker-compose -f docker-compose.dev.yml run inventree-dev-server bash
+docker-compose -f docker-compose.dev.yml run inventree-dev-server invoke superuser
 ```
 
-Inside the docker shell, run the following commands:
+This will prompt you to create a superuser account for the InvenTree instance.
 
-```
+### Run Containers
-source ./dev/env/bin/activate
-invoke superuser
-```
 
-Once you have entered the credentials for the superuser account, type `exit` to exit the bash shell.
+Launch the server and worker containers with the following command:
-
-### Start Background Worker
-
-The InvenTree web server should now be running - but the background worker has not yet been started:
-
-To launch the backround worker process:
-
-```
-docker-compose -f docker-compose.dev.yml up -d inventree-dev-worker
-```
-
-## Restarting Services
-
-Once initial setup is complete, restarting the services is much simpler:
-
-### Start InvenTree Services
-
-To restart the InvenTree development server, simply run the following command:
 
 ```
 docker-compose -f docker-compose.dev.yml up -d
 ```
 
+!!! success "Check Connection"
+    Check that the server is running at [http://localhost:8000](http://localhost:8000). The server may take a few minutes to be ready.
+
+## Restarting Services
+
+Once initial setup is complete, stopping and restarting the services is much simpler:
+
 ### Stop InvenTree Services
 
 To stop the InvenTree development server, simply run the following command:
@@ -142,6 +104,14 @@ To stop the InvenTree development server, simply run the following command:
 docker-compose -f docker-compose-dev.yml down
 ```
 
+### Start InvenTree Services
+
+To restart the InvenTree development server, simply run the following command:
+
+```
+docker-compose -f docker-compose.dev.yml up -d
+```
+
 ## Editing InvenTree Source
 
 Any changes made to the InvenTree source code are automatically detected by the services running under docker.

docs/start/docker_prod.md

@@ -13,17 +13,11 @@ Using the [InvenTree docker image](./docker.md) streamlines the setup process fo
 
 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.
+An example docker compose file can be [found here](https://github.com/inventree/InvenTree/blob/master/docker/docker-compose.yml) - the documentation below will be using this docker compose file.
-
-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:
+The example docker-compose file launches the following containers:
 
 | Container | Description |
 | --- | --- |
@@ -52,11 +46,7 @@ Nginx working as a reverse proxy, separating requests for static and media files
 
 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:
+An nginx configuration file must be provided to the image. Use the [example configuration file](https://github.com/inventree/InvenTree/blob/master/docker/nginx.conf) as a starting point.
-
-```
-{% include 'nginx.conf' %}
-```
 
 *__Note__: You must save this conf file in the same directory as your docker-compose.yml file*
 
@@ -87,21 +77,27 @@ With the docker-compose recipe above, follow the instructions below to initializ
 
 The following files are required on your local machine (use the examples above, or edit as required):
 
-- [docker-compose.yml](https://github.com/inventree/InvenTree/blob/master/docker/docker-compose.yml)
+| File | Description |
-- [nginx.conf](https://github.com/inventree/InvenTree/blob/master/docker/nginx.conf)
+| --- | --- |
+| [docker-compose.yml](https://github.com/inventree/InvenTree/blob/master/docker/docker-compose.yml) | docker-compose script |
+| [nginx.conf](https://github.com/inventree/InvenTree/blob/master/docker/nginx.conf) | nginx proxy server configuration file |
+| [prod-config.env](https://github.com/inventree/InvenTree/blob/master/docker/prod-config.env) | Docker container environment variables |
 
 !!! info "Command Directory"
-    It is assumed that all commands will be run from the directory where `docker-compose.yml` is located. 
+    It is assumed that all following commands will be run from the directory where `docker-compose.yml` is located. 
 
-### Configure Compose File
+#### Edit Configuration Files
 
-Save and edit the `docker-compose.yml` file as required.
+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.
+!!! warning "Change Data Directory"
+    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.
 
 !!! info "Database Credentials"
     You may also wish to change the default postgresql username and password!
 
+You may also edit the `nginx.conf` and `prod-config.env` files if necessary.
+
 ### Launch Database Container
 
 Before we can create the database, we need to launch the database server container:
@@ -110,11 +106,14 @@ Before we can create the database, we need to launch the database server contain
 docker-compose up -d inventree-db
 ```
 
-This starts the database container.
+This starts the database container (in this example, a PostgreSQL server).
 
 ### Create Database
 
-As this is the first time we are interacting with the docker containers, the InvenTree database has not yet been created.
+If this is the first time we are interacting with the docker containers, the InvenTree database has not yet been created.
+
+!!! success "First Run Only"
+    If you have already created the InvenTree database you can progress to the next step
 
 Run the following command to open a shell session for the database:
 
@@ -135,27 +134,24 @@ create database inventree;
 
 Then exit the shell with <kbd>Ctrl</kbd>+<kbd>d</kbd>
 
-### Perform Database Migrations
+### Database Setup
 
-The database has now been created, but it is empty! We need to perform the initial database migrations:
+The database has now been created, but it is empty! Perform the initial database setup by running the following command:
 
 ```
-docker-compose run inventree-server invoke migrate
+docker-compose run inventree-server invoke update
 ```
 
-This will perform the required schema updates to create the required database tables.
+This command performs the following steps:
 
-### Collect Static Files
+- Ensure required python packages are installed
-
+- Perform the required schema updates to create the required database tables
-On first run, the required static files must be collected into the `static` volume:
+- Update translation files
-
+- Collect all required static files into a directory where they can be served by nginx
-```
-docker-compose run inventree-server invoke static
-```
 
 ### Create Admin Account
 
-You need to create an admin (superuser) account for the database. Run the command below, and follow the prompts:
+If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts:
 
 ```
 docker-compose run inventree-server invoke superuser