Mirrored_Repos/InvenTree
1
0
Fork 0
mirror of https://github.com/inventree/InvenTree synced 2024-08-30 18:33:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

[WIP] docker / Caddy (#6551)

Browse Source 
* remove docker-sqlite file

- Do not want to encourage use of sqlite

* Add Caddyfile

* Add default site URL to .env

- Matches Caddyfile

* Cleanup / simplify .env file

* Remove dev nginx conf file

* Further cleanup of .env file

* Update docker-compose.yml

- Use caddy image instead of nginx as proxy

* Set max body size

* gunicorn: enable external logging

* Update file structure

* Cleanup docker-compose file

* Update docker/docker-compose.yml

Co-authored-by: Matthias Mair <code@mjmair.com>

* Update docker/Caddyfile

Co-authored-by: Matthias Mair <code@mjmair.com>

* Fix for postgresql packages

- Need postgresql13-client to be installed, it contains pg_dump
- Without this, backup / restore *does not work*

* Create static_i18n dir if it does not exist

* Reduce output from collectstatic

* Revert gunicorn logging

- Want to see the logs in docker

* Fix trailing slash

Ref: https://github.com/inventree/InvenTree/pull/6551#issuecomment-1962423765

* tasks.py - pass 'nouv' option through

* Update package requirements:

- Allow installation of rapidfuzz without building

* Install uv as part of docker image

* Add environment variable to control downstream URL

* Do not use uv package manager by default

- Currently does not work "correctly" - ignores installed packages
- Requires further work to run reliably

* Fix docker-compose file

- Do not build locally

* Cleanup gunicorn file

- Remove unused lien

* Cleanup docker-compose.yml

- Simpler volume management

* Update Caddyfile

Add newline

* Update requirements.txt

Add newline

* Update tasks.py

Add missing blank line

* Simplify Caddyfile

* Adds option for customizing web port

* cleanup docker-compose.yml

- Better mapping of caddy data
- Cleaner volume setup

* Add django version template

- Ensure all docs links point to the current django version we are using

* docs: cleanup intro.md

* Cleanup serving_files.md

* Cleanup config.md

* docker install docs updates

* Enable code block copying

* Fix include file

* Fix link

* Update docker install docs

* Update docker.md

* Add info about demo dataset

* Tweak heading

* Update docs link checks

* Fix workflow

* Another fix

* More ignore pattearns

---------

Co-authored-by: Matthias Mair <code@mjmair.com>
This commit is contained in:
Oliver 2024-02-28 01:06:19 +11:00 committed by GitHub
parent 8a128a2bdd
commit f6123cc261
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
35 changed files with 557 additions and 937 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/actions/setup/action.yaml vendored
View File

@ -86,8 +86,8 @@ runs:
- name: Run invoke install
if: ${{ inputs.install == 'true' }}
shell: bash
run: invoke install
run: invoke install --uv
- name: Run invoke update
if: ${{ inputs.update == 'true' }}
shell: bash
run: invoke update
run: invoke update --uv

9
.github/workflows/qc_checks.yaml vendored
View File

@ -111,9 +111,12 @@ jobs:
pip install -r docs/requirements.txt
python docs/ci/check_mkdocs_config.py
- name: Check Links
run: |
pip install linkcheckmd requests
python -m linkcheckmd docs --recurse
uses: gaurav-nelson/github-action-markdown-link-check@v1
with:
folder-path: docs
config-file: docs/mlc_config.json
check-modified-files-only: 'yes'
use-quiet-mode: 'yes'
schema:
name: Tests - API Schema Documentation

4
Dockerfile
View File

@ -62,7 +62,9 @@ RUN apk add --no-cache \
# Image format support
libjpeg libwebp zlib \
# Weasyprint requirements : https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#alpine-3-12
py3-pip py3-pillow py3-cffi py3-brotli pango poppler-utils openldap && \
py3-pip py3-pillow py3-cffi py3-brotli pango poppler-utils openldap \
# Core database packages
postgresql13-client && \
# fonts
apk --update --upgrade --no-cache add fontconfig ttf-freefont font-noto terminus-font && fc-cache -f

5
InvenTree/InvenTree/settings.py
View File

@ -136,6 +136,11 @@ STATICFILES_DIRS = []
STATICFILES_I18_PREFIX = 'i18n'
STATICFILES_I18_SRC = BASE_DIR.joinpath('templates', 'js', 'translated')
STATICFILES_I18_TRG = BASE_DIR.joinpath('InvenTree', 'static_i18n')
# Create the target directory if it does not exist
if not STATICFILES_I18_TRG.exists():
STATICFILES_I18_TRG.mkdir(parents=True)
STATICFILES_DIRS.append(STATICFILES_I18_TRG)
STATICFILES_I18_TRG = STATICFILES_I18_TRG.joinpath(STATICFILES_I18_PREFIX)

2
InvenTree/config_template.yaml
View File

@ -215,7 +215,7 @@ login_default_protocol: http
# Remote / proxy login
# These settings can introduce security problems if configured incorrectly. Please read
# https://docs.djangoproject.com/en/4.0/howto/auth-remote-user/ for more details
# https://docs.djangoproject.com/en/4.2/howto/auth-remote-user/ for more details
# The header name should be prefixed by `HTTP`. Please read the docs for more details
# https://docs.djangoproject.com/en/stable/ref/request-response/#django.http.HttpRequest.META
remote_login_enabled: False

33
docker/production/.env → docker/.env
View File

@ -1,16 +1,8 @@
# InvenTree environment variables for a postgresql production setup
# InvenTree environment variables for docker compose deployment
# Location of persistent database data (stored external to the docker containers)
# Note: You *must* un-comment this line, and point it to a path on your local machine
# e.g. Linux
#INVENTREE_EXT_VOLUME=/home/inventree/data
# e.g. Windows (docker desktop)
#INVENTREE_EXT_VOLUME=c:/Users/inventree/data
# Default web port for the InvenTree server
INVENTREE_WEB_PORT=1337
# Specify the location of the external data volume
# By default, placed in local directory 'inventree-data'
INVENTREE_EXT_VOLUME=./inventree-data
# Ensure debug is false for a production setup
INVENTREE_DEBUG=False
@ -23,16 +15,14 @@ INVENTREE_LOG_LEVEL=WARNING
#INVENTREE_ADMIN_EMAIL=
# Database configuration options
# Note: The example setup is for a PostgreSQL database
INVENTREE_DB_ENGINE=postgresql
INVENTREE_DB_NAME=inventree
INVENTREE_DB_HOST=inventree-db
INVENTREE_DB_PORT=5432
# Database credentials - These must be configured before running
# Uncomment the lines below, and change from the default values!
#INVENTREE_DB_USER=pguser
#INVENTREE_DB_PASSWORD=pgpassword
# Database credentials - These should be changed from the default values!
INVENTREE_DB_USER=pguser
INVENTREE_DB_PASSWORD=pgpassword
# Redis cache setup (disabled by default)
# Un-comment the following lines to enable Redis cache
@ -45,12 +35,15 @@ INVENTREE_DB_PORT=5432
INVENTREE_GUNICORN_TIMEOUT=90
# Enable custom plugins?
INVENTREE_PLUGINS_ENABLED=False
INVENTREE_PLUGINS_ENABLED=True
# Run migrations automatically?
INVENTREE_AUTO_UPDATE=False
INVENTREE_AUTO_UPDATE=True
# Image tag that should be used
INVENTREE_TAG=stable
COMPOSE_PROJECT_NAME=inventree-production
# Site URL - update this to match your host (and update the Caddyfile too!)
INVENTREE_SITE_URL="http://inventree.localhost"
COMPOSE_PROJECT_NAME=inventree

36
docker/Caddyfile Normal file
View File

@ -0,0 +1,36 @@
# Caddyfile for Inventree
# The following environment variables may be used:
# - INVENTREE_SITE_URL: The upstream URL of the Inventree site (default: inventree.localhost)
# - INVENTREE_SERVER: The internal URL of the Inventree container (default: http://inventree-server:8000)
(log_common) {
log {
output file /var/log/caddy/{args.0}.access.log
}
}
# Change the host to your domain (this will serve at inventree.localhost)
{$INVENTREE_SITE_URL:inventree.localhost} {
import log_common inventree
encode gzip
request_body {
max_size 100MB
}
handle_path /static/* {
root * /var/www/static
file_server
}
handle_path /media/* {
forward_auth {$INVENTREE_SERVER:"http://inventree-server:8000"} {
uri /auth/
}
root * /var/www/media
file_server
}
reverse_proxy {$INVENTREE_SERVER:"http://inventree-server:8000"}
}

64
docker/docker-compose.sqlite.yml
View File

@ -1,64 +0,0 @@
version: "3.8"
# Docker compose recipe for InvenTree development server
# - Runs sqlite database
# - Uses built-in django webserver
# - Runs the InvenTree background worker process
# - Serves media and static content directly from Django webserver
# IMPORTANT NOTE:
# The InvenTree docker image does not clone source code from git.
# Instead, you must specify *where* the source code is located,
# (on your local machine).
# The django server will auto-detect any code changes and reload the server.
services:
# InvenTree web server services
# Uses gunicorn as the web server
inventree-dev-server:
container_name: inventree-dev-server
build:
context: .
target: dev
# Cache the built image to be used by the inventree-dev-worker process
image: inventree-dev-image
ports:
# Expose web server on port 8000
- 8000:8000
volumes:
# Ensure you specify the location of the 'src' directory at the end of this file
- src:/home/inventree
environment:
- INVENTREE_DEBUG=True
- INVENTREE_DB_ENGINE=sqlite
- INVENTREE_DB_NAME=/home/inventree/db.sqlite3
restart: unless-stopped
# Background worker process handles long-running or periodic tasks
inventree-dev-worker:
container_name: inventree-dev-worker
image: inventree-dev-image
command: invoke worker
depends_on:
- inventree-dev-server
volumes:
# Ensure you specify the location of the 'src' directory at the end of this file
- src:/home/inventree
environment:
- INVENTREE_DEBUG=True
- INVENTREE_DB_ENGINE=sqlite
- INVENTREE_DB_NAME=/home/inventree/db.sqlite3
restart: unless-stopped
volumes:
# NOTE: Change "../" to a directory on your local machine, where the InvenTree source code is located
# Persistent data, stored external to the container(s)
src:
driver: local
driver_opts:
type: none
o: bind
# This directory specified where InvenTree source code is stored "outside" the docker containers
# By default, this directory is one level above the "docker" directory
device: ${INVENTREE_EXT_VOLUME:-../}

52
docker/production/docker-compose.yml → docker/docker-compose.yml
View File

@ -39,6 +39,7 @@ services:
# Use PostgreSQL as the database backend
inventree-db:
image: postgres:13
container_name: inventree-db
expose:
- ${INVENTREE_DB_PORT:-5432}/tcp
environment:
@ -48,13 +49,14 @@ services:
- POSTGRES_DB=${INVENTREE_DB_NAME:?You must provide the 'INVENTREE_DB_NAME' variable in the .env file}
volumes:
# Map 'data' volume such that postgres database is stored externally
- inventree_data:/var/lib/postgresql/data/:z
- ${INVENTREE_EXT_VOLUME:?You must specify the 'INVENTREE_EXT_VOLUME' variable in the .env file!}:/var/lib/postgresql/data/:z
restart: unless-stopped
# redis acts as database cache manager
# only runs under the "redis" profile : https://docs.docker.com/compose/profiles/
inventree-cache:
image: redis:7.0
container_name: inventree-cache
depends_on:
- inventree-db
profiles:
@ -70,10 +72,8 @@ services:
inventree-server:
# If you wish to specify a particular InvenTree version, do so here
image: inventree/inventree:${INVENTREE_TAG:-stable}
container_name: inventree-server
# Only change this port if you understand the stack.
# If you change this you have to change:
# - the proxy settings (on two lines)
# - only change the exposed port - eg `1338:8000` if you want to expose the server on port 1338
expose:
- 8000
depends_on:
@ -82,13 +82,14 @@ services:
- .env
volumes:
# Data volume must map to /home/inventree/data
- inventree_data:/home/inventree/data:z
- ${INVENTREE_EXT_VOLUME}:/home/inventree/data:z
restart: unless-stopped
# Background worker process handles long-running or periodic tasks
inventree-worker:
# If you wish to specify a particular InvenTree version, do so here
image: inventree/inventree:${INVENTREE_TAG:-stable}
container_name: inventree-worker
command: invoke worker
depends_on:
- inventree-server
@ -96,37 +97,26 @@ services:
- .env
volumes:
# Data volume must map to /home/inventree/data
- inventree_data:/home/inventree/data:z
- ${INVENTREE_EXT_VOLUME}:/home/inventree/data:z
restart: unless-stopped
# nginx acts as a reverse proxy
# 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!
# caddy acts as reverse proxy and static file server
# https://hub.docker.com/_/caddy
inventree-proxy:
image: nginx:stable
container_name: inventree-proxy
image: caddy:alpine
restart: always
depends_on:
- inventree-server
ports:
- ${INVENTREE_WEB_PORT:-80}:80
- 443:443
env_file:
- .env
ports:
# Default web port is 1337 (can be changed in the .env file)
- ${INVENTREE_WEB_PORT:-1337}:80
volumes:
# Provide nginx configuration file to the container
# Refer to the provided example file as a starting point
- ./nginx.prod.conf:/etc/nginx/conf.d/default.conf:ro,z
# nginx proxy needs access to static and media files
- inventree_data:/var/www:z
restart: unless-stopped
volumes:
# Persistent data, stored external to the container(s)
inventree_data:
driver: local
driver_opts:
type: none
o: bind
# This directory specified where InvenTree data are stored "outside" the docker containers
device: ${INVENTREE_EXT_VOLUME:?You must specify the 'INVENTREE_EXT_VOLUME' variable in the .env file!}
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- ${INVENTREE_EXT_VOLUME}/static:/var/www/static:z
- ${INVENTREE_EXT_VOLUME}/media:/var/www/media:z
- ${INVENTREE_EXT_VOLUME}:/var/log:z
- ${INVENTREE_EXT_VOLUME}:/data:z
- ${INVENTREE_EXT_VOLUME}:/config:z

2
docker/install_build_packages.sh
View File

@ -7,5 +7,5 @@ apk add gcc g++ musl-dev openssl-dev libffi-dev cargo python3-dev openldap-dev \
jpeg-dev openjpeg-dev libwebp-dev zlib-dev \
sqlite sqlite-dev \
mariadb-connector-c-dev mariadb-client mariadb-dev \
postgresql13-dev postgresql-libs postgresql13-client \
postgresql13-dev postgresql-libs \
$@

66
docker/nginx.dev.conf
View File

@ -1,66 +0,0 @@
server {
# Listen for connection on (internal) port 80
listen 80;
real_ip_header proxy_protocol;
location / {
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-By $server_addr:$server_port;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header CLIENT_IP $remote_addr;
proxy_pass_request_headers on;
proxy_redirect off;
client_max_body_size 100M;
proxy_buffering off;
proxy_request_buffering off;
# Change 'inventree-dev-server' to the name of the inventree server container,
# and '8000' to the INVENTREE_WEB_PORT (if not default)
proxy_pass http://inventree-dev-server:8000;
}
# Redirect any requests for static files
location /static/ {
alias /var/www/dev/static/;
autoindex on;
# Caching settings
expires 30d;
add_header Pragma public;
add_header Cache-Control "public";
}
# Redirect any requests for media files
location /media/ {
alias /var/www/dev/media/;
# Media files require user authentication
auth_request /auth;
# Content header to force download
add_header Content-disposition "attachment";
}
# Use the 'user' API endpoint for auth
location /auth {
internal;
proxy_pass http://inventree-dev-server:8000/auth/;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
}

67
docker/production/nginx.prod.conf
View File

@ -1,67 +0,0 @@
server {
# Listen for connection on (internal) port 80
# If you are exposing this server to the internet, you should use HTTPS!
# In which case, you should also set up a redirect from HTTP to HTTPS, and listen on port 443
# See the Nginx documentation for more details
listen 80;
real_ip_header proxy_protocol;
location / {
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-By $server_addr:$server_port;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header CLIENT_IP $remote_addr;
proxy_pass_request_headers on;
proxy_redirect off;
client_max_body_size 100M;
proxy_buffering off;
proxy_request_buffering off;
# Do not touch this unless you have a specific reason - this and the docker-compose need to match
proxy_pass http://inventree-server:8000;
}
# Redirect any requests for static files
location /static/ {
alias /var/www/static/;
autoindex on;
# Caching settings
expires 30d;
add_header Pragma public;
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;
# Content header to force download
add_header Content-disposition "attachment";
}
# 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;
}
}

3
docker/requirements.txt
View File

@ -17,3 +17,6 @@ gunicorn>=21.2.0
# LDAP required packages
django-auth-ldap # Django integration for ldap auth
python-ldap # LDAP auth support
# Upgraded python package installer
uv

1
docs/_includes/django.html Normal file
View File

@ -0,0 +1 @@
https://docs.djangoproject.com/en/{{ config.extra.django_version }}

6
docs/docs/develop/starting.md
View File

@ -8,16 +8,16 @@ As part of the larger project other languages/techniques are used, such as docke
### Getting started
#### Getting to know the basics
The Django framework is a powerful tool for creating web applications. It is well documented and has a large community. The [Django documentation](https://docs.djangoproject.com/en/stable/) is a good place to start.
The Django framework is a powerful tool for creating web applications. It is well documented and has a large community. The [Django documentation]({% include "django.html" %}) is a good place to start.
In particular the [tutorial](https://docs.djangoproject.com/en/stable/intro/tutorial01/) is a good way to get to know the basics of Django.
In particular the [tutorial]({% include "django.html" %}/intro/tutorial01/) is a good way to get to know the basics of Django.
InvenTree follows the best practies for Django so most of the contents should be applicable to InvenTree as well. The REST API is based on the [Django REST framework](https://www.django-rest-framework.org/).
#### Setting up a development environment
The recommended way to set up a development environment is to use VSCode devcontainers. The required files are provided with the repo, the docs are on a [dedicated page](./devcontainer.md).
It is also possible to use [docker development](../start/docker_dev.md) or [bare metal development](../start/bare_dev.md). With these you need to install the required dependencies manually with a dedicated task.
It is also possible to use [docker](../start/docker.md) or [bare metal development](../start/bare_dev.md). With these you need to install the required dependencies manually with a dedicated task.
```bash
invoke setup-dev
```

2
docs/docs/extend/plugins.md
View File

@ -85,7 +85,7 @@ The configuration entries must be enabled via the [InvenTree admin interface](..
### Plugin Mixins
Common use cases are covered by pre-supplied modules in the form of *mixins* (similar to how [Django](https://docs.djangoproject.com/en/stable/topics/class-based-views/mixins/) does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box.
Common use cases are covered by pre-supplied modules in the form of *mixins* (similar to how [Django]({% include "django.html" %}/topics/class-based-views/mixins/) does it). Each mixin enables the integration into a specific area of InvenTree. Sometimes it also enhances the plugin with helper functions to supply often used functions out-of-the-box.
Supported mixin classes are:

2
docs/docs/extend/plugins/app.md
View File

@ -7,4 +7,4 @@ title: App Mixin
If this mixin is added to a plugin the directory the plugin class is defined in is added to the list of `INSTALLED_APPS` in the InvenTree server configuration.
!!! warning "Danger Zone"
Only use this mixin if you have an understanding of djangos [app system](https://docs.djangoproject.com/en/stable/ref/applications). Plugins with this mixin are deeply integrated into InvenTree and can cause difficult to reproduce or long-running errors. Use the built-in testing functions of django to make sure your code does not cause unwanted behaviour in InvenTree before releasing.
Only use this mixin if you have an understanding of djangos [app system]({% include "django.html" %}/ref/applications). Plugins with this mixin are deeply integrated into InvenTree and can cause difficult to reproduce or long-running errors. Use the built-in testing functions of django to make sure your code does not cause unwanted behaviour in InvenTree before releasing.

2
docs/docs/extend/plugins/metadata.md
View File

@ -12,7 +12,7 @@ A much simpler and more accessible method of recording custom information agains
### MetadataMixin Class
*Most* of the models in the InvenTree database inherit from the `MetadataMixin` class, which adds the `metadata` field to each inheriting model. The `metadata` field is a [JSONField](https://docs.djangoproject.com/en/3.2/ref/models/fields/#django.db.models.JSONField) which allows for storing arbitrary JSON data against the model instance.
*Most* of the models in the InvenTree database inherit from the `MetadataMixin` class, which adds the `metadata` field to each inheriting model. The `metadata` field is a [JSONField]({% include "django.html" %}/ref/models/fields/#django.db.models.JSONField) which allows for storing arbitrary JSON data against the model instance.
This field is provided to allow any plugins to store and retrieve arbitrary data against any item in the database.

6
docs/docs/extend/plugins/urls.md
View File

@ -6,7 +6,7 @@ title: URLs Mixin
Use the class constant `URLS` for a array of URLs that should be added to InvenTrees URL paths or override the `plugin.setup_urls` function.
The array has to contain valid URL patterns as defined in the [django documentation](https://docs.djangoproject.com/en/stable/topics/http/urls/).
The array has to contain valid URL patterns as defined in the [django documentation]({% include "django.html" %}/topics/http/urls/).
``` python
class MyUrlsPlugin(UrlsMixin, InvenTreePlugin):
@ -19,14 +19,14 @@ class MyUrlsPlugin(UrlsMixin, InvenTreePlugin):
```
The URLs get exposed under `/plugin/{plugin.slug}/*` and get exposed to the template engine with the prefix `plugin:{plugin.slug}:` (for usage with the [url tag](https://docs.djangoproject.com/en/stable/ref/templates/builtins/#url)).
The URLs get exposed under `/plugin/{plugin.slug}/*` and get exposed to the template engine with the prefix `plugin:{plugin.slug}:` (for usage with the [url tag]({% include "django.html" %}/ref/templates/builtins/#url)).
!!! info "Note"
In this example, when an HTTP request is made to `/plugin/{plugin.slug}/increase/.../...` the function `self.view_increase` is called and returns the view to be displayed (step 4 in the Django documentation)
### Views
If your plugin will implement and host another webpage, familiarize yourself with Django views. Implementation is exactly the same.
A good place to start is the [django documentation](https://docs.djangoproject.com/en/4.2/topics/http/views/). Additional InvenTree-specific information is below.
A good place to start is the [django documentation]({% include "django.html" %}/topics/http/views/). Additional InvenTree-specific information is below.
### Rendering Views
Rendering templated views is also supported. Templated HTML files should be placed inside your plugin folder in a sub folder called `templates`.

6
docs/docs/faq.md
View File

@ -29,7 +29,7 @@ If the installed version of invoke is too old, users may see error messages duri
- *'update' did not receive all required positional arguments!*
- *Function has keyword-only arguments or annotations*
As per the [invoke guide](./start/intro.md#invoke), the minimum required version of Invoke is `2.0.0`.
As per the [invoke guide](./start/intro.md#invoke), the minimum required version of Invoke is `{{ config.extra.min_invoke_version }}`.
To determine the version of invoke you have installed, run either:
@ -77,7 +77,7 @@ The most common problem here is that the correct sequenct of steps has not been
For more information, refer to the installation guides:
- [Docker Installation](./start/docker_prod.md#updating-inventree)
- [Docker Installation](./start/docker_install.md#updating-inventree)
- [Bare Metal Installation](./start/install.md#updating-inventree)
!!! warning "Invoke Update"
@ -117,7 +117,7 @@ invoke worker
### File Sync Issues - Docker
When installing under [Docker](./start/docker.md), sometimes issues may arise keeping [persistent data](./start/docker.md#persistent-data) in sync. Refer to the [common issues](./start/docker_prod.md#common-issues) section in the docker setup guide for further details.
When installing under [Docker](./start/docker.md), sometimes issues may arise keeping [persistent data](./start/docker.md#persistent-data) in sync. Refer to the [common issues](./start/docker.md#common-issues) section in the docker setup guide for further details.
### Permission denied for mkdir: /home/inventree

6
docs/docs/report/report.md
View File

@ -25,7 +25,7 @@ Templates are rendered using standard HTML / CSS - if you are familiar with web
### Template Language
Uploaded report template files are passed through the [django template rendering framework](https://docs.djangoproject.com/en/dev/topics/templates/), and as such accept the same variable template strings as any other django template file. Different variables are passed to the report template (based on the context of the report) and can be used to customize the contents of the generated PDF.
Uploaded report template files are passed through the [django template rendering framework]({% include "django.html" %}/topics/templates/), and as such accept the same variable template strings as any other django template file. Different variables are passed to the report template (based on the context of the report) and can be used to customize the contents of the generated PDF.
### Variables
@ -77,7 +77,7 @@ Item: {{ item }}
```
!!! info "Conditionals"
Refer to the [django template language documentation](https://docs.djangoproject.com/en/dev/ref/templates/language/) for more information.
Refer to the [django template language documentation]({% include "django.html" %}/ref/templates/language/) for more information.
### Localization Issues
@ -278,7 +278,7 @@ Asset files can be rendered directly into the template as follows
If the requested asset name does not match the name of an uploaded asset, the template will continue without loading the image.
!!! info "Assets location"
You need to ensure your asset images to the report/assets directory in the [data directory](../start/docker_dev.md/#data-directory). Upload new assets via the [admin interface](../settings/admin.md) to ensure they are uploaded to the correct location on the server.
You need to ensure your asset images to the report/assets directory in the [data directory](../start/intro.md#file-storage). Upload new assets via the [admin interface](../settings/admin.md) to ensure they are uploaded to the correct location on the server.
## Report Snippets

2
docs/docs/start/advanced.md
View File

@ -94,7 +94,7 @@ This can be used to track usage and performance of the InvenTree backend and con
If your InvenTree instance is used in a multi-site environment, you can enable multi-site support. Note that supporting multiple sites is well outside the scope of most InvenTree installations. If you know what you are doing, and have a good reason to enable multi-site support, you can do so by setting the `INVENTREE_SITE_MULTI` environment variable to `True`.
!!! tip "Django Documentation"
For more information on multi-site support, refer to the [Django documentation](https://docs.djangoproject.com/en/3.2/ref/contrib/sites/).
For more information on multi-site support, refer to the [Django documentation]({% include "django.html" %}/ref/contrib/sites/).
| Environment Variable | Config Key | Description | Default |
| --- | --- | --- | --- |

7
docs/docs/start/bare_prod.md
View File

@ -9,7 +9,7 @@ title: Bare Metal Production Server
The following instructions provide a reasonably performant server, using [gunicorn](https://gunicorn.org/) as a webserver, and [supervisor](http://supervisord.org/) as a process manager.
For alternative deployment methods, django apps provide multiple deployment methods - see the [Django documentation](https://docs.djangoproject.com/en/2.2/howto/deployment/).
For alternative deployment methods, django apps provide multiple deployment methods - see the [Django documentation]({% include "django.html" %}/howto/deployment/).
There are also numerous online tutorials describing how to deploy a Django application either locally or on an online platform.
@ -102,10 +102,9 @@ In addition to the InvenTree server, you will need a method of delivering static
### 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/).
You (or your system administrator) may wish to perform further steps such as placing the InvenTree server behind a reverse-proxy such as [caddy](https://caddyserver.com/), or [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.
As a starting point, you can refer to the [docker guide](./docker.md) for a demonstration of running InvenTree behind a Caddy proxy.

115
docs/docs/start/config.md
View File

@ -1,28 +1,13 @@
---
title: Database Configuration
title: InvenTree Configuration
---
## Database Configuration
## InvenTree Configuration
While many InvenTree options can be configured at "run time", there are a number of system configuration parameters which need to be set *before* running InvenTree. Admin users will need to adjust the InvenTree installation to meet the particular needs of their setup. For example, pointing to the correct database backend, or specifying a list of allowed hosts.
InvenTree system settings can be specified either via environment variables, or in a configuration file.
!!! info "Environment Variables"
Settings specified using environment variables take priority. Values provided in the configuration file are ignored if a matching environment variable is present.
### Environment Variables
In addition to specifying InvenTree options via the `config.yaml` file, these options can also be specified via environment variables. This can be usful for system administrators who want the flexibility of altering settings without editing the configuration file.
Environment variable settings generally use the `INVENTREE_` prefix, and are all uppercase.
!!! info "Configuration Priority"
Configuration options set via environment variables will take priority over the values set in the `config.yaml` file.
!!! warning "Available Variables"
Some configuration options cannot be set via environment variables. Refer to the documentation below.
### Configuration File
To support install specific settings, a simple configuration file `config.yaml` is provided. This configuration file is loaded by the InvenTree server at runtime. Settings specific to a given install should be adjusted in `config.yaml`.
@ -43,7 +28,19 @@ The configuration file *template* can be found on [GitHub](https://github.com/in
The default configuration file (as defined by the template linked above) will be copied to the specified configuration file location on first run, if a configuration file is not found in that location.
!!! tip "Restart Server"
The contents of the configuration file are read when the InevnTree server first launches. If any changes are made to the configuration file, ensure that the server is restarted, so that the changes can be made operational.
The contents of the configuration file are read when the InvenTree server first launches. If any changes are made to the configuration file, ensure that the server is restarted, so that the changes can be made operational.
### Environment Variables
In addition to specifying InvenTree options via the `config.yaml` file, these options can also be specified via environment variables. This can be useful for system administrators who want the flexibility of altering settings without editing the configuration file.
Environment variable settings generally use the `INVENTREE_` prefix, and are all uppercase.
!!! info "Configuration Priority"
Configuration options set via environment variables will take priority over the values set in the `config.yaml` file. This can be useful for overriding specific settings without needing to edit the configuration file.
!!! warning "Available Variables"
Some configuration options cannot be set via environment variables. Refer to the documentation below.
## Basic Options
@ -56,31 +53,52 @@ The following basic options are available:
| INVENTREE_DB_LOGGING | db_logging | Enable logging of database messages | False |
| INVENTREE_TIMEZONE | timezone | Server timezone | UTC |
| INVENTREE_SITE_URL | site_url | Specify a fixed site URL | *Not specified* |
| INVENTREE_ADMIN_ENABLED | admin_enabled | Enable the [django administrator interface](https://docs.djangoproject.com/en/4.2/ref/contrib/admin/) | True |
| INVENTREE_ADMIN_ENABLED | admin_enabled | Enable the [django administrator interface]({% include "django.html" %}/ref/contrib/admin/) | True |
| INVENTREE_ADMIN_URL | admin_url | URL for accessing [admin interface](../settings/admin.md) | admin |
| INVENTREE_LANGUAGE | language | Default language | en-us |
| INVENTREE_BASE_URL | base_url | Server base URL | *Not specified* |
| INVENTREE_AUTO_UPDATE | auto_update | Database migrations will be run automatically | False |
### Admin Site
## Server Access
Django provides a powerful [administrator interface](https://docs.djangoproject.com/en/4.2/ref/contrib/admin/) which can be used to manage the InvenTree database. This interface is enabled by default, but can be disabled by setting `INVENTREE_ADMIN_ENABLED` to `False`.
Depending on how your InvenTree installation is configured, you will need to pay careful attention to the following settings. If you are running your server behind a proxy, or want to adjust support for CORS requests, one or more of the following settings may need to be adjusted.
#### Custom Admin URL
!!! warning "Advanced Users"
The following settings require a certain assumed level of knowledge. You should also refer to the [django documentation]({% include "django.html" %}/ref/settings/) for more information.
By default, the admin interface is available at the `/admin/` URL. This can be changed by setting the `INVENTREE_ADMIN_URL` environment variable.
!!! danger "Not Secure"
Allowing access from any host is not secure, and should be adjusted for your installation.
!!! info "Environment Variables"
Note that a provided environment variable will override the value provided in the configuration file.
!!! success "INVENTREE_SITE_URL"
If you have specified the `INVENTREE_SITE_URL`, this will automatically be used as a trusted CSRF and CORS host (see below).
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_ALLOWED_HOSTS | allowed_hosts | List of allowed hosts | `*` |
| INVENTREE_TRUSTED_ORIGINS | trusted_origins | List of trusted origins. Refer to the [django documentation]({% include "django.html" %}/ref/settings/#csrf-trusted-origins) | Uses the *INVENTREE_SITE_URL* parameter, if set. Otherwise, an empty list. |
| INVENTREE_CORS_ORIGIN_ALLOW_ALL | cors.allow_all | Allow all remote URLS for CORS checks | False |
| INVENTREE_CORS_ORIGIN_WHITELIST | cors.whitelist | List of whitelisted CORS URLs. Refer to the [django-cors-headers documentation](https://github.com/adamchainz/django-cors-headers#cors_allowed_origins-sequencestr) | Uses the *INVENTREE_SITE_URL* parameter, if set. Otherwise, an empty list. |
| INVENTREE_USE_X_FORWARDED_HOST | use_x_forwarded_host | Use forwarded host header | False |
| INVENTREE_USE_X_FORWARDED_PORT | use_x_forwarded_port | Use forwarded port header | False |
| INVENTREE_CORS_ALLOW_CREDENTIALS | cors.allow_credentials | Allow cookies in cross-site requests | True |
## Admin Site
Django provides a powerful [administrator interface]({% include "django.html" %}/ref/contrib/admin/) which can be used to manage the InvenTree database. This interface is enabled by default, and available at the `/admin/` URL.
The following admin site configuration options are available:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_ADMIN_ENABLED | admin_enabled | Enable the django administrator interface | True |
| INVENTREE_ADMIN_URL | admin_url | URL for accessing the admin interface | admin |
!!! warning "Security"
Changing the admin URL is a simple way to improve security, but it is not a substitute for proper security practices.
### Base URL Configuration
The base URL of the InvenTree site is required for constructing absolute URLs in a number of circumstances. To construct a URL, the InvenTree iterates through the following options in decreasing order of importance:
1. Static configuration (i.e. set using environment variable or configuration file as above)
2. Global settings (i.e. configured at run-time in the [global settings](../settings/global.md))
3. Using the hostname supplied by the user request
## Administrator Account
An administrator account can be specified using the following environment variables:
@ -196,32 +214,6 @@ A list of currency codes (e.g. *AUD*, *CAD*, *JPY*, *USD*) can be specified usin
!!! tip "More Info"
Read the [currencies documentation](../settings/currency.md) for more information on currency support in InvenTree
## Server Access
Depending on how your InvenTree installation is configured, you will need to pay careful attention to the following settings. If you are running your server behind a proxy, or want to adjust support for CORS requests, one or more of the following settings may need to be adjusted.
!!! warning "Advanced Users"
The following settings require a certain assumed level of knowledge. You should also refer to the [django documentation](https://docs.djangoproject.com/en/4.2/ref/settings/) for more information.
!!! danger "Not Secure"
Allowing access from any host is not secure, and should be adjusted for your installation.
!!! info "Environment Variables"
Note that a provided environment variable will override the value provided in the configuration file.
!!! success "INVENTREE_SITE_URL"
If you have specified the `INVENTREE_SITE_URL`, this will automatically be used as a trusted CSRF and CORS host (see below).
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| INVENTREE_ALLOWED_HOSTS | allowed_hosts | List of allowed hosts | `*` |
| INVENTREE_TRUSTED_ORIGINS | trusted_origins | List of trusted origins. Refer to the [django documentation](https://docs.djangoproject.com/en/4.2/ref/settings/#csrf-trusted-origins) | Uses the *INVENTREE_SITE_URL* parameter, if set. Otherwise, an empty list. |
| INVENTREE_CORS_ORIGIN_ALLOW_ALL | cors.allow_all | Allow all remote URLS for CORS checks | False |
| INVENTREE_CORS_ORIGIN_WHITELIST | cors.whitelist | List of whitelisted CORS URLs. Refer to the [django-cors-headers documentation](https://github.com/adamchainz/django-cors-headers#cors_allowed_origins-sequencestr) | Uses the *INVENTREE_SITE_URL* parameter, if set. Otherwise, an empty list. |
| INVENTREE_USE_X_FORWARDED_HOST | use_x_forwarded_host | Use forwarded host header | False |
| INVENTREE_USE_X_FORWARDED_PORT | use_x_forwarded_port | Use forwarded port header | False |
| INVENTREE_CORS_ALLOW_CREDENTIALS | cors.allow_credentials | Allow cookies in cross-site requests | True |
## File Storage Locations
InvenTree requires some external directories for storing files:
@ -230,6 +222,7 @@ InvenTree requires some external directories for storing files:
| --- | --- | --- | --- |
| INVENTREE_STATIC_ROOT | static_root | [Static files](./serving_files.md#static-files) directory | *Not specified* |
| INVENTREE_MEDIA_ROOT | media_root | [Media files](./serving_files.md#media-files) directory | *Not specified* |
| INVENTREE_BACKUP_DIR | backup_dir | Backup files directory | *Not specified* |
!!! tip "Serving Files"
Read the [Serving Files](./serving_files.md) section for more information on hosting *static* and *media* files
@ -298,7 +291,7 @@ The InvenTree server can be integrated with the [sentry.io](https://sentry.io) m
!!! info "Default DSN"
If enabled with the default DSN, server errors will be logged to a sentry.io account monitored by the InvenTree developers.
### Customisation Options
### Customization Options
The logo and custom messages can be changed/set:
@ -327,9 +320,3 @@ The following [plugin](../extend/plugins.md) configuration options are available
| INVENTREE_PLUGIN_NOINSTALL | plugin_noinstall | Disable Plugin installation via API - only use plugins.txt file | False |
| INVENTREE_PLUGIN_FILE | plugins_plugin_file | Location of plugin installation file | *Not specified* |
| INVENTREE_PLUGIN_DIR | plugins_plugin_dir | Location of external plugin directory | *Not specified* |
## Other Options
### Middleware
Custom middleware layers can be specified here.

107
docs/docs/start/docker.md
View File

@ -2,18 +2,24 @@
title: Docker Setup
---
## Docker Image
## Docker Installation Guide
The information on this page serves as useful theory and background information for setting up InvenTree using docker.
!!! tip "Docker Install"
To jump right into the installation process, refer to the [docker installation guide](./docker_install.md)
## Docker Theory
The most convenient method of installing and running InvenTree is to use the official [docker image](https://hub.docker.com/r/inventree/inventree), available from docker-hub.
The InvenTree docker image contains all the required system packages, python modules, and configuration files for running a containerised InvenTree web server.
!!! tip "Compose Yourself"
The InvenTree container requires linking with other docker containers (such as a database backend) for complete operation. Sample [docker compose](#docker-compose) scripts are provided to get you up and running
The InvenTree docker image contains all the required system packages, python modules, and configuration files for running a containerized InvenTree production installation.
!!! tip "Docker Compose"
The InvenTree container requires linking with other docker containers (such as a database backend, and a file server) for complete operation. Refer to the [docker compose](#docker-compose) instructions to get up and running
!!! warning "Check the version"
Please make sure you are reading the [STABLE](https://docs.inventree.org/en/stable/start/docker_prod/) documentation when using the stable docker image tags.
Please make sure you are reading the [STABLE](https://docs.inventree.org/en/stable/start/docker/) documentation when using the stable docker image tags.
!!! warning "Assumed Knowledge"
A very basic understanding of [Docker](https://www.docker.com/) and [docker compose](https://docs.docker.com/compose/) is assumed, for the following setup guides.
@ -26,16 +32,11 @@ Pre-built Docker images are available from [dockerhub](https://hub.docker.com/r/
| --- | --- | --- |
| **inventree:stable** | The most recent *stable* release version of InvenTree | [stable docs](https://docs.inventree.org/en/stable/start/docker/) |
| **inventree:latest** | The most up-to-date *development* version of InvenTree. | [latest docs](https://docs.inventree.org/en/latest/start/docker/) |
| **inventree:_tag_** | Specific tagged images are built for each tagged release of InvenTree, e.g. `inventree:0.7.3`| https://docs.inventree.org/en/INSERT_YOUR_TAG_HERE/start/docker/ |
| **inventree:_tag_** | Specific tagged images are built for each tagged release of InvenTree, e.g. `inventree:0.7.3`| *Refer to specific InvenTree version* |
### Docker Compose
The InvenTree docker image provides a containerized webserver, however it *must* be connected with other containers (at the very least, a database backend).
InvenTree provides sample docker compose files to get you up and running:
- A [development](#development-server) compose file provides a simple way to spin up a development environment
- A [production](#production-server) compose file is intended to be used in a production environment, running the web server behind a nginx proxy.
The InvenTree docker image provides a containerized webserver, however it *must* be connected with other containers to function.
### Environment Variables
@ -77,14 +78,82 @@ Plugins are supported natively when running under docker. There are two ways to
- Install via the `plugins.txt` file provided in the external data directory
- Install into the `plugins/` subdirectory in the external data directory
## Docker Setup Guides
## Docker Compose
With these basics in mind, refer to the following installation guides:
[docker compose](https://docs.docker.com/compose/) is used to sequence all the required containerized processes.
### Production Server
### Static and Media Files
Refer to the [docker production server setup guide](./docker_prod.md) for instructions on configuring a production server using docker.
The production docker compose configuration outlined on this page uses [Caddy](https://caddyserver.com/) 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.
### Development Server
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details
Refer to the [docker development server setup guide](./docker_dev.md) for instructions on configuring a development server using docker.
### SSL Certificates
The provided `Caddyfile` configuration file is setup to enable [Automatic HTTPS](https://caddyserver.com/docs/automatic-https) by default! All you have to do is specify a `https://` URL in the `INVENTREE_SITE_URL` variable.
### Containers
The example docker compose file launches the following containers:
| Container | Description |
| --- | --- |
| inventree-db | PostgreSQL database |
| inventree-server | Gunicorn web server |
| inventree-worker | django-q background worker |
| inventree-proxy | Caddy file server and reverse proxy |
| *inventree-cache* | *redis cache (optional)* |
#### PostgreSQL Database
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).
#### Web Server
Runs an InvenTree web server instance, powered by a Gunicorn web server.
#### Background Worker
Runs the InvenTree background worker process. This spins up a second instance of the *inventree* container, with a different entrypoint command.
#### File Server
Caddy working as a reverse proxy, separating requests for static and media files, and directing everything else to Gunicorn.
This container uses the official [caddy image](https://hub.docker.com/_/caddy).
#### Redis Cache
Redis is used as cache storage for the InvenTree server. This provides a more performant caching system which can useful in larger installations.
This container uses the official [redis image](https://hub.docker.com/_/redis).
!!! info "Redis on Docker"
Docker adds an additional network layer - that might lead to lower performance than bare metal.
To optimize and configure your redis deployment follow the [official docker guide](https://redis.io/docs/getting-started/install-stack/docker/#configuration).
!!! warning "Disabled by default"
The *redis* container is not enabled in the default configuration. This is provided as an example for users wishing to use redis.
To enable the *redis* container, run any `docker compose` commands with the `--profile redis` flag.
You will also need to un-comment the `INVENTREE_CACHE_<...>` variables in the `.env` file.
### Data Volume
InvenTree stores any persistent data (e.g. uploaded media files, database data, etc) in a [volume](https://docs.docker.com/storage/volumes/) which is mapped to a local system directory. The location of this directory must be configured in the `.env` file, specified using the `INVENTREE_EXT_VOLUME` variable.
!!! info "Data Directory"
Make sure you change the path to the local directory where you want persistent data to be stored.
## Common Issues
### Volume Mapping
When configuring a docker install, sometimes a misconfiguration can cause peculiar issues where it seems that the installation is functioning correctly, but uploaded files and plugins do not "persist" across sessions. In such cases, the "mounted" volume has not mapped to a directory on your local filesystem. This may occur if you have tried multiple setup options without clearing existing volume bindings.
!!! tip "Start with a clean slate"
To prevent such issues, it is recommended that you start with a "clean slate" if you have previously configured an InvenTree installation under docker.
If you have previously setup InvenTree, remove existing volume bindings using the following command:
```docker volume rm -f inventree-production_inventree_data```

241
docs/docs/start/docker_dev.md
View File

@ -1,241 +0,0 @@
---
title: Docker Development Server
---
## Docker Development Server
You can use docker to launch and manage a development server, in a similar fashion to managing a production server.
The InvenTree dockerfile (`./Dockerfile`) uses a [multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) process to allow both production and development setups from the same image.
There are some key differences compared to the [docker production setup](./docker_prod.md):
- The docker image is built locally, rather than being downloaded from DockerHub
- The docker image points to the source code on your local machine (mounted as a 'volume' in the docker container)
- The django webserver is used, instead of running behind Gunicorn
- The server will automatically reload when code changes are detected
!!! info "Static and Media Files"
The development server runs in DEBUG mode, and serves static and media files natively.
!!! 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.
### Data Directory
Persistent data (such as the stored database, media files, configuration files, etc) will be stored in the `./data` directory (relative to the InvenTree source code directory).
- This directory is automatically created when you launch InvenTree via docker
- This directory is excluded from git version tracking
## Quickstart Guide
To get "up and running" with a development environment, complete with a set of [demo data](https://github.com/inventree/demo-dataset) to work with, run the following commands:
```bash
git clone https://github.com/inventree/InvenTree.git && cd InvenTree
docker compose run inventree-dev-server invoke update
docker compose run inventree-dev-server invoke setup-test --dev
docker compose up -d
```
!!! tip "Development Server"
You can then view the development server at [http://localhost:8000](http://localhost:8000)
!!! info "Details, details"
For a more in-depth setup guide, continue reading below!
## Development Setup Guide
To get started with an InvenTree development setup, follow the simple steps outlined below. Before continuing, ensure that you have completed the following steps:
- Downloaded the InvenTree source code to your local machine
- Installed docker on your local machine (install *Docker Desktop* on Windows)
- Have a terminal open to the root directory of the InvenTree source code
### Edit Environment Variables (Optional)
If desired, the user may edit the environment variables, located in the `.env` file.
!!! success "This step is optional"
This step can be skipped, as the default variables will work just fine!
!!! info "Database Credentials"
You may also wish to change the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`) from their default values
### Perform Initial Setup
Perform the initial database setup by running the following command:
```bash
docker compose run inventree-dev-server invoke update
```
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!
### Import Demo Data
To fill the database with a demo dataset, run the following command:
```bash
docker compose run inventree-dev-server invoke setup-test --dev
```
### Start Docker Containers
Now that the database has been created, and migrations applied, we are ready to launch the InvenTree containers:
```bash
docker compose up -d
```
### Create Admin Account
If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts:
!!! info "Containers must be running"
For the `invoke superuser` command to execute properly, ensure you have run the `docker compose up -d` command.
```bash
docker compose run inventree-dev-server invoke superuser
```
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.
## Running commands in the container
Using `docker compose run [...]` commands creates a new container to run this specific command.
This will eventually clutter your docker with many dead containers that take up space on the system.
You can access the running containers directly with the following:
```bash
docker exec -it inventree-dev-server /bin/bash
```
You then run the following to access the virtualenv:
```bash
source data/env/bin/activate
```
This sets up a bash terminal where you can run `invoke` commands directly.
!!! warning "Tests"
Running `invoke test` in your currently active inventree-dev-server container may result in tests taking longer than usual.
### Cleaning up old containers
If you have Docker Desktop installed, you will be able to remove containers directly in the GUI.
Your active containers are grouped under "inventree" in Docker Desktop.
The main dev-server, dev-db, and dev-worker containers are all listed without the "inventree" prefix.
One time run containers, like those executed via `docker compose run [...]` are suffixed with `run-1a2b3c4d5e6f` where the hex string varies.
To remove such containers, either click the garbage bin on the end of the line, or mark the containers, and click the delete button that shows up.
This is the recommended procedure for container cleanup.
#### Advanced cleanup
!!! warning "Advanced users only"
This section requires good knowledge of Docker and how it operates.
Never perform these commands if you do not understand what they do
If you're running a container with the general boilerplate commands used with invoke (invoke test, invoke update, etc) and no custom parameters or execution, you can add the `--rm` flag to `docker compose run`, and the container will delete itself when it goes down.
Do note that any data not stored in a volume, i.e. only in the container, will be lost when the container stops.
To clean out old containers using the command line, follow this guide:
Run the following command:
```bash
docker ps -a --filter status=exited
```
This gives you a list of all stopped containers.
Find the containers you wish to delete, copy the container IDs and add them to this command:
```bash
docker rm [ID1] [ID2] [IDn]
```
When executed, this removes all containers whose IDs were pasted.
!!! warning "Execute at own risk"
The command below does not forgive errors.
Execute this only if you know what you're doing
Running this command will remove **all** stopped one-time run InvenTree containers matching parameters:
```bash
docker container prune --filter label="com.docker.compose.oneoff=True" --filter label="com.docker.compose.service=inventree-dev-server"
```
The following output will appear:
```
WARNING! This will remove all stopped containers.
Are you sure you want to continue? [y/N] y
Deleted Containers:
[IDs of any container that was deleted, one per line]
```
## Restarting Services
Once initial setup is complete, stopping and restarting the services is much simpler:
### Stop InvenTree Services
To stop the InvenTree development server, simply run the following command:
```
docker compose down
```
### Start InvenTree Services
To start the InvenTree development server, simply run the following command:
```
docker compose up -d
```
### Restart InvenTree Services
A restart cycle is as simple as:
```
docker compose restart
```
## 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 run inventree-dev-server invoke update
```
### Docker Image Updates
Occasionally, the docker image itself may receive some updates. In these cases, it may be required that the image is rebuilt. To perform a complete rebuild of the InvenTree development image from local source, run the following command:
```
docker compose build --no-cache
```

211
docs/docs/start/docker_install.md Normal file
View File

@ -0,0 +1,211 @@
---
title: Docker Production Server
---
## Docker Production Server
The following guide provides a streamlined production InvenTree installation, with minimal configuration required.
!!! tip "Docker Installation"
This guide assumes that you have already installed [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/). If you have not yet installed Docker, please refer to the [official installation guide](https://docs.docker.com/get-docker/).
!!! info "Starting Point"
This setup guide should be considered a *starting point* - your particular production requirements vary from the example shown here.
!!! tip "Docker Theory"
Refer to the [docker theory section](./docker.md) for more information about how our docker installation works under the hood.
### Before You Start
!!! warning "Check the version"
Please make sure you are reading the [STABLE](https://docs.inventree.org/en/stable/start/docker/) documentation when using the stable docker image tags.
!!! warning "Docker Knowledge Required"
This guide assumes that you are reasonably comfortable with the basic concepts of docker and docker compose.
## Docker Installation
### Required Files
The following files required for this setup are provided with the InvenTree source, located in the `./docker/` directory of the [InvenTree source code](https://github.com/inventree/InvenTree/tree/master/docker/production):
| Filename | Description |
| --- | --- |
| [docker-compose.yml](https://github.com/inventree/InvenTree/blob/master/docker/docker-compose.yml) | The docker compose script |
| [.env](https://github.com/inventree/InvenTree/blob/master/docker/.env) | Environment variables |
| [Caddyfile](https://github.com/inventree/InvenTree/blob/master/docker/Caddyfile) | Caddy configuration file |
Download these files to a directory on your local machine.
!!! success "Working Directory"
This tutorial assumes you are working from a direction where all of these files are located.
!!! tip "No Source Required"
For a production setup you do not need the InvenTree source code. Simply download the three required files from the links above!
### Edit Environment Variables
The first step is to edit the environment variables, located in the `.env` file.
!!! warning "External Volume"
You must define the `INVENTREE_EXT_VOLUME` variable - this must point to a directory *on your local machine* where persistent data is to be stored.
!!! warning "Database Credentials"
You must also define the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`). You should ensure they are changed from the default values for added security
!!! info "Other Variables"
There are a number of other environment variables which can be set to customize the InvenTree installation. Refer to the [environment variables](./config.md) documentation for more information.
### Initial Database Setup
Perform the initial database setup by running the following command:
```bash
docker compose run --rm inventree-server invoke update
```
This command performs the following steps:
- Ensure required python packages are installed
- Create a new (empty) database
- Perform the required schema updates to create the required database tables
- Update translation files
- Update required static files
### Create Administrator Account
If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts:
```
docker compose run inventree-server invoke superuser
```
Alternatively, admin account details can be specified in the `.env` file, removing the need for this manual step:
| Variable | Description |
| --- | --- |
| INVENTREE_ADMIN_USER | Admin account username |
| INVENTREE_ADMIN_PASSWORD | Admin account password |
| INVENTREE_ADMIN_EMAIL | Admin account email address |
!!! warning "Scrub Account Data"
Ensure that the admin account credentials are removed from the `.env` file after the first run, for security.
### Start Docker Containers
Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers:
```
docker compose up -d
```
This command launches the following containers:
- `inventree-db` - PostgreSQL database
- `inventree-server` - InvenTree web server
- `inventree-worker` - Background worker
- `inventree-proxy` - Caddy reverse proxy
!!! success "Up and Running!"
You should now be able to view the InvenTree login screen at [http://inventree.localhost](http://inventree.localhost) (or whatever custom domain you have configured in the `.env` file).
## 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.
!!! tip "Docker Directory"
All `docker compose` commands must be performed in the same directory as the [docker-compose.yml file](#required-files)
!!! info "Tagged Version"
If you are targeting a particular "tagged" version of InvenTree, you may wish to edit the `INVENTREE_TAG` variable in the `.env` file before issuing the `docker compose pull` command
### Update Database
Run the following command to ensure that the InvenTree database is updated:
```
docker compose run --rm inventree-server invoke update
```
!!! info "Skip Backup"
By default, the `invoke update` command performs a database backup. To skip this step, add the `--skip-backup` flag
### Start Containers
Now restart the docker containers:
```
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.
Read more about [data backup](./backup.md).
### Exporting Database as JSON
To export the database to an agnostic JSON file, perform the following command:
```
docker compose run --rm inventree-server invoke export-records -f /home/inventree/data/data.json
```
This will export database records to the file `data.json` in your mounted volume directory.
## Further Configuration
### Custom Domain
By default, the InvenTree server is accessible at [http://inventree.localhost](http://inventree.localhost). If you wish to use a custom domain, you can edit the `.env` environment file to specify the domain name.
Look for the `INVENTREE_SITE_URL` variable, and set it to the desired domain name.
!!! tip "Configuration Options"
There are a number of other environment variables which can be set to customize the InvenTree installation. Refer to the [configuration documentation](./config.md) for more information.
### SSL Configuration
The provided `Caddyfile` configuration file is setup to enable [Automatic HTTPS](https://caddyserver.com/docs/automatic-https) "out of the box". All you have to do is specify a `https://` URL in the `INVENTREE_SITE_URL` variable.
The [Caddy](./docker.md#ssl-certificates) container will automatically generate SSL certificates for your domain.
#### Persistent Files
Any persistent files generated by the Caddy container (such as certificates, etc) will be stored in the `caddy` directory within the external volume.
### Demo Dataset
To quickly get started with a demo dataset, you can run the following command:
```
docker compose run --rm inventree-server invoke setup-test -i
```
This will install the InvenTree demo dataset into your instance.
To start afresh (and completely remove the existing database), run the following command:
```
docker compose run --rm inventree-server invoke delete-data
```

247
docs/docs/start/docker_prod.md
View File

@ -1,247 +0,0 @@
---
title: Docker Production Server
---
## Docker Production Server
The following guide provides a streamlined production InvenTree installation, with minimal configuration required.
!!! info "Starting Point"
This setup guide should be considered a *starting point*. It is likely that your particular production requirements will vary from the example shown here.
### Before You Start
!!! warning "Check the version"
Please make sure you are reading the [STABLE](https://docs.inventree.org/en/stable/start/docker_prod/) documentation when using the stable docker image tags.
!!! warning "Docker Skills Required"
This guide assumes that you are reasonably comfortable with the basic concepts of docker and docker compose.
#### Docker Image
This production setup guide uses the official InvenTree docker image, available from dockerhub.
!!! info "Stable Version"
The provided docker compose file targets `inventree:stable` by default.
#### Docker Compose
A sample [docker compose file](https://github.com/inventree/InvenTree/blob/master/docker/production/docker-compose.yml) is provided to sequence all the required processes.
!!! tip "Starting Point"
If you require a different configuration, use this docker compose file as a starting point.
#### Static and Media Files
The sample docker compose configuration outlined on this page uses nginx to serve static files and media files. If you change this configuration, you will need to ensure that static and media files are served correctly.
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details
#### Required Files
The following files required for this setup are provided with the InvenTree source, located in the `./docker/production` directory of the [InvenTree source code](https://github.com/inventree/InvenTree/tree/master/docker/production):
| Filename | Description |
| --- | --- |
| [docker-compose.yml](https://github.com/inventree/InvenTree/blob/master/docker/production/docker-compose.yml) | The docker compose script |
| [.env](https://github.com/inventree/InvenTree/blob/master/docker/production/.env) | Environment variables |
| [nginx.prod.conf](https://github.com/inventree/InvenTree/blob/master/docker/production/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 required files are all located in your working directory.
!!! tip "No Source Required"
For a production setup you do not need the InvenTree source code. Simply download the three required files from the links above!
### Containers
The example docker compose file launches the following containers:
| Container | Description |
| --- | --- |
| inventree-db | PostgreSQL database |
| inventree-server | Gunicorn web server |
| inventree-worker | django-q background worker |
| inventree-proxy | nginx proxy server |
| *inventree-cache* | *redis cache (optional)* |
#### PostgreSQL Database
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).
#### Web Server
Runs an InvenTree web server instance, powered by a Gunicorn web server.
#### Background Worker
Runs the InvenTree background worker process. This spins up a second instance of the *inventree* container, with a different entrypoint command.
#### Nginx Proxy
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).
#### Redis Cache
Redis is used as cache storage for the InvenTree server. This provides a more performant caching system which can useful in larger installations.
This container uses the official [redis image](https://hub.docker.com/_/redis).
!!! info "Redis on Docker"
Docker adds an additional network layer - that might lead to lower performance than bare metal.
To optimize and configure your redis deployment follow the [official docker guide](https://redis.io/docs/getting-started/install-stack/docker/#configuration).
!!! warning "Disabled by default"
The *redis* container is not enabled in the default configuration. This is provided as an example for users wishing to use redis.
To enable the *redis* container, run any `docker compose` commands with the `--profile redis` flag.
You will also need to un-comment the `INVENTREE_CACHE_<...>` variables in the `.env` file.
### Data Volume
InvenTree stores any persistent data (e.g. uploaded media files, database data, etc) in a [volume](https://docs.docker.com/storage/volumes/) which is mapped to a local system directory. The location of this directory must be configured in the `.env` file, specified using the `INVENTREE_EXT_VOLUME` variable.
!!! info "Data Directory"
Make sure you change the path to the local directory where you want persistent data to be stored.
#### Common Issues
When configuring a docker install, sometimes a misconfiguration can cause peculiar issues where it seems that the installation is functioning correctly, but uploaded files and plugins do not "persist" across sessions. In such cases, the "mounted" volume has not mapped to a directory on your local filesystem. This may occur if you have tried multiple setup options without clearing existing volume bindings.
!!! tip "Start with a clean slate"
To prevent such issues, it is recommended that you start with a "clean slate" if you have previously configured an InvenTree installation under docker.
If you have previously setup InvenTree, remove existing volume bindings using the following command:
```docker volume rm -f inventree-production_inventree_data```
## Production Setup Guide
### Edit Environment Variables
The first step is to edit the environment variables, located in the `.env` file.
!!! warning "External Volume"
You must define the `INVENTREE_EXT_VOLUME` variable - this must point to a directory *on your local machine* where persistent data is to be stored.
!!! warning "Database Credentials"
You must also define the database username (`INVENTREE_DB_USER`) and password (`INVENTREE_DB_PASSWORD`). You should ensure they are changed from the default values for added security
### Initial Database Setup
Perform the initial database setup by running the following command:
```bash
docker compose run inventree-server invoke update
```
This command performs the following steps:
- Ensure required python packages are installed
- Create a new (empty) database
- Perform the required schema updates to create the required database tables
- Update translation files
- Collect all required static files into a directory where they can be served by nginx
### Create Administrator Account
If you are creating the initial database, you need to create an admin (superuser) account for the database. Run the command below, and follow the prompts:
```
docker compose run inventree-server invoke superuser
```
Alternatively, admin account details can be specified in the `.env` file, removing the need for this manual step:
| Variable | Description |
| --- | --- |
| INVENTREE_ADMIN_USER | Admin account username |
| INVENTREE_ADMIN_PASSWORD | Admin account password |
| INVENTREE_ADMIN_EMAIL | Admin account email address |
!!! warning "Scrub Account Data"
Ensure that the admin account credentials are removed from the `.env` file after the first run, for security.
### Start Docker Containers
Now that the database has been created, migrations applied, and you have created an admin account, we are ready to launch the InvenTree containers:
```
docker compose up -d
```
This command launches the following containers:
- `inventree-db` - PostgreSQL database
- `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.
!!! tip "Docker Directory"
All `docker compose` commands must be performed in the same directory as the [docker-compose.yml file](#required-files)
!!! info "Tagged Version"
If you are targeting a particular "tagged" version of InvenTree, you may wish to edit the `INVENTREE_TAG` variable in the `.env` file before issuing the `docker compose pull` command
### Update Database
Run the following command to ensure that the InvenTree database is updated:
```
docker compose run inventree-server invoke update
```
!!! info "Skip Backup"
By default, the `invoke update` command performs a database backup. To skip this step, add the `--skip-backup` flag
### Start Containers
Now restart the docker containers:
```
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.
Read more about [data backup](./backup.md).
### 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 -f /home/inventree/data/data.json
```
This will export database records to the file `data.json` in your mounted volume directory.

106
docs/docs/start/intro.md
View File

@ -2,71 +2,78 @@
title: Setup Introduction
---
!!! info "Fast install"
A quick-and-easy install can be done done with the following one-liner.
```bash
wget -qO install.sh https://get.inventree.org && bash install.sh
```
Read more about the [installer](./installer.md).
## Introduction
InvenTree can be self-hosted with minimal system requirements. Multiple database back-ends are supported, allowing for flexibility where required.
A functional InvenTree server can be hosted with minimal setup requirements. Multiple installation methods and database back-ends are supported, allowing for flexibility where required.
!!! info "Production Ready"
InvenTree is designed to be a production-ready application, and can be deployed in a variety of environments. The following instructions are designed to help you get started with a *production* setup. For a development setup, refer to the [development setup guide](../develop/starting.md).
## Installation Methods
To quickly jump to a specific installation method, refer to the following links:
- [**Docker**](./docker.md)
- [**Package Installer**](./installer.md)
- [**Bare Metal**](./install.md)
!!! success "Docker Recommended"
The recommended method of installing InvenTree is to follow our [docker setup guide](./docker.md). 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.
!!! info "Further Reading"
For more information on the InvenTree tech stack, continue reading below!
### Configuration Options
Independent of the preferred installation method, InvenTree provides a number of [configuration options](./config.md) which can be used to customize the server environment.
## System Components
The InvenTree server ecosystem consists of the following components:
### Database
A persistent database is required for data storage. InvenTree can be used with any of the following database backends:
A persistent database is required for data storage. By default, InvenTree is configured to use [PostgreSQL](https://www.postgresql.org/) - and this is the recommended database backend to use. However, InvenTree can also be configured to connect to any database backend [supported by Django]({% include "django.html" %}/ref/databases/)
* PostgreSQL
* MySQL / MariaDB
* SQLite
!!! warning "SQLite"
While SQLite provides a simpler setup and is useful for a development environment, we strongly recommend against using it for a production environment. Use PostgreSQL or MySQL instead
Database selection should be determined by your particular installation requirements.
### Media Files
Uploaded media files (images, attachments, reports, etc) are stored to a persistent storage volume.
### Web Server
The bulk of the InvenTree code base supports the custom web server application. The web server application services user requests and facilitates database access.
The bulk of the InvenTree code base supports the custom web server application. The web server application services user requests and facilitates database access. The webserver provides access to the [API](../api/api.md) for performing database query actions.
The webserver code also provides a first-party API for performing database query actions.
Once a database is setup, you need a way of accessing the data. InvenTree provides a "server" application out of the box, but this may not scale particularly well with multiple users. Instead, InvenTree can be served using a webserver such as [Gunicorn](https://gunicorn.org/). For more information see the [deployment documentation](./bare_prod.md).
InvenTree uses [Gunicorn](https://gunicorn.org/) as the web server - a Python WSGI HTTP server.
### Background Tasks
A separate application handles management of [background tasks](../settings/tasks.md), separate to user-facing web requests.
A separate application handles management of [background tasks](../settings/tasks.md), separate to user-facing web requests. The background task manager is required to perform asynchronous tasks, such as sending emails, generating reports, and other long-running tasks.
InvenTree uses [django-q2](https://django-q2.readthedocs.io/en/master/) as the background task manager.
### File Storage
Uploaded *media* files (images, attachments, reports, etc) and *static* files (javascript, html) are stored to a persistent storage volume. A *file server* is required to serve these files to the user.
InvenTree uses [Caddy](https://caddyserver.com/) as a file server, which is configured to serve both *static* and *media* files. Additionally, Caddy provides SSL termination and reverse proxy services.
## OS Requirements
The InvenTree documentation assumes that the operating system is a debian based Linux OS. Some installation steps may differ for different systems.
The InvenTree documentation *assumes* that the operating system is a debian based Linux OS. Some installation steps may differ for different systems.
!!! warning "Installing on Windows"
Installation on Windows is *not guaranteed* to work (at all). To install on a Windows system, it is highly recommended that you [install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10#manual-installation-steps), and then follow installation procedure from within the WSL environment.
To install on a Windows system, you should [install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10#manual-installation-steps), and then follow installation procedure from within the WSL environment.
!!! success "Docker"
Installation on any OS is simplified by following the [docker setup guide](../docker).
Installation on any OS is simplified by following the [docker setup guide](./docker.md).
## Python Requirements
InvenTree runs on [Python](https://python.org).
!!! warning "Python Version"
InvenTree requires Python 3.9 (or newer). If your system has an older version of Python installed, you will need to follow the update instructions for your OS.
InvenTree requires a minimum Python version of {{ config.extra.min_python_version}}. If your system has an older version of Python installed, you will need to follow the update instructions for your OS.
### Invoke
InvenTree makes use of the [invoke](https://www.pyinvoke.org/) python toolkit for performing various administrative actions.
!!! warning "Invoke Version"
InvenTree requires invoke version 2.0.0 or newer. Some platforms may be shipped with older versions of invoke!
InvenTree requires invoke version {{ config.extra.min_invoke_version }} or newer. Some platforms may be shipped with older versions of invoke!
!!! tip "Updating Invoke"
To update your invoke version, run `pip install -U invoke`
@ -102,12 +109,8 @@ To configure Inventree inside a virtual environment, ``cd`` into the inventree b
source env/bin/activate
```
!!! info "Activate Virtual Environment"
if
```
source env/bin/activate
```
is not working try
Or, if that does not work, try:
```
. env/bin/activate
```
@ -127,31 +130,10 @@ Alternatively, the source can be downloaded as a [.zip archive](https://github.c
!!! info "Updating via Git"
Downloading the source code using Git is recommended, as it allows for simple updates when a new version of InvenTree is released.
## Installation Guides
There are multiple ways to get an InvenTree server up and running, of various complexity (and robustness)!
### Docker
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 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 following guides for further instructions:
- [**Bare metal development server setup guide**](./bare_dev.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).
By default, a production InvenTree installation is configured to run with [DEBUG mode]({% include "django.html" %}/ref/settings/#std:setting-DEBUG) *disabled*.
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.

23
docs/docs/start/serving_files.md
View File

@ -4,25 +4,26 @@ title: Serving Static and Media Files
## Serving Files
In production, the InvenTree web server software *does not* provide hosting of static files, or user-uploaded (media) files.
In a production installation, the InvenTree web server application *does not* provide hosting of static files, or user-uploaded (media) files. Instead, these files should be served by a separate web server, such as [Caddy](https://caddyserver.com/), [Nginx](https://www.nginx.com/), or [Apache](https://httpd.apache.org/).
!!! info "Debug Mode"
When running in [production mode](./bare_prod.md) (i.e. the `INVENTREE_DEBUG` flag is disabled), a separate web server is required for serving *static* and *media* files. In `DEBUG` mode, the django webserver facilitates delivery of *static* and *media* files, but this is explicitly not suitable for a production environment.
!!! into "Read More"
You can find further information in the [django documentation](https://docs.djangoproject.com/en/dev/howto/static-files/deployment/).
!!! tip "Read More"
You can find further information in the [django documentation]({% include "django.html" %}/howto/static-files/deployment/).
There are *many* different ways that a sysadmin might wish to handle this - and it depends on your particular installation requirements.
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
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
### Media Files
It is highly recommended that the *media* files are served in such a way that user authentication is required.
It is highly recommended that the *media* files are served behind an authentication layer. This is because the media files are user-uploaded, and may contain sensitive information. Most modern web servers provide a way to serve files behind an authentication layer.
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.
### Example Configuration
The [docker production example](./docker.md) provides an example using [Caddy](https://caddyserver.com) to serve *static* and *media* files, and redirecting other requests to the InvenTree web server itself.
Caddy is a modern web server which is easy to configure and provides a number of useful features, including automatic SSL certificate generation.

11
docs/mkdocs.yml
View File

@ -8,6 +8,7 @@ site_author: InvenTree
repo_url: https://github.com/inventree/inventree
repo_name: inventree/inventree
# Theme
theme:
name: material
@ -34,6 +35,7 @@ theme:
icon:
repo: fontawesome/brands/github
features:
- content.code.copy
- header.autohide
- navigation.expand
- navigation.footer
@ -78,7 +80,7 @@ nav:
- Getting started: develop/starting.md
- Contributing: develop/contributing.md
- Devcontainer: develop/devcontainer.md
- Platform UI: develop/react-frontend.md
- React Frontend: develop/react-frontend.md
- Credits: credits.md
- Privacy: privacy.md
- Release Notes: releases/release_notes.md
@ -87,8 +89,7 @@ nav:
- Configuration: start/config.md
- Docker:
- Introduction: start/docker.md
- Production: start/docker_prod.md
- Development: start/docker_dev.md
- Installation: start/docker_install.md
- Bare Metal:
- Introduction: start/install.md
- Installer: start/installer.md
@ -274,6 +275,10 @@ extra:
# provider: google
# property: UA-143467500-1
min_python_version: 3.9
min_invoke_version: 2.0.0
django_version: 4.2
version:
default: stable
provider: mike

13
docs/mlc_config.json Normal file
View File

@ -0,0 +1,13 @@
{
"ignorePatterns": [
{
"pattern": "http://inventree.localhost"
},
{
"pattern": "http://localhost"
},
{
"pattern": "http://127.0.0.1"
}
]
}

2
requirements.in
View File

@ -45,7 +45,7 @@ python-barcode[images] # Barcode generator
python-dotenv # Environment variable management
pyyaml>=6.0.1 # YAML parsing
qrcode[pil] # QR code generator
rapidfuzz==0.7.6 # Fuzzy string matching
rapidfuzz # Fuzzy string matching
regex # Advanced regular expressions
sentry-sdk # Error reporting (optional)
setuptools # Standard dependency

2
requirements.txt
View File

@ -274,7 +274,7 @@ pyyaml==6.0.1
# tablib
qrcode==7.4.2
# via django-allauth-2fa
rapidfuzz==0.7.6
rapidfuzz==3.6.1
redis==5.0.1
# via django-redis
referencing==0.33.0

21
tasks.py
View File

@ -207,8 +207,8 @@ def check_file_existance(filename: str, overwrite: bool = False):
# Install tasks
@task(help={'nouv': 'Do not use UV'})
def plugins(c, nouv=False):
@task(help={'uv': 'Use UV (experimental package manager)'})
def plugins(c, uv=False):
"""Installs all plugins as specified in 'plugins.txt'."""
from InvenTree.InvenTree.config import get_plugin_file
@ -217,20 +217,20 @@ def plugins(c, nouv=False):
print(f"Installing plugin packages from '{plugin_file}'")
# Install the plugins
if nouv:
if not uv:
c.run(f"pip3 install --disable-pip-version-check -U -r '{plugin_file}'")
else:
c.run('pip3 install --no-cache-dir --disable-pip-version-check uv')
c.run(f"uv pip install -r '{plugin_file}'")
@task(post=[plugins], help={'nouv': 'Do not use UV'})
def install(c, nouv=False):
@task(help={'uv': 'Use UV package manager (experimental)'})
def install(c, uv=False):
"""Installs required python packages."""
print("Installing required python packages from 'requirements.txt'")
# Install required Python packages with PIP
if nouv:
if not uv:
c.run('pip3 install --upgrade pip')
c.run('pip3 install --upgrade setuptools')
c.run(
@ -241,6 +241,9 @@ def install(c, nouv=False):
c.run('uv pip install --upgrade setuptools')
c.run('uv pip install -U -r requirements.txt')
# Run plugins install
plugins(c, uv=uv)
@task(help={'tests': 'Set up test dataset at the end'})
def setup_dev(c, tests=False):
@ -305,7 +308,7 @@ def static(c, frontend=False):
frontend_build(c)
print('Collecting static files...')
manage(c, 'collectstatic --no-input --clear')
manage(c, 'collectstatic --no-input --clear --verbosity 0')
@task
@ -389,6 +392,7 @@ def migrate(c):
'frontend': 'Force frontend compilation/download step (ignores INVENTREE_DOCKER)',
'no_frontend': 'Skip frontend compilation/download step',
'skip_static': 'Skip static file collection step',
'uv': 'Use UV (experimental package manager)',
},
)
def update(
@ -397,6 +401,7 @@ def update(
frontend: bool = False,
no_frontend: bool = False,
skip_static: bool = False,
uv: bool = False,
):
"""Update InvenTree installation.
@ -414,7 +419,7 @@ def update(
- translate_stats
"""
# Ensure required components are installed
install(c)
install(c, uv=uv)
if not skip_backup:
backup(c)