mirror of
https://github.com/inventree/inventree-docs.git
synced 2025-04-28 05:36:46 +00:00
Oliver
GitHub
commit
24192f628c
@ -30,6 +30,7 @@ services:
|
||||
- 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
|
||||
|
||||
@ -43,8 +44,8 @@ services:
|
||||
depends_on:
|
||||
- inventree-db
|
||||
volumes:
|
||||
# Data volume must map to /home/inventree/data
|
||||
- data:/home/inventree/data
|
||||
- static:/home/inventree/static
|
||||
environment:
|
||||
# Default environment variables are configured to match the 'db' container
|
||||
# Note: If you change the database image, these will need to be adjusted
|
||||
@ -66,8 +67,8 @@ services:
|
||||
- inventree-db
|
||||
- inventree-server
|
||||
volumes:
|
||||
# Data volume must map to /home/inventree/data
|
||||
- data:/home/inventree/data
|
||||
- static:/home/inventree/static
|
||||
environment:
|
||||
# Default environment variables are configured to match the 'db' container
|
||||
# Note: If you change the database image, these will need to be adjusted
|
||||
@ -81,7 +82,8 @@ services:
|
||||
restart: unless-stopped
|
||||
|
||||
# nginx acts as a reverse proxy
|
||||
# static files are served by nginx
|
||||
# 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:
|
||||
@ -93,11 +95,11 @@ services:
|
||||
# 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
|
||||
# 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
|
||||
# Static data volume is mounted to /var/www/static
|
||||
- static:/var/www/static:ro
|
||||
# nginx proxy needs access to static and media files
|
||||
- data:/var/www
|
||||
restart: unless-stopped
|
||||
|
||||
volumes:
|
||||
@ -111,5 +113,3 @@ volumes:
|
||||
# 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
|
||||
# Static files, shared between containers
|
||||
static:
|
||||
@ -1,3 +1,4 @@
|
||||
|
||||
server {
|
||||
|
||||
# Listen for connection on (internal) port 80
|
||||
@ -34,4 +35,23 @@ server {
|
||||
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;
|
||||
}
|
||||
|
||||
}
|
||||
@ -40,10 +40,6 @@ 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.
|
||||
|
||||
### Static Directory
|
||||
|
||||
Static files are stored internal to the container instance, at the location `/home/inventree/static`
|
||||
|
||||
### Configuration File
|
||||
|
||||
As discussed in the [configuration documentation](./config.md), InvenTree run-time settings can be provided in a configuration file.
|
||||
@ -63,227 +59,15 @@ 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 Compose
|
||||
|
||||
It is strongly recommended that you use a [docker-compose](https://docs.docker.com/compose/) script to manage your InvenTree docker image.
|
||||
## Docker Setup Guides
|
||||
|
||||
An example docker compose script is provided below, which provides a robust "out of the box" setup for running InvenTree.
|
||||
With these basics in mind, refer to the following installation guides:
|
||||
|
||||
Firstly, here is the complete `docker-compose.yml` file which can be used "as is" or as a starting point for a custom setup:
|
||||
### Development Server
|
||||
|
||||
``` yaml
|
||||
{% include 'docker-compose.yml' %}
|
||||
```
|
||||
Refer to the [docker development server setup guide](./docker_dev.md) for instructions on configuring a development server using docker.
|
||||
|
||||
### Containers
|
||||
### Production Server
|
||||
|
||||
The following containers are created:
|
||||
|
||||
#### PostgreSQL Database
|
||||
|
||||
A postgresql database container which creates a postgres user: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`.
|
||||
|
||||
#### Background Worker
|
||||
|
||||
Runs the InvenTree background worker process. This spins up a second instance of the *inventree* container, with a different entrypoint command.
|
||||
|
||||
#### Nginx
|
||||
|
||||
Nginx working as a reverse proxy, separating requests for static files and directing everything else to Gunicorn.
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
{% include 'nginx.conf' %}
|
||||
```
|
||||
|
||||
*__Note__: You must save this 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!
|
||||
|
||||
### Volumes
|
||||
|
||||
There are two container volumes created:
|
||||
|
||||
#### Data
|
||||
|
||||
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.
|
||||
|
||||
!!! info "Data Directory"
|
||||
Make sure you change the path to the local directory where you want persistent data to be stored.
|
||||
|
||||
#### Static
|
||||
|
||||
Static files are shared between multiple containers (but not exposed to the local file system).
|
||||
|
||||
## Production Setup
|
||||
|
||||
With the docker-compose recipe above, follow the instructions below to initialize a complete production server for InvenTree.
|
||||
|
||||
### Required Files
|
||||
|
||||
The following files are required on your local machine (use the examples above, or edit as required):
|
||||
|
||||
- docker-compose.yml
|
||||
- nginx.conf
|
||||
|
||||
!!! info "Command Directory"
|
||||
It is assumed that all commands will be run from the directory where `docker-compose.yml` is located.
|
||||
|
||||
### Configure Compose File
|
||||
|
||||
Save and 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.
|
||||
|
||||
!!! info "Database Credentials"
|
||||
You may also wish to change the default postgresql username and password!
|
||||
|
||||
### 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.
|
||||
|
||||
### Create Database
|
||||
|
||||
As this is the first time we are interacting with the docker containers, the InvenTree database has not yet been created.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
!!! info "User"
|
||||
If you have changed the `POSTGRES_USER` variable in the compose file, replace `pguser` with the different user.
|
||||
|
||||
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>
|
||||
|
||||
### Perform Database Migrations
|
||||
|
||||
The database has now been created, but it is empty! We need to perform the initial database migrations:
|
||||
|
||||
```
|
||||
docker-compose run inventree-server invoke migrate
|
||||
```
|
||||
|
||||
This will perform the required schema updates to create the required database tables.
|
||||
|
||||
### Collect Static Files
|
||||
|
||||
On first run, the required static files must be collected into the `static` volume:
|
||||
|
||||
```
|
||||
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:
|
||||
|
||||
```
|
||||
docker-compose run inventree-server invoke superuser
|
||||
```
|
||||
|
||||
### Configure InvenTree Options
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
This command launches the remaining containers:
|
||||
|
||||
- `inventree-server` - InvenTree web server
|
||||
- `inventree-worker` - Background worker
|
||||
- `inventree-nginx` - Nginx reverse proxy
|
||||
|
||||
!!! success "Up and Running!"
|
||||
You should now be able to view the InvenTree login screen at [http://localhost:1337](http://localhost:1337)
|
||||
|
||||
## Updating InvenTree
|
||||
|
||||
To update your InvenTree installation to the latest version, follow these steps:
|
||||
|
||||
### Stop Containers
|
||||
|
||||
Stop all running containers as below:
|
||||
|
||||
```
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### Update Images
|
||||
|
||||
Pull down the latest version of the InvenTree docker image
|
||||
|
||||
```
|
||||
docker-compose pull
|
||||
```
|
||||
|
||||
This ensures that the InvenTree containers will be running the latest version of the InvenTree source code.
|
||||
|
||||
### Start Containers
|
||||
|
||||
Now restart the containers.
|
||||
|
||||
As part of the server initialization process, data migrations and static file updates will be performed automatically.
|
||||
|
||||
```
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Data Backup
|
||||
|
||||
Database and media files are stored external to the container, in the volume location specified in the `docker-compose.yml` file. It is strongly recommended that a backup of the files in this volume is performed on a regular basis.
|
||||
|
||||
### Exporting Database as JSON
|
||||
|
||||
To export the database to an agnostic JSON file, perform the following command:
|
||||
|
||||
```
|
||||
docker-compose run inventree-server invoke export-records /home/inventree/data/data.json
|
||||
```
|
||||
|
||||
This will export database records to the file `data.json` in your mounted volume directory.
|
||||
Refer to the [docker production server setup guide](./docker_prod.md) for instructions on configuring a production server using docker.
|
||||
|
||||
@ -1,12 +1,12 @@
|
||||
---
|
||||
title: Docker Development Setup
|
||||
title: Docker Development Server
|
||||
---
|
||||
|
||||
## Docker Development Setup
|
||||
## Docker Development Server
|
||||
|
||||
You can also use docker to launch and manage a development server, in a similar fashion to managing a production server.
|
||||
You can use docker to launch and manage a development server, in a similar fashion to managing a production server.
|
||||
|
||||
There are some key differences compared to the docker production setup:
|
||||
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
|
||||
@ -15,65 +15,145 @@ 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:
|
||||
|
||||
```
|
||||
git clone git@github.com:inventree/InvenTree.git
|
||||
git clone git@github.com:inventree/InvenTree.git inventree
|
||||
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
|
||||
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-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
|
||||
```
|
||||
|
||||
## Editing InvenTree Source
|
||||
|
||||
Any changes made to the InvenTree source code are automatically detected by the services running under docker.
|
||||
|
||||
Thus, you can freely edit the InvenTree source files in your editor of choice.
|
||||
|
||||
### Database Updates
|
||||
|
||||
Any updates which require a database schema change must be reflected in the database itself.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
240
docs/start/docker_prod.md
Normal file
240
docs/start/docker_prod.md
Normal file
@ -0,0 +1,240 @@
|
||||
---
|
||||
title: Docker Production Server
|
||||
---
|
||||
|
||||
## Docker Production Server
|
||||
|
||||
Using the [InvenTree docker image](./docker.md) streamlines the setup process for an InvenTree production server.
|
||||
|
||||
## Docker Compose
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
| Container | Description |
|
||||
| --- | --- |
|
||||
| inventree-db | PostgreSQL database |
|
||||
| inventree-server | Gunicorn web server |
|
||||
| invenrtee-worker | django-q background worker |
|
||||
| inventree-proxy | nginx proxy |
|
||||
|
||||
#### PostgreSQL Database
|
||||
|
||||
A postgresql database container which creates a postgres user: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`.
|
||||
|
||||
#### Background Worker
|
||||
|
||||
Runs the InvenTree background worker process. This spins up a second instance of the *inventree* container, with a different entrypoint command.
|
||||
|
||||
#### Nginx
|
||||
|
||||
Nginx working as a reverse proxy, separating requests for static and media files, and directing everything else to Gunicorn.
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
{% include 'nginx.conf' %}
|
||||
```
|
||||
|
||||
*__Note__: You must save this 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.
|
||||
|
||||
!!! 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:
|
||||
|
||||
| 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 |
|
||||
|
||||
## Production Setup
|
||||
|
||||
With the docker-compose recipe above, follow the instructions below to initialize a complete production server for InvenTree.
|
||||
|
||||
### Required Files
|
||||
|
||||
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)
|
||||
- [nginx.conf](https://github.com/inventree/InvenTree/blob/master/docker/nginx.conf)
|
||||
|
||||
!!! info "Command Directory"
|
||||
It is assumed that all commands will be run from the directory where `docker-compose.yml` is located.
|
||||
|
||||
### Configure Compose File
|
||||
|
||||
Save and 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.
|
||||
|
||||
!!! info "Database Credentials"
|
||||
You may also wish to change the default postgresql username and password!
|
||||
|
||||
### 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.
|
||||
|
||||
### Create Database
|
||||
|
||||
As this is the first time we are interacting with the docker containers, the InvenTree database has not yet been created.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
!!! info "User"
|
||||
If you have changed the `POSTGRES_USER` variable in the compose file, replace `pguser` with the different user.
|
||||
|
||||
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>
|
||||
|
||||
### Perform Database Migrations
|
||||
|
||||
The database has now been created, but it is empty! We need to perform the initial database migrations:
|
||||
|
||||
```
|
||||
docker-compose run inventree-server invoke migrate
|
||||
```
|
||||
|
||||
This will perform the required schema updates to create the required database tables.
|
||||
|
||||
### Collect Static Files
|
||||
|
||||
On first run, the required static files must be collected into the `static` volume:
|
||||
|
||||
```
|
||||
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:
|
||||
|
||||
```
|
||||
docker-compose run inventree-server invoke superuser
|
||||
```
|
||||
|
||||
### Configure InvenTree Options
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
This command launches the remaining containers:
|
||||
|
||||
- `inventree-server` - InvenTree web server
|
||||
- `inventree-worker` - Background worker
|
||||
- `inventree-nginx` - Nginx reverse proxy
|
||||
|
||||
!!! success "Up and Running!"
|
||||
You should now be able to view the InvenTree login screen at [http://localhost:1337](http://localhost:1337)
|
||||
|
||||
## Updating InvenTree
|
||||
|
||||
To update your InvenTree installation to the latest version, follow these steps:
|
||||
|
||||
### Stop Containers
|
||||
|
||||
Stop all running containers as below:
|
||||
|
||||
```
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### Update Images
|
||||
|
||||
Pull down the latest version of the InvenTree docker image
|
||||
|
||||
```
|
||||
docker-compose pull
|
||||
```
|
||||
|
||||
This ensures that the InvenTree containers will be running the latest version of the InvenTree source code.
|
||||
|
||||
### Start Containers
|
||||
|
||||
Now restart the containers.
|
||||
|
||||
As part of the server initialization process, data migrations and static file updates will be performed automatically.
|
||||
|
||||
```
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## Data Backup
|
||||
|
||||
Database and media files are stored external to the container, in the volume location specified in the `docker-compose.yml` file. It is strongly recommended that a backup of the files in this volume is performed on a regular basis.
|
||||
|
||||
### Exporting Database as JSON
|
||||
|
||||
To export the database to an agnostic JSON file, perform the following command:
|
||||
|
||||
```
|
||||
docker-compose run inventree-server invoke export-records /home/inventree/data/data.json
|
||||
```
|
||||
|
||||
This will export database records to the file `data.json` in your mounted volume directory.
|
||||
@ -101,8 +101,7 @@ source env/bin/activate
|
||||
|
||||
This will place the current shell session inside a virtual environment - the terminal should display the ``(env)`` prefix.
|
||||
|
||||
|
||||
## Downloading Source Code
|
||||
## InvenTree Source Code
|
||||
|
||||
InvenTree source code is distributed on [GitHub](https://github.com/inventree/inventree/), and the latest version can be downloaded (using Git) with the following command:
|
||||
|
||||
@ -123,8 +122,46 @@ There are multiple ways to get an InvenTree server up and running, of various co
|
||||
|
||||
The recommended method of installing InvenTree is to use [docker](https://www.docker.com). InvenTree provides out-of-the-box support for docker and docker-compose, which provides a simple, reliable and repeatable pipeline for integration into your production environment.
|
||||
|
||||
Refer to the [docker setup instructions](./docker.md) for further information.
|
||||
Refer to the following guides for further instructions:
|
||||
|
||||
- [**Docker development server setup guide**](./docker_dev.md)
|
||||
- [**Docker production server setup guide**](./docker.md)
|
||||
|
||||
### Bare Metal
|
||||
|
||||
If you do not wish to use the docker container, you will need to manually install the required packages and follow through the installation guide. Refer to the [InvenTree installation instructions](../install) for more details.
|
||||
If you do not wish to use the docker container, you will need to manually install the required packages and follow through the installation guide.
|
||||
|
||||
Refer to the following guides for further instructions:
|
||||
|
||||
- [**Bare metal development server setup guide**](./development.md)
|
||||
- [**Bare metal production server setup guide**](./install.md)
|
||||
|
||||
## Debug Mode
|
||||
|
||||
By default, the InvenTree web server is configured to run in [DEBUG mode](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-DEBUG).
|
||||
|
||||
Running in DEBUG mode provides many handy development features, however it is strongly recommended *NOT* to run in DEBUG mode in a production environment. This recommendation is made because DEBUG mode leaks a lot of information about your installation and may pose a security risk.
|
||||
|
||||
So, for a production setup, you should set `INVENTREE_DEBUG=false` in the [configuration options](./config.md).
|
||||
|
||||
### Potential Issues
|
||||
|
||||
However, turning off DEBUG mode creates further work for the system administrator. In particular, when running in DEBUG mode, the InvenTree web server natively manages *static* and *media* files, which means that the InvenTree server can run "monolithically" without the need for a separate web server.
|
||||
|
||||
With DEBUG mode turned off, a separate web server is required for serving *static* and *media* files. You can find further information in the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/deployment/).
|
||||
|
||||
There are *many* different ways that a sysadmin might wish to handle this.
|
||||
|
||||
The [docker production example](./docker_prod.md) provides an example using [Nginx](https://www.nginx.com/) to serve *static* and *media* files, and redirecting other requests to the InvenTree web server itself.
|
||||
|
||||
You may use this as a jumping off point, or use an entirely different server setup.
|
||||
|
||||
#### Static Files
|
||||
|
||||
Static files can be served without any need for authentication. In fact, they must be accessible *without* authentication, otherwise the unauthenticated views (such as the login screen) will not function correctly.
|
||||
|
||||
#### Media Files
|
||||
|
||||
It is highly recommended that the *media* files are served in such a way that user authentication is required.
|
||||
|
||||
Refer to the [docker production example](./docker_prod.md) for a demonstration of using nginx to serve media files only to authenticated users, and forward authentication requests to the InvenTree web server.
|
||||
|
||||
@ -92,3 +92,13 @@ The process status can be viewed [in your web browser](http://localhost:9001).
|
||||
## Production Ready
|
||||
|
||||
The InvenTree server (and background task manager) should now be running!
|
||||
|
||||
### Next Steps
|
||||
|
||||
You (or your system administrator) may wish to perform further steps such as placing the InvenTree server behind a reverse-proxy such as [nginx](https://www.nginx.com/).
|
||||
|
||||
As production environment options are many and varied, such tasks are outside the scope of this documentation.
|
||||
|
||||
There are many great online tutorials about running django applications in production!
|
||||
|
||||
As a starting point, you can refer to the [docker production example](./docker_prod.md) for a demonstration of running InvenTree behind a nginx proxy.
|
||||
|
||||
@ -47,11 +47,8 @@ nav:
|
||||
- Installation:
|
||||
- Introduction: start/intro.md
|
||||
- Configuration: start/config.md
|
||||
- Docker Installation: start/docker.md
|
||||
- Docker Development: start/docker_dev.md
|
||||
- Manual Installation: start/install.md
|
||||
- Development Server: start/development.md
|
||||
- Production Server: start/production.md
|
||||
- Docker Setup: start/docker.md
|
||||
- Bare Metal Setup: start/install.md
|
||||
- Updating: start/update.md
|
||||
- Migrating: start/migrate.md
|
||||
- Parts:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user