inventree/InvenTree
2
0
Fork 0
mirror of https://github.com/inventree/InvenTree.git synced 2025-06-16 20:15:44 +00:00
Code Activity

Merge branch 'master' of https://github.com/inventree/InvenTree into pui-only

Browse Source
This commit is contained in:
Matthias Mair
2024-11-10 00:39:43 +01:00
parent 536850b046 255a5d083e
commit 7c36e5bc8b
263 changed files with 72514 additions and 56235 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/docs/assets/images/stock/stock_external_icon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

39
docs/docs/develop/react-frontend.md
View File

@ -1,11 +1,20 @@
---
title: Platform UI / React
title: React Frontend Development
---
## Setup
The new React-based UI will not be available by default. In order to set your development environment up to view the frontend, follow this guide.
The new UI requires a separate frontend server to run to serve data for the new Frontend.
The following documentation details how to setup and run a development installation of the InvenTree frontend user interface.
### Prerequisites
To run the frontend development server, you will need to have the following installed:
- Node.js
- Yarn
!!! note "Devcontainer"
The [devcontainer](./devcontainer.md) setup already includes all prerequisite packages, and is ready to run the frontend server.
### Install
@ -79,3 +88,27 @@ When running the frontend development server, some features may not work entirel
#### SSO Login
When logging into the frontend dev server via SSO, the redirect URL may not redirect correctly.
## Testing
The frontend codebase it tested using [Playwright](https://playwright.dev/). There are a large number of tests that cover the frontend codebase, which are run automatically as part of the CI pipeline.
### Install Playwright
To install the required packages to run the tests, you can use the following command:
```bash
cd src/frontend
npx playwright install
```
### Running Tests
To run the tests locally, in an interactive editor, you can use the following command:
```bash
cd src/frontend
npx playwright test --ui
```
This will first launch the backend server (at `http://localhost:8000`), and then run the tests against the frontend server (at `http://localhost:5173`). An interactive browser window will open, and you can run the tests individually or as a group.

222
docs/docs/extend/plugins/ui.md
View File

@ -4,19 +4,104 @@ title: User Interface Mixin
## User Interface Mixin
The *User Interface* mixin class provides a set of methods to implement custom functionality for the InvenTree web interface.
The `UserInterfaceMixin` class provides a set of methods to implement custom functionality for the InvenTree web interface.
### Enable User Interface Mixin
To enable user interface plugins, the global setting `ENABLE_PLUGINS_INTERFACE` must be enabled, in the [plugin settings](../../settings/global.md#plugin-settings).
## Plugin Context
## Custom UI Features
When rendering certain content in the user interface, the rendering functions are passed a `context` object which contains information about the current page being rendered. The type of the `context` object is defined in the `PluginContext` file:
The InvenTree user interface functionality can be extended in various ways using plugins. Multiple types of user interface *features* can be added to the InvenTree user interface.
{{ includefile("src/frontend/src/components/plugins/PluginContext.tsx", title="Plugin Context", fmt="javascript") }}
The entrypoint for user interface plugins is the `UserInterfaceMixin` class, which provides a number of methods which can be overridden to provide custom functionality. The `get_ui_features` method is used to extract available user interface features from the plugin:
## Custom Panels
::: plugin.base.ui.mixins.UserInterfaceMixin.get_ui_features
options:
show_bases: False
show_root_heading: False
show_root_toc_entry: False
show_sources: True
summary: False
members: []
Note here that the `get_ui_features` calls other methods to extract the available features from the plugin, based on the requested feature type. These methods can be overridden to provide custom functionality.
!!! info "Implementation"
Your custom plugin does not need to override the `get_ui_features` method. Instead, override one of the other methods to provide custom functionality.
### UIFeature Return Type
The `get_ui_features` method should return a list of `UIFeature` objects, which define the available user interface features for the plugin. The `UIFeature` class is defined as follows:
::: plugin.base.ui.mixins.UIFeature
options:
show_bases: False
show_root_heading: False
show_root_toc_entry: False
show_sources: True
summary: False
members: []
Note that the *options* field contains fields which may be specific to a particular feature type - read the documentation below on each feature type for more information.
### Dynamic Feature Loading
Each of the provided feature types can be loaded dynamically by the plugin, based on the information provided in the API request. For example, the plugin can choose to show or hide a particular feature based on the user permissions, or the current state of the system.
For examples of this dynamic feature loading, refer to the [sample plugin](#sample-plugin) implementation which demonstrates how to dynamically load custom panels based on the provided context.
### Javascript Source Files
The rendering function for the custom user interface features expect that the plugin provides a Javascript source file which contains the necessary code to render the custom content. The path to this file should be provided in the `source` field of the `UIFeature` object.
Note that the `source` field can include the name of the function to be called (if this differs from the expected default function name).
For example:
```
"source": "/static/plugins/my_plugin/my_plugin.js:my_custom_function"
```
## Available UI Feature Types
The following user interface feature types are available:
### Dashboard Items
The InvenTree dashboard is a collection of "items" which are displayed on the main dashboard page. Custom dashboard items can be added to the dashboard by implementing the `get_ui_dashboard_items` method:
::: plugin.base.ui.mixins.UserInterfaceMixin.get_ui_dashboard_items
options:
show_bases: False
show_root_heading: False
show_root_toc_entry: False
show_sources: True
summary: False
members: []
#### Dashboard Item Options
The *options* field in the returned `UIFeature` object can contain the following properties:
::: plugin.base.ui.mixins.CustomDashboardItemOptions
options:
show_bases: False
show_root_heading: False
show_root_toc_entry: False
show_sources: True
summary: False
members: []
#### Source Function
The frontend code expects a path to a javascript file containing a function named `renderDashboardItem` which will be called to render the custom dashboard item. Note that this function name can be overridden by appending the function name in the `source` field of the `UIFeature` object.
#### Example
Refer to the [sample plugin](#sample-plugin) for an example of how to implement server side rendering for custom panels.
### Panels
Many of the pages in the InvenTree web interface are built using a series of "panels" which are displayed on the page. Custom panels can be added to these pages, by implementing the `get_ui_panels` method:
@ -29,71 +114,11 @@ Many of the pages in the InvenTree web interface are built using a series of "pa
summary: False
members: []
The custom panels can display content which is generated either on the server side, or on the client side (see below).
#### Panel Options
### Server Side Rendering
The *options* field in the returned `UIFeature` object can contain the following properties:
The panel content can be generated on the server side, by returning a 'content' attribute in the response. This 'content' attribute is expected to be raw HTML, and is rendered directly into the page. This is particularly useful for displaying static content.
Server-side rendering is simple to implement, and can make use of the powerful Django templating system.
Refer to the [sample plugin](#sample-plugin) for an example of how to implement server side rendering for custom panels.
**Advantages:**
- Simple to implement
- Can use Django templates to render content
- Has access to the full InvenTree database, and content not available on the client side (via the API)
**Disadvantages:**
- Content is rendered on the server side, and cannot be updated without a page refresh
- Content is not interactive
### Client Side Rendering
The panel content can also be generated on the client side, by returning a 'source' attribute in the response. This 'source' attribute is expected to be a URL which points to a JavaScript file which will be loaded by the client.
Refer to the [sample plugin](#sample-plugin) for an example of how to implement client side rendering for custom panels.
#### Panel Render Function
The JavaScript file must implement a `renderPanel` function, which is called by the client when the panel is rendered. This function is passed two parameters:
- `target`: The HTML element which the panel content should be rendered into
- `context`: A dictionary of context data which can be used to render the panel content
**Example**
```javascript
export function renderPanel(target, context) {
target.innerHTML = "<h1>Hello, world!</h1>";
}
```
#### Panel Visibility Function
The JavaScript file can also implement a `isPanelHidden` function, which is called by the client to determine if the panel is displayed. This function is passed a single parameter, *context* - which is the same as the context data passed to the `renderPanel` function.
The `isPanelHidden` function should return a boolean value, which determines if the panel is displayed or not, based on the context data.
If the `isPanelHidden` function is not implemented, the panel will be displayed by default.
**Example**
```javascript
export function isPanelHidden(context) {
// Only visible for active parts
return context.model == 'part' && context.instance?.active;
}
```
## Custom UI Functions
User interface plugins can also provide additional user interface functions. These functions can be provided via the `get_ui_features` method:
::: plugin.base.ui.mixins.UserInterfaceMixin.get_ui_features
::: plugin.base.ui.mixins.CustomPanelOptions
options:
show_bases: False
show_root_heading: False
@ -102,36 +127,55 @@ User interface plugins can also provide additional user interface functions. The
summary: False
members: []
::: plugin.samples.integration.user_interface_sample.SampleUserInterfacePlugin.get_ui_features
#### Source Function
The frontend code expects a path to a javascript file containing a function named `renderPanel` which will be called to render the custom panel. Note that this function name can be overridden by appending the function name in the `source` field of the `UIFeature` object.
#### Example
Refer to the [sample plugin](#sample-plugin) for an example of how to implement server side rendering for custom panels.
### Template Editors
The `get_ui_template_editors` feature type can be used to provide custom template editors.
::: plugin.base.ui.mixins.UserInterfaceMixin.get_ui_template_editors
options:
show_bases: False
show_root_heading: False
show_root_toc_entry: False
show_source: True
members: []
Currently the following functions can be extended:
### Template editors
The `template_editor` feature type can be used to provide custom template editors.
**Example:**
{{ includefile("src/backend/InvenTree/plugin/samples/static/plugin/sample_template.js", title="sample_template.js", fmt="javascript") }}
show_bases: False
show_root_heading: False
show_root_toc_entry: False
show_sources: True
summary: False
members: []
### Template previews
The `template_preview` feature type can be used to provide custom template previews. For an example see:
The `get_ui_template_previews` feature type can be used to provide custom template previews:
**Example:**
::: plugin.base.ui.mixins.UserInterfaceMixin.get_ui_template_previews
options:
show_bases: False
show_root_heading: False
show_root_toc_entry: False
show_sources: True
summary: False
members: []
{{ includefile("src/backend/InvenTree/plugin/samples/static/plugin/sample_template.js", title="sample_template.js", fmt="javascript") }}
## Plugin Context
When rendering certain content in the user interface, the rendering functions are passed a `context` object which contains information about the current page being rendered. The type of the `context` object is defined in the `PluginContext` file:
{{ includefile("src/frontend/src/components/plugins/PluginContext.tsx", title="Plugin Context", fmt="javascript") }}
This context data can be used to provide additional information to the rendering functions, and can be used to dynamically render content based on the current state of the system.
### Additional Context
Note that additional context can be passed to the rendering functions by adding additional key-value pairs to the `context` field in the `UIFeature` return type (provided by the backend via the API). This field is optional, and can be used at the discretion of the plugin developer.
## Sample Plugin
A sample plugin which implements custom user interface functionality is provided in the InvenTree source code:
A sample plugin which implements custom user interface functionality is provided in the InvenTree source code, which provides a full working example of how to implement custom user interface functionality.
::: plugin.samples.integration.user_interface_sample.SampleUserInterfacePlugin
options:

8
docs/docs/order/purchase_order.md
View File

@ -93,6 +93,14 @@ There are two options to mark items as "received":
!!! note "Permissions"
Marking line items as received requires the "Purchase order" ADD permission.
### Item Location
When receiving items from a purchase order, the location of the items must be specified. There are multiple ways to specify the location:
* **Order Destination**: The *destination* field of the purchase order can be set to a specific location. When receiving items, the location will default to the destination location.
* **Line Item Location**: Each line item can have a specific location set. When receiving items, the location will default to the line item location. *Note: A destination specified at the line item level will override the destination specified at the order level.*
### Received Items
Each item marked as "received" is automatically converted into a stock item.

4
docs/docs/start/bare_dev.md
View File

@ -40,7 +40,7 @@ To enable access to the InvenTree server from other computers on a local network
## Background Worker
The background task manager must also be started. The InvenTree server is already running in the foreground, so open a *new shell window* to start the server.
The [background task manager](./processes.md#background-worker) must also be started. The InvenTree server is already running in the foreground, so open a *new shell window* to start the server.
### Activate Virtual Environment
@ -55,4 +55,4 @@ source ./env/bin/activate
(env) invoke worker
```
This will start the background process manager in the current shell.
This will start an instance of the background worker in the current shell.

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

@ -19,7 +19,7 @@ The InvenTree web server is hosted using [Gunicorn](https://gunicorn.org/). Guni
### Supervisor
[Supervisor](http://supervisord.org/) is a process control system which monitors and controls multiple background processes. It is used in the InvenTree production setup to ensure that the server and background worker processes are always running.
[Supervisor](http://supervisord.org/) is a process control system which monitors and controls multiple background processes. It is used in the InvenTree production setup to ensure that the [web server](./processes.md#web-server) and [background worker](./processes.md#background-worker) processes are always running.
## Gunicorn
@ -98,11 +98,12 @@ The InvenTree server (and background task manager) should now be running!
In addition to the InvenTree server, you will need a method of delivering static and media files (this is *not* handled by the InvenTree server in a production environment).
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details
Refer to the [proxy server documentation](./processes.md#proxy-server) for more details
### 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 [caddy](https://caddyserver.com/), or [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](./processes.md#proxy-server) 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!

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

@ -279,12 +279,12 @@ InvenTree requires some external directories for storing files:
| Environment Variable | Configuration File | Description | Default |
| --- | --- | --- | --- |
| 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_STATIC_ROOT | static_root | [Static files](./processes.md#static-files) directory | *Not specified* |
| INVENTREE_MEDIA_ROOT | media_root | [Media files](./processes.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
Read the [proxy server documentation](./processes.md#proxy-server) for more information on hosting *static* and *media* files
### Static File Storage
@ -369,6 +369,15 @@ The logo and custom messages can be changed/set:
| INVENTREE_CUSTOMIZE | customize.navbar_message | Custom message for navbar | *Not specified* |
| INVENTREE_CUSTOMIZE | customize.hide_pui_banner | Disable PUI banner | False |
The INVENTREE_CUSTOMIZE environment variable must contain a json object with the keys from the table above and
the wanted values. Example:
```
INVENTREE_CUSTOMIZE={"login_message":"Hallo Michi","hide_pui_banner":"True"}
```
This example removes the PUI banner and sets a login message. Take care of the double quotes.
If you want to remove the InvenTree branding as far as possible from your end-user also check the [global server settings](../settings/global.md#server-settings).
!!! info "Custom Splash Screen Path"

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

@ -87,7 +87,7 @@ Plugins are supported natively when running under docker. There are two ways to
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.
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details
Refer to the [proxy server documentation](./processes.md#proxy-server) for more details
### SSL Certificates
@ -99,45 +99,11 @@ 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.
#### Proxy 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).
!!! info "Nginx Proxy"
An alternative is to run nginx as the reverse proxy. A sample configuration file is provided in the `./contrib/container/` source directory.
#### 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).
!!! tip "Enable Cache"
While a redis container is provided in the default configuration, by default it is not enabled in the Inventree server. You can enable redis cache support by following the [caching configuration guide](./config.md#caching)
| inventree-db | [PostgreSQL database](./processes.md#database) |
| inventree-server | [InvenTree web server](./processes.md#web-server) |
| inventree-worker | [django-q background worker](./processes.md#background-worker) |
| inventree-proxy | [Caddy file server and reverse proxy](./processes.md#proxy-server) |
| *inventree-cache* | [*redis cache (optional)*](./processes.md#cache-server) |
### Data Volume

12
docs/docs/start/docker_install.md
View File

@ -37,6 +37,9 @@ The following files required for this setup are provided with the InvenTree sour
Download these files to a directory on your local machine.
!!! warning "File Extensions"
If your computer adds *.txt* extensions to any of the downloaded files, rename the file and remove the added extension before continuing!
!!! success "Working Directory"
This tutorial assumes you are working from a directory where all of these files are located.
@ -101,10 +104,11 @@ 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
- `inventree-db` - [PostgreSQL database](./processes.md#database)
- `inventree-server` - [InvenTree web server](./processes.md#web-server)
- `inventree-worker` - [Background worker](./processes.md#background-worker)
- `inventree-proxy` - [Caddy reverse proxy](./processes.md#proxy-server)
- `inventree-cache` - [Redis cache](./processes.md#cache-server)
!!! 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).

4
docs/docs/start/install.md
View File

@ -66,14 +66,14 @@ In addition to the location where the InvenTree source code is located, you will
InvenTree requires a directory for storage of [static files](./config.md#static-file-storage).
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details
Refer to the [proxy server documentation](./processes.md#proxy-server) for more details
#### Media Files
InvenTree requires a directory for storage of [user uploaded files](./config.md#uploaded-file-storage)
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details
Refer to the [proxy server documentation](./processes.md#proxy-server) for more details
#### Backup Directory

5
docs/docs/start/installer.md
View File

@ -132,11 +132,14 @@ To update InvenTree run `apt install --only-upgrade inventree` - this might need
## Controlling InvenTree
### Services
InvenTree installs multiple services that can be controlled with your local system runner (`service` or `systemctl`).
The service `inventree` controls everything, `inventree-web` the (internal) webserver and `inventree-worker` the background worker(s).
The service `inventree` controls everything, `inventree-web` (the [InvenTree web server](./processes.md#web-server)) and `inventree-worker` the [background worker(s)](./processes.md#background-worker).
More instances of the worker can be instantiated from the command line. This is only meant for advanced users.
This sample script launches 3 services. By default, 1 is launched.
```bash
inventree scale worker=3
```

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

@ -29,30 +29,7 @@ Independent of the preferred installation method, InvenTree provides a number of
## System Components
The InvenTree server ecosystem consists of the following components:
### Database
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/)
### 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 webserver provides access to the [API](../api/api.md) for performing database query actions.
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. 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.
The InvenTree software stack is composed of multiple components, each of which is required for a fully functional server environment. Your can read more about the [InvenTree processes here](./processes.md).
## OS Requirements
@ -132,4 +109,4 @@ So, for a production setup, you should set `INVENTREE_DEBUG=false` in the [confi
Turning off DEBUG mode creates further work for the system administrator. In particular, when running in DEBUG mode, the InvenTree web server natively manages *static* and *media* files, which means that the InvenTree server can run "monolithically" without the need for a separate web server.
!!! info "Read More"
Refer to the [Serving Files](./serving_files.md) section for more details
Refer to the [proxy server documentation](./processes.md#proxy-server) for more details

103
docs/docs/start/processes.md Normal file
View File

@ -0,0 +1,103 @@
---
title: InvenTree Processes
---
## InvenTree Processes
InvenTree is a complex application, and there are a number of processes which must be running in order for the system to operate correctly. Typically, these processes are started automatically when the InvenTree application stack is launched. However, in some cases, it may be necessary to start these processes manually.
System administrators should be aware of the following processes when configuring an InvenTree installation:
### Database
At the core of the InvenTree application is the SQL database. The database is responsible for storing all of the persistent data which is used by the InvenTree application.
InvenTree supports a [number of database backends]({% include "django.html" %}/ref/databases) - which typically require their own process to be running.
Refer to the [database configuration guide](./config.md#database-options) for more information on selecting and configuring the database backend.
In running InvenTree via [docker compose](./docker_install.md), the database process is managed by the `inventree-db` service which provides a [Postgres docker container](https://hub.docker.com/_/postgres).
### Web Server
The InvenTree web server is responsible for serving the InvenTree web interface to users. The web server is a [Django](https://www.djangoproject.com/) application, which is run using the [Gunicorn](https://gunicorn.org/) WSGI server.
The web server interfaces with the backend database and provides a [REST API](../api/api.md) (via the [Django REST framework](https://www.django-rest-framework.org/)) which is used by the frontend web interface.
In running InvenTree via [docker compose](./docker_install.md), the web server process is managed by the `inventree-server` service, which runs from a custom docker image.
### Proxy Server
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.
!!! tip "Read More"
You can find further information in the [django documentation]({% include "django.html" %}/howto/static-files/deployment/).
A proxy server is required to store and serve static files (such as images, documents, etc) which are used by the InvenTree application. As django is not designed to serve static files in a production environment, a separate file server is required. For our docker compose setup, we use the `inventree-proxy` service, which runs a [Caddy](https://caddyserver.com/) proxy server to serve static files.
In addition to serving static files, the proxy server also provides a reverse proxy to the InvenTree web server, allowing the InvenTree web interface to be accessed via a standard HTTP/HTTPS port.
Further, it provides an authentication endpoint for accessing files in the `/static/` and `/media/` directories.
Finally, it provides a [Let's Encrypt](https://letsencrypt.org/) endpoint for automatic SSL certificate generation and renewal.
#### Static Files
Static files can be served without any need for authentication. In fact, they must be accessible *without* authentication, otherwise the unauthenticated views (such as the login screen) will not function correctly.
#### Media Files
It is highly recommended that the *media* files are served 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.
#### 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.
#### Alternatives to Caddy
An alternative is to run nginx as the reverse proxy. A sample configuration file is provided in the `./contrib/container/` source directory.
#### Integrating with Existing Proxy
You may wish to integrate the InvenTree web server with an existing reverse proxy server. This is possible, but requires careful configuration to ensure that the static and media files are served correctly.
*Note: A custom configuration of the proxy server is outside the scope of this documentation!*
### Background Worker
The InvenTree background worker is responsible for handling [asynchronous tasks](../settings/tasks.md) which are not suitable for the main web server process. This includes tasks such as sending emails, generating reports, and other long-running tasks.
InvenTree uses the [django-q2](https://django-q2.readthedocs.io/en/master/) package to manage background tasks.
The background worker process is managed by the `inventree-worker` service in the [docker compose](./docker_install.md) setup. Note that this services runs a duplicate copy of the `inventree-server` container, but with a different entrypoint command which starts the background worker process.
#### Important Information
If the background worker process is not running, InvenTree will not be able to perform background tasks. This can lead to issues such as emails not being sent, or reports not being generated. Additionally, certain data may not be updated correctly if the background worker is not running.
!!! warning "Background Worker"
The background worker process is a critical part of the InvenTree application stack. It is important that this process is running correctly in order for the InvenTree application to operate correctly.
#### Limitations
If the [cache server](#cache-server) is not running, the background worker will be limited to running a single threaded worker. This is because the background worker uses the cache server to manage task locking, and without a global cache server to communicate between processes, concurrency issues can occur.
### Cache Server
The InvenTree cache server is used to store temporary data which is shared between the InvenTree web server and the background worker processes. The cache server is also used to store task information, and to manage task locking between the background worker processes.
Using a cache server can significantly improve the performance of the InvenTree application, as it reduces the need to query the database for frequently accessed data.
InvenTree uses the [Redis](https://redis.io/) cache server to manage cache data. When running in docker, we use 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).
!!! tip "Enable Cache"
While a redis container is provided in the default configuration, by default it is not enabled in the Inventree server. You can enable redis cache support by following the [caching configuration guide](./config.md#caching)

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

@ -1,29 +0,0 @@
---
title: Serving Static and Media Files
---
## Serving 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.
!!! 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.
### Static Files
Static files can be served without any need for authentication. In fact, they must be accessible *without* authentication, otherwise the unauthenticated views (such as the login screen) will not function correctly.
### Media Files
It is highly recommended that the *media* files are served 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.
### 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.

13
docs/docs/stock/stock.md
View File

@ -18,6 +18,19 @@ If there are some icons missing in the tabler icons package, users can even inst
A stock location type represents a specific type of location (e.g. one specific size of drawer, shelf, ... or box) which can be assigned to multiple stock locations. In the first place, it is used to specify an icon and having the icon in sync for all locations that use this location type, but it also serves as a data field to quickly see what type of location this is. It is planned to add e.g. drawer dimension information to the location type to add a "find a matching, empty stock location" tool.
## External Stock Location
An external stock location can be used to indicate that items in there might not be available
for immediate usage. Stock items in an external location are marked with an additional icon
in the build order line items view where the material is allocated.
{% with id="stock_external_icon", url="stock/stock_external_icon.png", description="External stock indication" %}
{% include 'img.html' %}
{% endwith %}
Anyhow there is no limitation on the stock item. It can be allocated as usual.
The external flag does not get inherited to sublocations.
## Stock Item
A *Stock Item* is an actual instance of a [*Part*](../part/part.md) item. It represents a physical quantity of the *Part* in a specific location.

2
docs/mkdocs.yml
View File

@ -88,6 +88,7 @@ nav:
- Security: security.md
- Install:
- Introduction: start/intro.md
- Processes: start/processes.md
- Configuration: start/config.md
- Docker:
- Introduction: start/docker.md
@ -97,7 +98,6 @@ nav:
- Installer: start/installer.md
- Production: start/bare_prod.md
- Development: start/bare_dev.md
- Serving Files: start/serving_files.md
- User Accounts: start/accounts.md
- Data Backup: start/backup.md
- Invoke: start/invoke.md

3
docs/mlc_config.json
View File

@ -17,6 +17,9 @@
},
{
"pattern": "https://www.reddit.com/r/InvenTree/"
},
{
"pattern": "https://opensource.org/license/MIT"
}
]
}

24
docs/requirements.txt
View File

@ -307,21 +307,21 @@ mkdocs-get-deps==0.2.0 \
--hash=sha256:162b3d129c7fad9b19abfdcb9c1458a651628e4b1dea628ac68790fb3061c60c \
--hash=sha256:2bf11d0b133e77a0dd036abeeb06dec8775e46efa526dc70667d8863eefc6134
# via mkdocs
mkdocs-git-revision-date-localized-plugin==1.2.9 \
--hash=sha256:dea5c8067c23df30275702a1708885500fadf0abfb595b60e698bffc79c7a423 \
--hash=sha256:df9a50873fba3a42ce9123885f8c53d589e90ef6c2443fe3280ef1e8d33c8f65
mkdocs-git-revision-date-localized-plugin==1.3.0 \
--hash=sha256:439e2f14582204050a664c258861c325064d97cdc848c541e48bb034a6c4d0cb \
--hash=sha256:c99377ee119372d57a9e47cff4e68f04cce634a74831c06bc89b33e456e840a1
# via -r docs/requirements.in
mkdocs-include-markdown-plugin==6.2.2 \
--hash=sha256:d293950f6499d2944291ca7b9bc4a60e652bbfd3e3a42b564f6cceee268694e7 \
--hash=sha256:f2bd5026650492a581d2fd44be6c22f90391910d76582b96a34c264f2d17875d
mkdocs-include-markdown-plugin==7.0.0 \
--hash=sha256:a8eac8f2e6aa391d82d1d5e473b819b52393d91464060c02db5741834fe9008b \
--hash=sha256:bf8d19245ae3fb2eea395888e80c60bc91806a0d879279707d707896c24319c3
# via -r docs/requirements.in
mkdocs-macros-plugin==1.3.6 \
--hash=sha256:074bc072cac14c28724037b6988743cd9425752bdd35ae05fbf96b1b2457f3b7 \
--hash=sha256:74fd418c8e1f9f021b7a45bb1c7d7461d8ae09ccec241787f3971e733374da8c
mkdocs-macros-plugin==1.3.7 \
--hash=sha256:02432033a5b77fb247d6ec7924e72fc4ceec264165b1644ab8d0dc159c22ce59 \
--hash=sha256:17c7fd1a49b94defcdb502fd453d17a1e730f8836523379d21292eb2be4cb523
# via -r docs/requirements.in
mkdocs-material==9.5.42 \
--hash=sha256:452a7c5d21284b373f36b981a2cbebfff59263feebeede1bc28652e9c5bbe316 \
--hash=sha256:92779b5e9b5934540c574c11647131d217dc540dce72b05feeda088c8eb1b8f2
mkdocs-material==9.5.43 \
--hash=sha256:4aae0664c456fd12837a3192e0225c17960ba8bf55d7f0a7daef7e4b0b914a34 \
--hash=sha256:83be7ff30b65a1e4930dfa4ab911e75780a3afc9583d162692e434581cb46979
# via -r docs/requirements.in
mkdocs-material-extensions==1.3.1 \
--hash=sha256:10c9511cea88f568257f960358a467d12b970e1f7b2c0e5fb2bb48cab1928443 \