inventree/inventree-docs
2
0
Fork 0
mirror of https://github.com/inventree/inventree-docs.git synced 2025-10-30 20:35:38 +00:00
Code Activity

Updated plugin docs (#398)

Browse Source
This commit is contained in:
Oliver
2022-11-21 22:05:26 +11:00
committed by GitHub
parent 98a416ebe8
commit 94d0bc8e63
4 changed files with 49 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/extend/plugins.md
View File

@@ -12,13 +12,7 @@ Plugins can be added from multiple sources:
- Custom plugins should be placed in the directory `./InvenTree/plugins`.
- InvenTree built-in plugins are located in the directory `./InvenTree/plugin/builtin`.
Note: Plugins are discovered and loaded only when the server is started.
!!! info "Enable Plugin Support"
To enable custom plugins, plugin support must be activated in the [server configuration](../start/config.md).
!!! question "Have you tried turning it off and on again?"
When new plugins are installed (and activated), both the web server and background worker must be restarted.
For further information, read more about [installing plugins](./plugins/install.md).
### Plugin Base Class

55
docs/extend/plugins/install.md
View File

@@ -7,7 +7,42 @@ title: Installing Plugins
Plugins can either be loaded from paths in the InvenTree install directory or as a plugin installed via pip. We recommend installation via pip as this enables hassle-free upgrades.
### Plugin Installation File (PIP)
### Common Issues
Installing plugins can be complex! Some common issues are outlined below:
#### Enable Plugin Support
To enable custom plugins, plugin support must be activated in the [server configuration](../../start/config.md#plugin-options). This step must be performed by a system administrator before the InvenTree server is started.
#### Restart Server
Plugins are discovered and loaded only when the server is started. When new plugins are installed (and activated), both the web server and background worker must be restarted.
#### Container Environments
In certain container environments (such as docker), plugins are installed into an *ephemeral* virtual environment which persists only for the lifetime of the container. To allow for this, InvenTree provides a configurable setting which can automatically install plugins whenever the container is loaded.
!!! tip "Check Plugins on Startup"
Ensure the **Check Plugins on Startup** option is enabled, when running InvenTree in a container environment!
{% with id="check_plugins", url="plugin/check_on_startup.png", description="Check plugins on startup" %}
{% include 'img.html' %}
{% endwith %}
### Installation Methods
#### Builtin Plugins
Builtin plugins ship in `src/InvenTree/plugin/builtin`. To achive full unit-testing for all mixins there are some sample implementations in `src/InvenTree/plugin/samples`.
!!! success "Builtin Plugins"
Builtin plugins are always enabled, as they are required for core InvenTree functionality
!!! info "Debug Only"
The sample plugins are not loaded in production mode.
#### Plugin Installation File (PIP)
Plugins installation can be simplified by providing a list of plugins in a plugin configuration file. This file (by default, *plugins.txt* in the same directory as the server configuration file) contains a list of required plugin packages.
@@ -23,15 +58,21 @@ Installation via PIP (using the *plugins.txt* file) provides a number of advanta
!!! success "Auto Update"
When the server installation is updated via the `invoke update` command, the plugins (as specified in *plugins.txt*) will also be updated automatically.
!!! info "Plugin File Location"
The location of your plugin configuration file will depend on your [server configuration](../../start/config.md)
### Builtin Plugins
#### Web Interface
Built-In plugins ship in `src/InvenTree/plugin/builtin`. To achive full unit-testing for all mixins there are some sample implementations in `src/InvenTree/plugin/samples`.
Admin users can install plugins directly from the web interface, via the "Plugin Settings" view:
!!! info "Debug Only"
The sample plugins are not loaded in production mode.
{% with id="plugin_install", url="plugin/plugin_install_web.png", description="Install via web interface" %}
{% include 'img.html' %}
{% endwith %}
### Local Directory
!!! success "Plugin File"
A plugin installed via the web interface is added to the [plugins.txt](#plugin-installation-file-pip) plugin file.
#### Local Directory
Custom plugins can be placed in the `src/InvenTree/plugins/` directory, where they will be automatically discovered. This can be useful for developing and testing plugins, but can prove more difficult in production (e.g. when using Docker).
@@ -41,7 +82,7 @@ Custom plugins can be placed in the `src/InvenTree/plugins/` directory, where th
!!! warning "Not Recommended For Production"
Loading plugins via the local *plugins* directory is not recommended for production. If you cannot use PIP installation (above), specify a custom plugin directory (below) or use a [VCS](https://pip.pypa.io/en/stable/topics/vcs-support/) as a plugin install source.
### Custom Directory
#### Custom Directory
If you wish to install plugins from local source, rather than PIP, it is better to place your plugins in a directory outside the InvenTree source directory.