doc (components/pubsub): Pubsub component documentation:
fix 476
This commit is contained in:
Goffi
parent
e7c508b11c
commit
f03939e2af
2 changed files with 238 additions and 2 deletions
|
|
@ -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.<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
|
||||
|
||||
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 <li_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 <https://repos.goffi.org/libervia-pubsub/>`__ 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.<xmpp_domain>"
|
||||
component_secret = "<password>"
|
||||
|
||||
- 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 "<xmpp_domain>"
|
||||
privileged_entities = {
|
||||
["pubsub.<xmpp_domain>"] = {
|
||||
roster = "get";
|
||||
message = "outgoing";
|
||||
presence = "roster";
|
||||
iq = {
|
||||
["http://jabber.org/protocol/pubsub"] = "set";
|
||||
};
|
||||
},
|
||||
}
|
||||
delegations = {
|
||||
["urn:xmpp:mam:2"] = {
|
||||
filtering = {"node"};
|
||||
jid = "pubsub.<xmpp_domain>";
|
||||
},
|
||||
["http://jabber.org/protocol/pubsub"] = {
|
||||
jid = "pubsub.<xmpp_domain>";
|
||||
},
|
||||
["http://jabber.org/protocol/pubsub#owner"] = {
|
||||
jid = "pubsub.<xmpp_domain>";
|
||||
},
|
||||
["https://salut-a-toi/protocol/schema:0"] = {
|
||||
jid = "pubsub.<xmpp_domain>";
|
||||
},
|
||||
["https://salut-a-toi.org/spec/pubsub_admin:0"] = {
|
||||
jid = "pubsub.<xmpp_domain>";
|
||||
},
|
||||
["urn:xmpp:pam:0"] = {
|
||||
jid = "pubsub.<xmpp_domain>";
|
||||
},
|
||||
["urn:xmpp:delegation:2:bare:disco#info:*"] = {
|
||||
jid = "pubsub.<xmpp_domain>";
|
||||
},
|
||||
["urn:xmpp:delegation:2:bare:disco#items:*"] = {
|
||||
jid = "pubsub.<xmpp_domain>";
|
||||
},
|
||||
["jabber:iq:private"] = {
|
||||
jid = "pubsub.<xmpp_domain>";
|
||||
},
|
||||
}
|
||||
|
||||
Component "pubsub.<xmpp_domain>"
|
||||
component_secret = "<password>"
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 = ""
|
||||
|
|
|
|||
Loading…
Reference in a new issue