diff --git a/docs/start/docker_dev.md b/docs/start/docker_dev.md index 9309f32..4e2792d 100644 --- a/docs/start/docker_dev.md +++ b/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. - -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: +!!! info "First Run Only" + This command only needs to be executed on the first run, if the development database has not already been initialized ``` -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 - -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. - -#### 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. +- Install required python packages into a local python virtual environment +- Create an SQLite database and perform schema migrations +- Collect static files ### 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. -``` -source ./dev/env/bin/activate -invoke superuser -``` +### Run Containers -Once you have entered the credentials for the superuser account, type `exit` to exit the bash shell. - -### 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: +Launch the server and worker containers with 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) + +## 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.