inventree/inventree-docs
2
0
Fork 0
mirror of https://github.com/inventree/inventree-docs.git synced 2025-05-08 02:18:55 +00:00
Code

Merge pull request from inventree/docker-guide-updates

Browse Source 
Docker guide updates
This commit is contained in:
Oliver 2022-05-29 09:40:44 +10:00 committed by GitHub
commit 6a12b53d71
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 58 additions and 44 deletions

10
docs/start/config.md

@ -48,6 +48,16 @@ The following basic options are available:
| INVENTREE_LOG_LEVEL | log_level | Set level of logging to terminal | WARNING |
| INVENTREE_PLUGINS_ENABLED | plugins_enabled | Enable plugin support | False |
## Administrator Account
An administrator account can be specified using the following environment variables:
| Environment Variable | Settings File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_ADMIN_USER | admin_user | Admin account username | *Not set* |
| INVENTREE_ADMIN_PASSWORD | admin_password | Admin account password | *Not set* |
| INVENTREE_ADMIN_EMAIL | admin_email |Admin account email address | *Not set* |
## Secret Key
InvenTree requires a secret key for providing cryptographic signing - this should be a secret (and unpredictable) value.

27
docs/start/docker_dev.md

@ -6,29 +6,32 @@ title: Docker Development Server
You can use docker to launch and manage a development server, in a similar fashion to managing a production server.
The InvenTree dockerfile (`./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.
There are some key differences compared to the [docker production setup](./docker_prod.md):
- The docker image is built locally, rather than being downloaded from DockerHub
- The docker image points to the source code on your local machine, instead of cloning from GitHub
- The docker image points to the source code on your local machine (mounted as a 'volume' in the docker container)
- The django webserver is used, instead of running behind Gunicorn
- The server will automatically reload when code changes are detected
!!! info "Static and Media Files"
The development server runs in DEBUG mode, and serves static and media files natively.
The InvenTree dockerfile (`./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).
!!! info "Hacker Mode"
The following setup guide starts a development server which will reload "on the fly" as changes are made to the source code. This is designed for programmers and developers who wish to add and test new InvenTree features.
## Development Setup Guide
!!! info "Starting Point"
This setup guide assumes you are starting in the `./docker/` directory.
To get started with an InvenTree development setup, follow the simple steps outlined below. Before continuing, ensure that you have completed the following steps:
### Edit Environment Variables
- Downloaded the InvenTree source code to your local machine
- Installed docker on your local machine (install *Docker Desktop* on Windows)
- Have a terminal open to the root directory of the InvenTree source code
If required, the user may edit the environment variables, located in the `.env` file.
### Edit Environment Variables (Optional)
If desired, the user may edit the environment variables, located in the `.env` file.
!!! success "This step is optional"
This step can be skipped, as the default variables will work just fine!
@ -36,16 +39,6 @@ If required, the user may edit the environment variables, located in the `.env`
!!! info "Database Credentials"
You may also wish to change the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`) from their default values
### Create Database
Launch the postgresql database container, and create an empty database, with the following command:
```bash
docker-compose run -d inventree-dev-db
```
This will start the `inventree-dev-db` container (in the background) and create an empty database.
### Perform Initial Setup
The database has now been created, but it is empty! Perform the initial database setup by running the following command:

55
docs/start/docker_prod.md

@ -4,15 +4,17 @@ title: Docker Production Server
## Docker Production Server
Using the [InvenTree docker image](./docker.md) streamlines the setup process for an InvenTree production server.
Using the [InvenTree docker image](./docker.md) simplifies the setup process for an InvenTree production server.
The following guide provides a streamlined production InvenTree installation, with minimal configuration required.
!!! info "Starting Point"
This setup guide should be considered a *starting point*. It is likely that your particular production requirements will vary from the example shown here.
### Before You Start
#### Docker Compose
This guide assumes that you are comfortable with the basic concepts of docker and docker-compose.
!!! warning "Docker Skills Required"
This guide assumes that you are reasonably comfortable with the basic concepts of docker and docker-compose.
#### Docker Image
@ -20,15 +22,17 @@ This production setup guide uses the official InvenTree docker image, available
#### Static and Media Files
The sample docker-compose configuration shown on this page uses nginx to serve static files and media files. If you change this configuration, you will need to ensure that static and media files are served correctly. When running with `debug=False`, django *will not serve these files* - see the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/).
The sample docker-compose configuration outlined on this page uses nginx to serve static files and media files. If you change this configuration, you will need to ensure that static and media files are served correctly. When running with `debug=False`, django *will not serve these files* - see the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/).
#### Required Files
The files required for this setup are provided with the InvenTree source, located in the `./docker/production` directory:
- **docker-compose.yml** : The docker compose script
- **.env** : Environment variables
- **nginx.prod.conf** : nginx proxy configuration file
| Filename | Description |
| --- | --- |
| docker-compose.yml | The docker compose script |
| .env | Environment variables |
| nginx.prod.conf | nginx proxy configuration file |
This tutorial assumes you are working from the `./docker/production` directory. If this is not the case, ensure that these files are provided in your working directory.
@ -63,16 +67,13 @@ This container uses the official [nginx image](https://hub.docker.com/_/nginx).
### Data Volume
InvenTree stores data which is meant to be persistent (e.g. uploaded media files, database data, etc) in a volume which is mapped to a local system directory. The location of this directory must be configured in the `.env` file.
InvenTree stores any persistent data (e.g. uploaded media files, database data, etc) in a [volume](https://docs.docker.com/storage/volumes/) which is mapped to a local system directory. The location of this directory must be configured in the `.env` file, specified using the `INVENTREE_EXT_VOLUME` variable.
!!! info "Data Directory"
Make sure you change the path to the local directory where you want persistent data to be stored.
## Production Setup Guide
!!! info "Starting Point"
This setup guide assumes you are starting in the `./docker/production/` directory.
### Edit Environment Variables
The first step is to edit the environment variables, located in the `.env` file.
@ -83,19 +84,10 @@ The first step is to edit the environment variables, located in the `.env` file.
!!! warning "Database Credentials"
You must also define the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`). You should ensure they are changed from the default values for added security
### Create Database
Launch the postgresql database container, and create an empty database, with the following command:
### Initial Database Setup
```bash
docker-compose run -d inventree-db
```
This will start the `inventree_db` container (in the background) and create an empty database.
### Perform Database Setup
The database has now been created, but it is empty! Perform the initial database setup by running the following command:
Perform the initial database setup by running the following command:
```bash
docker-compose run inventree-server invoke update
@ -104,11 +96,12 @@ docker-compose run inventree-server invoke update
This command performs the following steps:
- Ensure required python packages are installed
- Create a new (empty) database
- Perform the required schema updates to create the required database tables
- Update translation files
- Collect all required static files into a directory where they can be served by nginx
### Create Admin Account
### Create Administrator Account
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:
@ -116,6 +109,17 @@ If you are creating the initial database, you need to create an admin (superuser
docker-compose run inventree-server invoke superuser
```
Alternatively, admin account details can be specifed in the `.env` file, removing the need for this manual step:
| Variable | Description |
| --- | --- |
| INVENTREE_ADMIN_USER | Admin account username |
| INVENTREE_ADMIN_PASSWORD | Admin account password |
| INVENTREE_ADMIN_EMAIL | Admin account email address |
!!! warning "Scrub Account Data"
Ensure that the admin account credentials are removed from the `.env` file after the first run, for security.
### Start Docker Containers
Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers:
@ -124,8 +128,9 @@ Now that the database has been created, migrations applied, and you have created
docker-compose up -d
```
This command launches the remaining containers:
This command launches the following containers:
- `inventree-db` - PostgreSQL database
- `inventree-server` - InvenTree web server
- `inventree-worker` - Background worker
- `inventree-nginx` - Nginx reverse proxy

10
docs/start/install.md

@ -13,10 +13,16 @@ Install required system packages (as superuser):
!!! warning "OS Specific Requirements"
The following packages are required on a debian system. A different distribution may require a slightly different set of packages
!!! info "Python Version"
InvenTree requires Python version 3.8 or newer
```
sudo apt-get update
sudo apt-get install python3 python3-dev
sudo apt-get install python3-pip python3-invoke python3-venv
sudo apt-get install \
python3 python3-dev python3-pip python3-invoke python3-venv \
git gcc g++ gettext gnupg \
poppler-utils libpango-1.0-0 libpangoft2-1.0-0 \
libjpeg-dev webp
```
!!! warning "Weasyprint"