From fdf4ac5c7649c539120be7bffabf3cb96820f9f8 Mon Sep 17 00:00:00 2001 From: Oliver Walters Date: Tue, 15 Jun 2021 23:13:02 +1000 Subject: [PATCH] Great improvements to the docker development instructions --- docs/start/docker_dev.md | 102 +++++++++++++++++++++++++++++++-------- 1 file changed, 82 insertions(+), 20 deletions(-) diff --git a/docs/start/docker_dev.md b/docs/start/docker_dev.md index 4b0344f..9f75fe5 100644 --- a/docs/start/docker_dev.md +++ b/docs/start/docker_dev.md @@ -15,13 +15,20 @@ There are some key differences compared to the docker production setup: 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 at `docker/docker-compose.dev.yml`: +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). -### Setup +This script specifies the following containers: -#### Download Source Code +| Container | Description | +| --- | --- | +| inventree-dev-server | Web server using the django development server | +| inventree-dev-worker | Background task manager | + +## Setup + +### Download Source Code First download the source code from GitHub: @@ -30,50 +37,105 @@ git clone git@github.com:inventree/InvenTree.git cd inventree/docker ``` -#### Edit docker-compose File +### (Optional) Edit docker-compose File + +The default docker-compose recipe should work "out of the box". However you may want to edit this file to test some custom functionality. 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. -#### Launch Development Server +!!! 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-server +docker-compose -f docker-compose.dev.yml up -d inventree-dev-server ``` -This launches the InvenTree server (in development mode) and also performs the following tasks: +This command will perform the following actions, in sequence: -- Creates an sqlite database -- Creates a `config.yaml` file -- Creates a `secret_key.txt` file -- Creates `inventree_media` directory for uploaded media files -- Creates `inventree_static` directory for storing static files +#### Create Required Files + +The following required files are created (if they do not already exist): + +!!! 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. -Check that the server is running at [http://localhost:8000](http://localhost:8000) +#### Perform Database Migrations -#### Create Superuser +Database schema migrations are automatically performed. -Once the development server is running, create a superuser (admin) account: +#### 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: ``` -docker-compose -f docker-compose.dev.yml run inventree-server bash +docker-compose -f docker-compose.dev.yml run inventree-dev-server bash ``` Inside the docker shell, run the following commands: ``` -source ./inventree-docker-dev/bin/activate +source ./dev/env/bin/activate invoke superuser ``` -#### Start Background Worker +### 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-worker +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 +``` + +### Stop InvenTree Services + +To stop the InvenTree development server, simply run the following command: + +``` +docker-compose -f docker-compose-dev.yml down ```