Addon docs

website/site/content/docs/addons/basics.md

@@ -0,0 +1,149 @@
++++
+title = "Basics"
+insert_anchor_links = "right"
+description = "Docspell Addons."
+weight = 10
+template = "docs.html"
++++
+
+# 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.
+
+{% warningbubble(title="Experimental") %} Addons are considered
+experimental. The interaction between addons and Docspell is still
+subject to change.
+
+The intended audience for addons are developers (to create addons) and
+technically inclined users to install, configure and use them.
+{% end %}
+
+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 ;-).
+
+{% infobubble(title="Enable addons manually") %}
+Addons are disabled by default. They must be enabled in the config
+file of the restserver!
+{% end %}
+
+
+## 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](https://nixos.wiki/wiki/Flakes) 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](@/docs/addons/using.md) describes this
+perspective.
+
+{{ buttonright(href="/docs/addons/using", text="More…") }}
+
+## Control how addons are run
+
+As the owner of your server, you want to [control how addons are
+run](@/docs/addons/control.md). Since addons are arbitrary programs,
+potentially downloaded from the internet, they can be run in a
+restricted environment.
+
+{{ buttonright(href="/docs/addons/control", text="More…") }}
+
+
+## Write custom addons
+
+Finally, [writing addons](@/docs/addons/writing.md) requires (among
+other things) to know how to interact with Docspell and what package
+format is expected.
+
+{{ buttonright(href="/docs/addons/writing", text="More…") }}
+
+
+
+<!-- ## Goals -->
+
+<!-- - Convenient for addon creators. Addons can be written in any -->
+<!--   programming language and have a very light contract: they receive -->
+<!--   one input argument and _may_ return structured data to instruct -->
+<!--   docspell what to do. If not they can execute abritrary code to call -->
+<!--   the server directly. -->
+<!-- - Server administrators control how they are executed. Since addons -->
+<!--   may run anything, the execution should be able to locked down when -->
+<!--   wanted. -->
+<!-- - Users can install and configure addons via the web interface easily. -->
+<!--   It should be easy for addon creators to document how users can use -->
+<!--   them. -->
+
+
+<!-- # TODOs -->
+
+<!-- - what if joex is running inside a container alread? -->
+<!-- - some use cases: -->
+<!--   - I want an addon to do some stuff when processing files -->
+<!--     - my files named "something_bla" are always this specific document -->
+<!--       and so very specific processing would be great -->
+<!--   - I want XYZ files to work (e.g. mp3?) -->
+<!--   - I want to generate previews for video files -->
+<!-- - Example Addons: -->
+<!--   - swiss qr code detection on invoices -->
+<!--   - tags via regexes -->
+<!--   - text extraction from audio? -->
+<!--   - preview generation for video? -->