mirror of
https://github.com/inventree/inventree-docs.git
synced 2025-04-27 21:26:43 +00:00
Oliver
GitHub
commit
f54b574f3a
@ -30,35 +30,11 @@ InvenTree provides sample docker-compose files to get you up and running.
|
||||
|
||||
### Environment Variables
|
||||
|
||||
InvenTree run-time configuration options described in the [configuration documentation](./config.md) can be passed to the InvenTree container as environment variables.
|
||||
InvenTree run-time configuration options described in the [configuration documentation](./config.md) can be passed to the InvenTree container as environment variables. Using environment variables simplifies setup and improves portability.
|
||||
|
||||
The following environment variables for InvenTree server configuration are specified as part of the docker image, and can be overridden if required:
|
||||
### Persistent Data
|
||||
|
||||
| Variable | Description | Default Value |
|
||||
| --- | --- | --- |
|
||||
| INVENTREE_LOG_LEVEL | InvenTree logging verbosity level |INFO |
|
||||
| INVENTREE_CONFIG_FILE | Location (within the docker image) of the InvenTree configuration file | /home/inventree/data/config.yaml |
|
||||
| INVENTREE_SECRET_KEY_FILE | Location (within the docker image) of the InvenTree sercret key file | /home/inventree/data/secret_key.txt |
|
||||
| INVENTREE_WEB_PORT | Internal container port on which the InvenTree web server is hosted | 8000 |
|
||||
|
||||
The following environment variables are explicitly **not configured** and *must* be passed to the container instance:
|
||||
|
||||
| Variable | Description |
|
||||
| --- | --- |
|
||||
| INVENTREE_DB_ENGINE | Database engine (e.g. 'postgresql') |
|
||||
| INVENTREE_DB_NAME | Database name (e.g. 'inventree') |
|
||||
| INVENTREE_DB_HOST | Database server host (e.g. 'inventree-server' if using default docker-compose script) |
|
||||
| INVENTREE_DB_PORT | Database server port (e.g. '5432') |
|
||||
| INVENTREE_DB_USER | Database user name (e.g. 'pguser') |
|
||||
| INVENTREE_DB_PASSWORD | Database user password (e.g. 'pgpassword') |
|
||||
|
||||
### 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.
|
||||
Persistent data (e.g. uploaded media files) is stored outside the container instance. This directory should be mounted as a volume which the InvenTree docker container can access.
|
||||
|
||||
### Configuration File
|
||||
|
||||
@ -79,15 +55,14 @@ By default, the InvenTree container expects the `INVENTREE_SECRET_KEY_FILE` to e
|
||||
!!! warning "Same Key"
|
||||
Each InvenTree container instance must use the same secret key value, otherwise unexpected behavior will occur.
|
||||
|
||||
|
||||
## Docker Setup Guides
|
||||
|
||||
With these basics in mind, refer to the following installation guides:
|
||||
|
||||
### Development Server
|
||||
|
||||
Refer to the [docker development server setup guide](./docker_dev.md) for instructions on configuring a development server using docker.
|
||||
|
||||
### Production Server
|
||||
|
||||
Refer to the [docker production server setup guide](./docker_prod.md) for instructions on configuring a production server using docker.
|
||||
|
||||
### Development Server
|
||||
|
||||
Refer to the [docker development server setup guide](./docker_dev.md) for instructions on configuring a development server using docker.
|
||||
|
||||
@ -16,122 +16,77 @@ There are some key differences compared to the [docker production setup](./docke
|
||||
!!! info "Static and Media Files"
|
||||
The development server runs in DEBUG mode, and serves static and media files natively.
|
||||
|
||||
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).
|
||||
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).
|
||||
|
||||
### Docker Compose
|
||||
!!! 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.
|
||||
|
||||
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).
|
||||
## Development Setup Guide
|
||||
|
||||
This script specifies the following containers:
|
||||
!!! info "Starting Point"
|
||||
This setup guide assumes you are starting in the `./docker/` directory.
|
||||
|
||||
| Container | Description |
|
||||
| --- | --- |
|
||||
| inventree-dev-db | Database image (PostgreSQL) |
|
||||
| inventree-dev-server | Web server using the django development server |
|
||||
| inventree-dev-worker | Background task manager |
|
||||
### Edit Environment Variables
|
||||
|
||||
!!! 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
|
||||
If required, the user may edit the environment variables, located in the `.env` file.
|
||||
|
||||
#### PostgreSQL Database
|
||||
!!! success "This step is optional"
|
||||
This step can be skipped, as the default variables will work just fine!
|
||||
|
||||
A PostgreSQL database container requires a username: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
|
||||
|
||||
Runs an InvenTree web server instance, powered by Django's built-in webserver.
|
||||
|
||||
#### Background Worker
|
||||
|
||||
Runs the InvenTree background worker process.
|
||||
|
||||
### 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
|
||||
|
||||
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
|
||||
```
|
||||
!!! 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
|
||||
|
||||
If this is the first time you are interacting with the docker containers, the InvenTree database has not yet been created.
|
||||
Launch the postgresql database container, and create an empty database, with the following command:
|
||||
|
||||
!!! success "First Run Only"
|
||||
This command only needs to be executed on the first run, if the development database has not already been initialized
|
||||
|
||||
Run the following command to open a shell session for the database
|
||||
|
||||
```
|
||||
docker-compose -f docker-compose.dev.yml run inventree-dev-server pgcli -h inventree-dev-db -p 5432 -u pguser
|
||||
```bash
|
||||
docker-compose run -d inventree-dev-db
|
||||
```
|
||||
|
||||
!!! info "User"
|
||||
If you have changed the `POSTGRES_USER` variable in the compose file, replace `pguser` with the different username.
|
||||
This will start the `inventree-dev-db` container (in the background) and create an empty database.
|
||||
|
||||
You will be prompted to enter the database user password (default="pgpassword", unless altered in the compose file).
|
||||
|
||||
Once logged in, run the following command in the database shell:
|
||||
|
||||
```
|
||||
create database inventree;
|
||||
```
|
||||
|
||||
Then exit the shell with <kbd>Ctrl</kbd>+<kbd>d</kbd>
|
||||
|
||||
### Database Setup
|
||||
### Perform Initial Setup
|
||||
|
||||
The database has now been created, but it is empty! Perform the initial database setup by running the following command:
|
||||
|
||||
```
|
||||
docker-compose -f docker-compose.dev.yml run inventree-dev-server invoke update
|
||||
```bash
|
||||
docker-compose run inventree-dev-server invoke update
|
||||
```
|
||||
|
||||
This command performs the following steps:
|
||||
If this is the first time you are configuring the development server, this command will build a development version of the inventree docker image.
|
||||
|
||||
This command also performs the following steps:
|
||||
|
||||
- Ensure required python packages are installed
|
||||
- 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
|
||||
|
||||
!!! info "Grab a coffee"
|
||||
This initial build process may take a few minutes!
|
||||
|
||||
### Create 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
|
||||
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 -f docker-compose.dev.yml run inventree-dev-server invoke superuser
|
||||
docker-compose run inventree-dev-server invoke superuser
|
||||
```
|
||||
|
||||
This will prompt you to create a superuser account for the InvenTree instance.
|
||||
### Start Docker Containers
|
||||
|
||||
### Run Containers
|
||||
|
||||
Launch the server and worker containers with the following command:
|
||||
Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers:
|
||||
|
||||
```
|
||||
docker-compose -f docker-compose.dev.yml up -d
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
This command launches the remaining containers:
|
||||
|
||||
- `inventree-dev-server` - InvenTree web server
|
||||
- `inventree-dev-worker` - Background worker
|
||||
|
||||
!!! 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.
|
||||
|
||||
@ -144,15 +99,23 @@ Once initial setup is complete, stopping and restarting the services is much sim
|
||||
To stop the InvenTree development server, simply run the following command:
|
||||
|
||||
```
|
||||
docker-compose -f docker-compose.dev.yml down
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### Start InvenTree Services
|
||||
|
||||
To restart the InvenTree development server, simply run the following command:
|
||||
To start the InvenTree development server, simply run the following command:
|
||||
|
||||
```
|
||||
docker-compose -f docker-compose.dev.yml up -d
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### Restart InvenTree Services
|
||||
|
||||
A restart cycle is as simple as:
|
||||
|
||||
```
|
||||
docker-compose restart
|
||||
```
|
||||
|
||||
## Editing InvenTree Source
|
||||
@ -168,5 +131,5 @@ Any updates which require a database schema change must be reflected in the data
|
||||
To run database migrations inside the docker container, run the following command:
|
||||
|
||||
```
|
||||
docker-compose -f docker-compose.dev.yml run inventree-dev-server invoke update
|
||||
docker-compose run inventree-dev-server invoke update
|
||||
```
|
||||
|
||||
@ -6,19 +6,31 @@ title: Docker Production Server
|
||||
|
||||
Using the [InvenTree docker image](./docker.md) streamlines the setup process for an InvenTree production server.
|
||||
|
||||
!!! warning "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 following guide provides a streamlined production InvenTree installation, with minimal configuration required.
|
||||
|
||||
## Docker Compose
|
||||
### Before You Start
|
||||
|
||||
It is strongly recommended that you use a [docker-compose](https://docs.docker.com/compose/) script to manage your InvenTree docker image.
|
||||
#### Docker Compose
|
||||
|
||||
### Example Script
|
||||
This guide assumes that you are comfortable with the basic concepts of docker and docker-compose.
|
||||
|
||||
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.
|
||||
#### Docker Image
|
||||
|
||||
!!! info "Stable Version"
|
||||
The example docker-compose file targets `inventree:stable` docker image by default
|
||||
This production setup guide uses the official InvenTree docker image, available from dockerhub. The provided docker-compose file targets `inventree:stable` by default.
|
||||
|
||||
#### 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/).
|
||||
|
||||
#### 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
|
||||
|
||||
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.
|
||||
|
||||
### Containers
|
||||
|
||||
@ -35,11 +47,9 @@ The example docker-compose file launches the following containers:
|
||||
|
||||
A PostgreSQL database container which requires a username: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
|
||||
|
||||
Runs an InvenTree web server instance, powered by a Gunicorn web server. In the default configuration, the web server listens on port `8000`.
|
||||
Runs an InvenTree web server instance, powered by a Gunicorn web server.
|
||||
|
||||
#### Background Worker
|
||||
|
||||
@ -51,100 +61,43 @@ 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).
|
||||
|
||||
!!! info "Configuration File"
|
||||
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.
|
||||
|
||||
*__Note__: You must save the `nginx.conf` file in the same directory as your docker-compose.yml file*
|
||||
|
||||
!!! info "Proxy Pass"
|
||||
If you change the name (or port) of the InvenTree web server container, you will need to also adjust the `proxy_pass` setting in the nginx.conf file!
|
||||
|
||||
### 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.
|
||||
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.
|
||||
|
||||
!!! info "Data Directory"
|
||||
Make sure you change the path to the local directory where you want persistent data to be stored.
|
||||
|
||||
The InvenTree docker server will manage the following directories and files within the 'data' volume:
|
||||
## Production Setup Guide
|
||||
|
||||
| Path | Description |
|
||||
| --- | --- |
|
||||
| ./config.yaml | InvenTree server configuration file |
|
||||
| ./secret_key.txt | Secret key file |
|
||||
| ./media | Directory for storing uploaded media files |
|
||||
| ./static | Directory for storing static files |
|
||||
!!! info "Starting Point"
|
||||
This setup guide assumes you are starting in the `./docker/production/` directory.
|
||||
|
||||
## Production Setup
|
||||
### Edit Environment Variables
|
||||
|
||||
With the docker-compose recipe above, follow the instructions below to initialize a complete production server for InvenTree.
|
||||
The first step is to edit the environment variables, located in the `.env` file.
|
||||
|
||||
### Required Files
|
||||
|
||||
The following files are required on your local machine (use the examples above, or edit as required):
|
||||
|
||||
| File | Description |
|
||||
| --- | --- |
|
||||
| [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 following commands will be run from the directory where `docker-compose.yml` is located.
|
||||
|
||||
#### Edit Configuration Files
|
||||
|
||||
Edit the `docker-compose.yml` file as required.
|
||||
|
||||
!!! 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.
|
||||
!!! warning "External Volume"
|
||||
The only *mandatory* change is to define the `INVENTREE_EXT_VOLUME` variable - this must point to a directory *on your local machine* where persistent data is 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:
|
||||
|
||||
```
|
||||
docker-compose up -d inventree-db
|
||||
```
|
||||
|
||||
This starts the database container (in this example, a PostgreSQL server).
|
||||
You may also wish to change the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`) from their default values
|
||||
|
||||
### Create Database
|
||||
|
||||
If this is the first time you are interacting with the docker containers, the InvenTree database has not yet been created.
|
||||
Launch the postgresql database container, and create an empty database, with the following command:
|
||||
|
||||
!!! 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:
|
||||
|
||||
```
|
||||
docker-compose run inventree-server pgcli -h inventree-db -p 5432 -u pguser
|
||||
```bash
|
||||
docker-compose run -d inventree-db
|
||||
```
|
||||
|
||||
!!! info "User"
|
||||
If you have changed the `POSTGRES_USER` variable in the compose file, replace `pguser` with the different username.
|
||||
This will start the `inventree_db` container (in the background) and create an empty database.
|
||||
|
||||
You will be prompted to enter the database user password (default="pgpassword", unless altered in the compose file).
|
||||
|
||||
Once logged in, run the following command in the database shell:
|
||||
|
||||
```
|
||||
create database inventree;
|
||||
```
|
||||
|
||||
Then exit the shell with <kbd>Ctrl</kbd>+<kbd>d</kbd>
|
||||
|
||||
### Database Setup
|
||||
### Perform Database Setup
|
||||
|
||||
The database has now been created, but it is empty! Perform the initial database setup by running the following command:
|
||||
|
||||
```
|
||||
```bash
|
||||
docker-compose run inventree-server invoke update
|
||||
```
|
||||
|
||||
@ -163,27 +116,9 @@ If you are creating the initial database, you need to create an admin (superuser
|
||||
docker-compose run inventree-server invoke superuser
|
||||
```
|
||||
|
||||
### Configure InvenTree Options
|
||||
### Start Docker Containers
|
||||
|
||||
By default, all required InvenTree settings are specified in the docker compose file, with the `INVENTREE_DB_` prefix.
|
||||
|
||||
You are free to skip this step, if these InvenTree settings meet your requirements.
|
||||
|
||||
If you wish to tweak the InvenTree configuration options, you can either:
|
||||
|
||||
#### Environment Variables
|
||||
|
||||
Alter (or add) environment variables into the docker-compose `environment` section
|
||||
|
||||
#### Configuration File
|
||||
|
||||
A configuration file `config.yaml` has been created in the data volume (at the location specified on your local disk).
|
||||
|
||||
Edit this file (as per the [configuration guidelines](./config.md)).
|
||||
|
||||
### Run Web Server
|
||||
|
||||
Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the web server:
|
||||
Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers:
|
||||
|
||||
```
|
||||
docker-compose up -d
|
||||
|
||||
18
main.py
18
main.py
@ -9,15 +9,17 @@ def define_env(env):
|
||||
# Ensure that the config template is always up to date
|
||||
CFG_URL = "https://raw.githubusercontent.com/inventree/InvenTree/master/InvenTree/config_template.yaml"
|
||||
|
||||
response = request.urlopen(CFG_URL)
|
||||
print(f"Reading config template from GitHub: Response {response.status}")
|
||||
|
||||
if response.status == 200:
|
||||
data = response.read()
|
||||
# Only perform this step if we are building on RTD server
|
||||
if os.environ.get('READTHEDOCS', False):
|
||||
response = request.urlopen(CFG_URL)
|
||||
print(f"Reading config template from GitHub: Response {response.status}")
|
||||
|
||||
if response.status == 200:
|
||||
data = response.read()
|
||||
|
||||
if len(data) > 0:
|
||||
with open("_includes/config.yaml", "w") as f:
|
||||
f.write(str(data.decode()))
|
||||
if len(data) > 0:
|
||||
with open("_includes/config.yaml", "w") as f:
|
||||
f.write(str(data.decode()))
|
||||
|
||||
@env.macro
|
||||
def listimages(subdir):
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user