erebion/libervia-backend
Watch
1
0
Fork
You've already forked libervia-backend
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc (components): document the common component settings:

Browse source 
- Move the `ComponentSettings` autodoc from "Simplified Component Configuration" to a new
  "Common Component Settings" section. This was confusing when most of time only `jid` and
  `secret` are needed.
- Document the config section naming (dashes replaced by underscores) and how to run a
  component in an isolated instance (systemd, `li -i`).
- Fix the `[components.X]` section names (`[component.X]`).
This commit is contained in:
Goffi 2026-11-03 14:24:59 +01:00
commit fc0a385027
1 changed files with 35 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

53
doc/components.rst
View file

@ -1,8 +1,8 @@
.. _components:
===================
Libervia Components
===================
==========
Components
==========
Libervia can act as an XMPP server component, which can be seen as a generic plugin for
XMPP servers.
@ -38,23 +38,20 @@ OpenFire
Prosody
https://prosody.im/doc/components
Tigase
https://docs.tigase.net/en/latest/Tigase_Administration/Components/_Components.html#external-component-configuration
.. Tigase documentation is down (2026-11-03, the whole docs.tigase.net site is 404),
uncomment once it's back:
.. Tigase
.. https://docs.tigase.net/en/latest/Tigase_Administration/Components/_Components.html#external-component-configuration
Simplified Component Configuration
==================================
Most user will want to use this simplified configuration. To set up a component, you
simply need to create a configuration section with ``[component.<entry_point>]`` where
you'll set the ``jid`` and ``secret`` options. Everything will be automatically configured
on backend startup, and the component will start automatically.
settings
--------
In ``[component.<entry_point>]``:
.. autopydantic_settings:: libervia.backend.tools.config.ComponentSettings
simply need to create a configuration section named after the entry point, with dashes
replaced by underscores (e.g. the ``email-gateway`` entry point uses the
``[component.email_gateway]`` section), where you'll set the ``jid`` and ``secret``
options. Everything will be automatically configured on backend startup, and the
component will start automatically.
example
-------
@ -69,6 +66,10 @@ find that it's ``pubsub``, then you simply put in your configuration (usually
jid = "pubsub.example.org"
secret = "your_shared_secret"
To run the component in an isolated backend instance (e.g. as a dedicated systemd
service), see :ref:`installation_system`. To work with such an instance from the CLI,
use the ``-i/--isolation`` option (see :ref:`li_isolation`).
Manual Component Configuration
==============================
@ -108,6 +109,14 @@ wants to connect it immediately, she can use::
$ li profile connect -cp ap-gateway
Common Component Settings
=========================
Besides component specific options (see the component sections below), every
component supports these common options in its configuration section:
.. autopydantic_settings:: libervia.backend.tools.config.ComponentSettings
Available Components
====================
@ -139,7 +148,7 @@ entities (JIDs). Permissions can be set through Ad-Hoc Commands.
Configuration
~~~~~~~~~~~~~
All options are to be set in ``[components.file_sharing]`` section.
All options are to be set in ``[component.file_sharing]`` section.
``http_upload_port``
port to use for HTTP File Upload
@ -216,7 +225,13 @@ documentation to find how this must be done.
Configuration
~~~~~~~~~~~~~
All options are to be set in ``[components.ap_gateway]`` section.
All options are to be set in ``[component.ap_gateway]`` section:
.. autopydantic_settings:: libervia.backend.plugins.plugin_comp_ap_gateway.settings.APGatewaySettings
By default, the HTTP server uses HTTPS, thus a TLS certificate is required, either in the
``tls`` option or in the global ``[tls]`` section. If an HTTPS proxy already handles TLS,
use ``http_connection_type = "http"`` instead.
.. _ap-actor-from-xmpp:
@ -745,7 +760,7 @@ any kind of extra informations) while AP only indicates if one will attend or no
event.
.. _Mobilizon: https://joinmobilizon.org/
.. _Mobilizon: https://mobilizon.org/
Using the Component (for developers)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -812,6 +827,8 @@ All options are to be set in the ``[component.conferences]`` section.
.. _Galène project: https://galene.org/
.. _email-gateway:
Email Gateway
-------------