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 (configuration): update (and rewrite for TOML):

Browse source 
- Configuration is now made with TOML, and the documentation was outdated. It has been
  rewritten for TOML, and autodoc is used to show configuration options available in code
  (and keep it up-to-date).
- New isolation mode is documentated.
- (core/constants): fix the `tmp` isolation mode to inherits the parent configuration like
  `normal`.
This commit is contained in:
Goffi 2026-11-03 12:52:53 +01:00
commit 2af29e7999
2 changed files with 176 additions and 133 deletions
Download patch file Download diff file Expand all files Collapse all files

299
doc/configuration.rst
View file

@ -4,156 +4,199 @@
Configuration Configuration
============= =============
Libervia main configuration is set in a file named ``libervia.conf`` (which may be prefixed Libervia main configuration is set in a file named ``libervia.toml``, in the `TOML`_
by a ``.`` if you want to hide it on suitable platforms). It is a common file used both by file format. It is a common file used both by backend and all frontends (and other
backend and all frontends (and even related project like Libervia Pubsub). projects from the ecosystem like Libervia Pubsub).
This file can be located in the following paths (in order of parsing): The file is optional: for most non-server uses, the defaults should be enough.
- ``/etc``
- ``~`` (``$HOME`` or your home directory)
- XDG directory for configuration (most of time it is
``~/.config/libervia/``)
- the parent directory of Libervia installation path
If several configurations files are found, they are merged. In case of conflict, the The most common location for this file is ``~/.config/libervia/libervia.toml``; in
option parsed last is the one used (in other words: if you have an option set in your home directory, ``libervia.toml`` or the hidden ``.libervia.toml`` also work.
``/etc/libervia.conf`` and the same one set in ``~/.libervia.conf``, the one from ``~/.libervia.conf``
will be used because it is parsed after ``/etc``).
Format .. admonition:: Details about the configuration files
====== :collapsible: closed
``libervia.conf`` is using the `INI`_ file format as understood by Python's `ConfigParser`_ Several files are searched, in this order:
(meaning that you can use interpolation).
The ``DEFAULT`` section is used for global options, this is where you specify where are - ``/etc/_libervia.toml`` (system-wide settings, usually set by distribution
your media. package maintainers, not user)
- ``/etc/libervia.toml`` (system-wide settings, for local admins)
- ``<XDG_CONFIG_DIR>/libervia/libervia.toml`` (e.g.
``/etc/xdg/libervia/libervia.toml``)
- ``/app/libervia.toml`` (Flatpak installations only)
- ``$XDG_CONFIG_HOME/libervia/libervia.toml`` (most of the time
``~/.config/libervia/libervia.toml``)
- ``~/libervia.toml``
- ``~/.libervia.toml``
Each frontend can have specific section with its name in lowercase (sections are case These locations follow the `XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/latest/>`_.
sensitive), and some backend plugin can use specific sections too (usually named ``plugin
<plugin name>``). The ``pubsub`` section is used by ``Libervia PubSub``. A section can also
have the name of a web site used with Libervia web framework.
If several configuration files are found, they are merged: the option parsed last
has the highest priority, and a section from a later file replaces the whole
section from previous files.
To recapitulate, you can have the following sections in your ``libervia.conf``: .. _TOML: https://toml.io/en/
``[DEFAULT]`` In isolation mode, an instance specific configuration file is also searched, see
the main, global section :ref:`configuration_isolation`.
frontend name (in lower case)
frontend specific settings. Some examples:
- ``[desktop]`` Frontends have their specific settings sections (e.g. ``[cli]``, ``[web]``) which are
- ``[cli]`` documented in their own documentation.
- ``[tui]``
- ``[web]``
``[plugin <plugin name>]``
backend plugin specific settings. Some examples:
- ``[plugin account]`` Environment variables
- ``[plugin muc]`` =====================
- ``[plugin search]``
``[pubsub]``
Libervia PubSub settings
``[<website name>]``
the settings of a website for Libervia web framework
.. _INI: https://en.wikipedia.org/wiki/INI_file Any option can also be set with an environment variable: the prefix is ``LIBERVIA_``,
.. _SafeConfigParser: https://docs.python.org/2/library/configparser.html then the section name, with ``__`` as separator between the levels (e.g. to set
``log_level`` in the ``[common]`` section: ``LIBERVIA_COMMON__LOG_LEVEL=debug``).
In the section, the option names suffixes are used to identify the type of settings: Environment variables take priority over the configuration files, they are useful to
override a single option without modifying a file.
- ``_dir`` is used to indicate a path to a directory
- ``_path`` is used to indicate a path (generally to a file, ``_dir`` being used for
directories)
- ``_int`` indicate a integer
- ``_list`` indicate a list comma-separated values
- ``_dict`` indicate a dictionary
- ``_json`` is used for complex data, represented with JSON format
Remember that if you want to span your data on several lines (which is often used with
``*_dict`` or ``*_json`` options), you need to indent the extra lines and keep the same
indentation.
Sample Sample
====== ======
Here is a configuration that you can use as a model to specify your own settings. Check Here is a configuration example. It is not meant to be copied as is, many of the
the comments to get the meaning of each option. options are not needed for a basic setup (notably the server related ones).
.. sourcecode:: cfg .. sourcecode:: toml
[DEFAULT] [common]
; where Libervia media are located # list of profiles with admin rights
media_dir = ~/workspace/sat_media admins_list = ["louise"]
log_level = debug # the following options are generally used when running Libervia
; domain used for new accounts # on a server (notably with Libervia Web)
xmpp_domain = example.net xmpp_domain = "example.net"
; list of profiles with admin rights
admins_list = toto,titi
; settings to let the backend send emails
email_from = NOREPLY@example.net
email_server = localhost
# email_port =
# email_username =
# email_password =
# email_starttls = true
# email_auth = true
# email_admins_list = toto@example.net, titi@example.org
; override DNS records
hosts_dict = {
"example.org": {"host": "127.0.0.1"}
}
; background luminance, used by terminal frontends
; can be "auto" (default) to autodetect, "dark" or "light"
background = auto
# end-user facing URL, used by Web frontend # end-user facing URL, used by Web frontend
public_url = example.com public_url = "example.com"
# uncomment next line if you don't want to use local cache for pubsub items
; pubsub_cache_strategy = "no_cache"
[plugin account] [common.hosts]
; where a new account must be created # override DNS records
new_account_server = localhost # "example.org".host = "127.0.0.1"
new_account_domain = example.net
[plugin muc]
; default room to use in the "Join room" menu
default_muc = libervia@chat.jabberfr.org
[tui]
log_level = debug
; how the logs are formatted
; note that "%" must be doubled here
log_fmt = %%(levelname)s: %%(message)s
; use bracketed paste mode
bracketed_paste = true
[cli] [cli]
; how to use xdotool to refresh Firefox when doing "li blog edit" # user-friendly blog preview open and refresh
blog_preview_open_cmd = firefox -new-tab {url} blog_preview_open_cmd = "firefox -new-tab {url}"
blog_preview_update_cmd = /bin/sh -c "WID=$(xdotool search --name 'Mozilla Firefox' | head -1); xdotool windowactivate $WID; xdotool key F5" blog_preview_update_cmd = "ydotool key F5"
; and below the equivalent with Konqueror # and the equivalent with Konqueror
# blog_preview_open_cmd = konqueror {url} # blog_preview_open_cmd = "konqueror {url}"
# blog_preview_update_cmd = /bin/sh -c "qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload" # blog_preview_update_cmd = "/bin/sh -c \"qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload\""
[web] [web]
; do we want "http", "https" or "both"? # passphrase for the "libervia" service profile
connection_type = both passphrase = "something_secure"
port = 8080 # to disable HTTPS when behind a proxy which handles the encryption
port_https = 8443 # (nginx, Apache, etc.)
; external port used for HTTPS (0 to use "port_https" value) # connection_type = "http"
port_https_ext = 443
; TLS public certificate or private key # [[bridges]]
; and public certificate combined (PEM format) # bridges between backend and frontends, usually not to be changed
tls_certificate = libervia.pem # (a suitable one is determined automatically)
; TLS certificate private key (PEM format) # type = "dbus"
tls_private_key = libervia-key.pem
; if true (or 1), HTTP will redirect to HTTPS [tls]
redirect_to_https = 1 certificate = "/path/to/libervia.pem"
; passphrase for libervia profile private_key = "/path/to/libervia-key.pem"
passphrase = something_secure
; here we redirect main libervia page [email]
; to the blog of a profile named "some_profile" # settings to let the backend send emails
url_redirections_dict = { server = "localhost"
"/": "/u/some_profile" from = "NOREPLY@example.net"
} username = "username"
password = "password"
# port = 587
# starttls = true
# auth = true
[component.pubsub]
# the "jid" and "secret" entries let the component be
# configured and connected automatically
jid = "pubsub.example.net"
secret = "some_shared_secret"
[component.ap_gateway]
http_connection_type = "http"
[application.peertube]
# settings used by the app manager
hostname = "videos.example.com"
Options
=======
The following top-level sections are available in the configuration file. This
documentation is generated from the code, so it is guaranteed to be up-to-date:
.. autopydantic_settings:: libervia.backend.tools.config.Settings
See :ref:`components` for the ``[component.<name>]`` sections.
Common
------
General options, used in many places:
.. autopydantic_settings:: libervia.backend.tools.config.CommonSettings
Email
-----
Options to let the backend send emails:
.. autopydantic_settings:: libervia.backend.tools.config.EmailSettings
TLS
---
Paths to the TLS certificates, used for secure (HTTPS) connections:
.. autopydantic_settings:: libervia.backend.tools.config.TLSSettings
Tor
---
Tor options are documented in :ref:`libervia_over_tor`, together with Tor specific
information.
Bridges
-------
Bridges are the way the backend and the frontends communicate with each other. If
empty, the ``auto`` bridge is used.
.. note::
Specifying several bridges at once is planned, but not implemented yet.
.. autopydantic_settings:: libervia.backend.tools.config.AutoBridgeSettings
.. autopydantic_settings:: libervia.backend.tools.config.DBusBridgeSettings
.. autopydantic_settings:: libervia.backend.tools.config.PbBridgeSettings
.. autopydantic_settings:: libervia.backend.tools.config.EmbeddedBridgeSettings
.. _configuration_isolation:
Isolation mode
==============
Isolation lets several Libervia instances run side by side, each with its own data.
An instance is enabled with the ``LIBERVIA_ISOLATION`` environment variable. The CLI
can also work with an isolated instance, using the ``-i/--isolation NAME`` option, see
:ref:`li_isolation`.
The name can contain only letters, digits and ``_``. The behaviour depends on
the isolation mode, set with ``LIBERVIA_ISOLATION_MODE`` (default: ``normal``):
- ``normal``: data and runtime files are stored in an instance specific directory, and
the instance configuration file
(``$XDG_CONFIG_HOME/libervia/isolated/<name>/libervia.toml``) is added to the list
of searched files (it is parsed last, so it takes priority)
- ``full``: as ``normal``, but only the instance configuration file is used (i.e., no
other configuration file is inherited)
- ``tmp``: as ``normal``, but data and runtime files are stored in the system
temporary directory (e.g. for disposable instances)
.. _TOML: https://toml.io/en/

2
libervia/backend/core/constants.py
View file

@ -131,7 +131,7 @@ class Const:
if ISOLATED_CONFIG_DIR is not None: if ISOLATED_CONFIG_DIR is not None:
isolated_conf = ISOLATED_CONFIG_DIR / f"{APP_NAME_FILE}.toml" isolated_conf = ISOLATED_CONFIG_DIR / f"{APP_NAME_FILE}.toml"
if isolation_mode == "normal": if isolation_mode in ("normal", "tmp"):
CONFIG_FILES.append(isolated_conf) CONFIG_FILES.append(isolated_conf)
else: else:
CONFIG_FILES = [isolated_conf] CONFIG_FILES = [isolated_conf]