diff --git a/docs/assets/images/plugin/check_on_startup.png b/docs/assets/images/plugin/check_on_startup.png new file mode 100644 index 0000000..9d13686 Binary files /dev/null and b/docs/assets/images/plugin/check_on_startup.png differ diff --git a/docs/assets/images/plugin/plugin_install_web.png b/docs/assets/images/plugin/plugin_install_web.png new file mode 100644 index 0000000..67ecc3b Binary files /dev/null and b/docs/assets/images/plugin/plugin_install_web.png differ diff --git a/docs/extend/plugins.md b/docs/extend/plugins.md index 0faded7..4950eac 100644 --- a/docs/extend/plugins.md +++ b/docs/extend/plugins.md @@ -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 diff --git a/docs/extend/plugins/install.md b/docs/extend/plugins/install.md index c1ead99..e2d5639 100644 --- a/docs/extend/plugins/install.md +++ b/docs/extend/plugins/install.md @@ -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.