diff --git a/doc/components.rst b/doc/components.rst index cf26e1eb..a4e5e7af 100644 --- a/doc/components.rst +++ b/doc/components.rst @@ -12,12 +12,13 @@ This page explains which components are available and how to use them. Running a component =================== -Components are linked to a Libervia profile in the same way as normal clients. - To run a component, you'll need to know its *entry point*, which is the name of the import name of plugin managing it. The entry point to use will be specified in the component installation documentation. +Components are linked to a Libervia profile in the same way as normal clients. You could +set them manually, but most of time you can use the simplified configuration. + You'll also have to declare the component on your XMPP server, this is a server dependent step and you'll have to check your server documentation for details. You'll have to specify a **shared secret** (can also be named simply *password*) that must be set both on @@ -40,6 +41,40 @@ Prosody 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.]`` 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.]``: + +.. autopydantic_settings:: libervia.backend.tools.config.ComponentSettings + +example +------- + +To set up the ``Pubsub`` component, you check the entry point in its documentation, and +find that it's ``pubsub``, then you simply put in your configuration (usually +``libervia.toml``): + +.. sourcecode:: toml + + [component.pubsub] + jid = "pubsub.example.org" + secret = "your_shared_secret" + +Manual Component Configuration +============================== + +In some rare case, you may want to manually create component profiles (e.g.; if you want +to use the same component multiple times). + On Libervia, setup is done with Libervia CLI's :ref:`profile create ` command. @@ -899,3 +934,198 @@ but it’s possible for some content to be incorrectly identified. .. _XEP-0498 (Pubsub File Sharing): https://xmpp.org/extensions/xep-0498.html .. _Wikipedia's Autocrypt page: https://en.wikipedia.org/wiki/Autocrypt +Libervia Pubsub +--------------- + +**entry_point:** ``pubsub`` + +.. note:: + + This component is **work in progress** and under heavy development. It is the rewrite on + top of Libervia Backend of the independent "Libervia Pubsub" component, and has not yet + full feature parity with it. + +Libervia Pubsub is a feature-full XMPP Pubsub service that can also be used as a +`XEP-0163 (Personal Eventing Protocol)`_ service (simply named "PEP"). Pubsub/PEP is a +major part of XMPP, and this implementation aims to be the state of the art with all +important features available. It is the reference implementation for Libervia, which means +that by using it you know that you'll have all pubsub related features needed to fully +enjoy Libervia capabilities. + + +.. _XEP-0163 (Personal Eventing Protocol): https://xmpp.org/extensions/xep-0163.html + +Features +~~~~~~~~ + +Libervia Pubsub aims to be a feature-full pubsub implementation. In addition to base +PEP/Pubsub service, it implements: + +`XEP-0059 (Result Set Management)`_ + Handle pagination on large result sets. + +`XEP-0355 (Namespace Delegation)`_ and `XEP-0356 (Privileged Entity)`_ + Can be used to replace a server's internal PEP implementation. + +`XEP-0496 (Pubsub Node Relationships)`_ + Build a node hierarchy with parent/children nodes and linked nodes. Useful to organise + nodes, change permissions, manage or delete automatically related nodes (e.g. a blog + post and its comments), implement forums, etc. + +`XEP-0499 (Pubsub Extended Discovery)`_ + Explore hierarchies of nodes as created with XEP-0496. + +History +~~~~~~~ + +Libervia Pubsub is a reimplementation on top of Libervia Backend of the former standalone +`pubsub component `__ of the same name, which +was previously called "SàT Pubsub". "SàT Pubsub" was itself a fork of `Idavoll`_, a Pubsub +component made by Ralph Meijer + +Acknowledgement +~~~~~~~~~~~~~~~ + +This component has been possible thanks to the work of Ralph Meijer on `Wokkel`_ and +`Idavoll`_. Ralph is also one of the authors of `XEP-0060 (Pubsub)`_. Other people made +that possible: the other authors of XEP-0060 (Peter Millard and Peter Saint-Andre), all +the awesome folks working or having worked on XMPP, and Adrien Cossa who worked on +Libervia and built the foundations to implement RSM (`XEP-0059 (Result Set Management)`_) +and MAM (`XEP-0313 (Message Archiving XEP)`_ and `XEP-0442 (Predefined Namespace for PEP +Nodes)`_). A big thanks to them! + +The reimplementation of Libervia Pubsub into Libervia Backend has been possible thanks to +a `NLnet`_/`NGI0 Commons Fund`_, for the "`Serverless and Metadata Reduction`_ for XMPP" +project. + +.. _XEP-0060 (Pubsub): https://xmpp.org/extensions/xep-0060.html +.. _Wokkel: https://github.com/ralphm/wokkel +.. _Idavoll: https://github.com/ralphm/idavoll +.. _XEP-0059 (Result Set Management): https://xmpp.org/extensions/xep-0059.html +.. _XEP-0313 (Message Archiving XEP): https://xmpp.org/extensions/xep-0313.html +.. _XEP-0355 (Namespace Delegation): https://xmpp.org/extensions/xep-0355.html +.. _XEP-0356 (Privileged Entity): https://xmpp.org/extensions/xep-0356.html +.. _XEP-0442 (Predefined Namespace for PEP Nodes): https://xmpp.org/extensions/xep-0442.html +.. _XEP-0496 (Pubsub Node Relationships): https://xmpp.org/extensions/xep-0496.html +.. _XEP-0499 (Pubsub Extended Discovery): https://xmpp.org/extensions/xep-0499.html +.. _NGI0 Commons Fund: https://nlnet.nl/commonsfund/ + +.. _NLnet: https://nlnet.nl/ +.. _Serverless and Metadata Reduction: https://nlnet.nl/project/ServerlessXMPP/ + +Prosody Configuration +--------------------- + +Libervia PubSub can work with any XMPP server (which supports components), but if you want +to use it as your PEP service, you need a server which supports XEP-0355 and XEP-0356. + +Below you'll find the instructions to use Libervia PubSub as a PEP service with Prosody: + +- add these two lines at the end of your ``prosody.cfg.lua`` file, adapting them to your + XMPP server domain (virtual host) and selecting a password of your choice: + +.. sourcecode:: lua + + Component "pubsub." + component_secret = "" + +- there are extra steps to enable the micro-blogging feature with Prosody. Please follow + the installation and configuration instructions that are given on these pages: + + - https://modules.prosody.im/mod_delegation.html + - https://modules.prosody.im/mod_privilege.html + +.. note:: + + On recent prosody installation, instead of manually cloning and linking it, you can use + the `Prosody Plugin Installer`_. + +To keep your modules up to date, we recommend to clone the full modules repository and +then to symlink them like that: + +.. sourcecode:: shell + + % cd /path/to/install_dir + % hg clone https://hg.prosody.im/prosody-modules + % cd /path/to/prosody_plugins + % ln -sf /path/to/install_dir/prosody-modules/mod_delegation ./ + % ln -sf /path/to/install_dir/prosody-modules/mod_privilege ./ + +Of course, you have to adapt ``/path/to/install_dir`` to the directory where you want to +install the modules, and ``/path/to/prosody_plugins`` to the directory where prosody +modules are installed (hint: check ``prosodyctl about`` to find the latter). The ``ln`` +commands may have to be run as root depending on your installation. + +Once your symlinks are set, to update the modules we just need to type this: + +.. sourcecode:: shell + + % cd /path/to/install_dir/prosody-modules + % hg pull -u + +Here is an example of how your ``prosody.cfg.lua`` should look like with +``mod_delegation`` and ``mod_privilege`` activated: + +.. sourcecode:: lua + + [...] + modules_enabled = { + [...] + "delegation"; + "privilege"; + } + [...] + VirtualHost "" + privileged_entities = { + ["pubsub."] = { + roster = "get"; + message = "outgoing"; + presence = "roster"; + iq = { + ["http://jabber.org/protocol/pubsub"] = "set"; + }; + }, + } + delegations = { + ["urn:xmpp:mam:2"] = { + filtering = {"node"}; + jid = "pubsub."; + }, + ["http://jabber.org/protocol/pubsub"] = { + jid = "pubsub."; + }, + ["http://jabber.org/protocol/pubsub#owner"] = { + jid = "pubsub."; + }, + ["https://salut-a-toi/protocol/schema:0"] = { + jid = "pubsub."; + }, + ["https://salut-a-toi.org/spec/pubsub_admin:0"] = { + jid = "pubsub."; + }, + ["urn:xmpp:pam:0"] = { + jid = "pubsub."; + }, + ["urn:xmpp:delegation:2:bare:disco#info:*"] = { + jid = "pubsub."; + }, + ["urn:xmpp:delegation:2:bare:disco#items:*"] = { + jid = "pubsub."; + }, + ["jabber:iq:private"] = { + jid = "pubsub."; + }, + } + + Component "pubsub." + component_secret = "" + modules_enabled = {"delegation", "privilege"} + +Of course, you still have to replace and adapt to your own settings. + +.. _XEP-0355: https://xmpp.org/extensions/xep-0355.html +.. _XEP-0356: https://xmpp.org/extensions/xep-0356.html + + +.. _Prosody Plugin Installer: https://prosody.im/doc/plugin_installer + diff --git a/doc/conf.py b/doc/conf.py index 9c31dd65..9224fa1e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -198,5 +198,11 @@ epub_exclude_files = ["search.html"] autodoc_pydantic_settings_show_config_summary = False autodoc_pydantic_settings_show_json = False autodoc_pydantic_settings_show_field_summary = False +autodoc_pydantic_field_list_validators = False +autodoc_pydantic_settings_show_validator_summary = False +autodoc_pydantic_settings_show_validator_members = False autodoc_pydantic_settings_member_order = "bysource" +autodoc_pydantic_model_show_config_summary = False +autodoc_pydantic_model_show_field_summary = False +autodoc_pydantic_model_show_json = False autodoc_pydantic_field_signature_prefix = ""