diff --git a/docs/start/docker.md b/docs/start/docker.md index 53eae8c..2847cd5 100644 --- a/docs/start/docker.md +++ b/docs/start/docker.md @@ -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 Ctrl+d - -### 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. diff --git a/docs/start/docker_dev.md b/docs/start/docker_dev.md index 7f2588a..9004cb2 100644 --- a/docs/start/docker_dev.md +++ b/docs/start/docker_dev.md @@ -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 ``` diff --git a/docs/start/docker_prod.md b/docs/start/docker_prod.md new file mode 100644 index 0000000..c8e624c --- /dev/null +++ b/docs/start/docker_prod.md @@ -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 Ctrl+d + +### 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. diff --git a/docs/start/intro.md b/docs/start/intro.md index ebaea15..3784077 100644 --- a/docs/start/intro.md +++ b/docs/start/intro.md @@ -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) diff --git a/mkdocs.yml b/mkdocs.yml index d6bfd1f..cb04ef4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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: