mirror of
https://github.com/inventree/inventree-docs.git
synced 2025-05-04 16:38:56 +00:00
Reorganize installation guide pages
This commit is contained in:
Oliver Walters
parent
50d9b32f73
commit
1e3d32c5ca
@ -63,227 +63,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
|
||||
@ -33,7 +33,7 @@ This script specifies the following containers:
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
232
docs/start/docker_prod.md
Normal file
232
docs/start/docker_prod.md
Normal file
@ -0,0 +1,232 @@
|
||||
---
|
||||
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:
|
||||
|
||||
#### 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.
|
||||
@ -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,16 @@ 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)
|
||||
|
||||
@ -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