Addons🔗

Addons allow to execute custom software within a defined context in Docspell. The idea is to be able to support new features and amend existing ones.

Despite the warning above, addons are a nice way to amend your docspell server with new things, you are encouraged to try it out and give feedback ;-).

What is an Addon?🔗

An addon is a zip file that contains a docspell-addon.yml (or .yaml or .json) file in its root. The docspell-addon.yml is the addon descriptor telling how to run and optionally build the addon. In the ZIP file, an addon provides a program that expects one argument which is a file containing the user input for the addon. Addons can communicate back to docspell via their stdout and/or via directly calling the docspell server as part of their program.

What can Addons do?🔗

Addons can accept user input and are arbitrary external programs that can do whatever they want. However, Docspell can embed running addons in restricted environments, where they don't have network for example. Addons can safely communicate to Docspell via their stdout output returning instructions that Docspell will realise.

Running addons is managed by docspell. Currently they can be executed:

• as the final step when processing or re-procssing an item. They then have access to all the item data that has been collected during processing (id, extracted text, converted pdfs, etc) and it can work with that. It may, for example, set more tags or custom fields.
• trigger manually on some existing item
• periodically defined by a schedule. This executes the addons only with the configured user input.
• … (maybe more to come)

Since an addon may not make sense to run on all these situations, it must define a sensible subset via the triggers option in its descriptor.

How are they run🔗

Addons are always executed by the joex component as an external process, therefore they can be written in any programming or scripting language.

That means the machine running joex possibly needs to match the requirements of each addon. To ease this, addons can provide a nix descripton or a Dockerfile. Then you need to prepare the machine only with two things (nix and docker) to have the prerequisites for running many addons.

More …🔗

Addons are a flexible way to extend Docspell and require some technical affinity. However, only "using" addons should not be that hard, but it will always depend on the documentation of the addon and its own complexity.

As the user, you may have different views: preparing the server to be able to run addons, writing your own addons and finally using them

The following sections are divided these perspectives:

Using Addons🔗

Addons must be installed and then configured in order before they can be used. Using Addons describes this perspective.

Control how addons are run🔗

As the owner of your server, you want to control how addons are run. Since addons are arbitrary programs, potentially downloaded from the internet, they can be run in a restricted environment.

Write custom addons🔗

Finally, writing addons requires (among other things) to know how to interact with Docspell and what package format is expected.