2af29e7999
- 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`.
202 lines
6.5 KiB
ReStructuredText
202 lines
6.5 KiB
ReStructuredText
.. _configuration:
|
|
|
|
=============
|
|
Configuration
|
|
=============
|
|
|
|
Libervia main configuration is set in a file named ``libervia.toml``, in the `TOML`_
|
|
file format. It is a common file used both by backend and all frontends (and other
|
|
projects from the ecosystem like Libervia Pubsub).
|
|
|
|
The file is optional: for most non-server uses, the defaults should be enough.
|
|
|
|
The most common location for this file is ``~/.config/libervia/libervia.toml``; in
|
|
your home directory, ``libervia.toml`` or the hidden ``.libervia.toml`` also work.
|
|
|
|
.. admonition:: Details about the configuration files
|
|
:collapsible: closed
|
|
|
|
Several files are searched, in this order:
|
|
|
|
- ``/etc/_libervia.toml`` (system-wide settings, usually set by distribution
|
|
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``
|
|
|
|
These locations follow the `XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/latest/>`_.
|
|
|
|
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.
|
|
|
|
.. _TOML: https://toml.io/en/
|
|
|
|
In isolation mode, an instance specific configuration file is also searched, see
|
|
:ref:`configuration_isolation`.
|
|
|
|
Frontends have their specific settings sections (e.g. ``[cli]``, ``[web]``) which are
|
|
documented in their own documentation.
|
|
|
|
Environment variables
|
|
=====================
|
|
|
|
Any option can also be set with an environment variable: the prefix is ``LIBERVIA_``,
|
|
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``).
|
|
|
|
Environment variables take priority over the configuration files, they are useful to
|
|
override a single option without modifying a file.
|
|
|
|
Sample
|
|
======
|
|
|
|
Here is a configuration example. It is not meant to be copied as is, many of the
|
|
options are not needed for a basic setup (notably the server related ones).
|
|
|
|
.. sourcecode:: toml
|
|
|
|
[common]
|
|
# list of profiles with admin rights
|
|
admins_list = ["louise"]
|
|
# the following options are generally used when running Libervia
|
|
# on a server (notably with Libervia Web)
|
|
xmpp_domain = "example.net"
|
|
# end-user facing URL, used by Web frontend
|
|
public_url = "example.com"
|
|
|
|
[common.hosts]
|
|
# override DNS records
|
|
# "example.org".host = "127.0.0.1"
|
|
|
|
[cli]
|
|
# user-friendly blog preview open and refresh
|
|
blog_preview_open_cmd = "firefox -new-tab {url}"
|
|
blog_preview_update_cmd = "ydotool key F5"
|
|
# and the equivalent with Konqueror
|
|
# blog_preview_open_cmd = "konqueror {url}"
|
|
# blog_preview_update_cmd = "/bin/sh -c \"qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload\""
|
|
|
|
[web]
|
|
# passphrase for the "libervia" service profile
|
|
passphrase = "something_secure"
|
|
# to disable HTTPS when behind a proxy which handles the encryption
|
|
# (nginx, Apache, etc.)
|
|
# connection_type = "http"
|
|
|
|
# [[bridges]]
|
|
# bridges between backend and frontends, usually not to be changed
|
|
# (a suitable one is determined automatically)
|
|
# type = "dbus"
|
|
|
|
[tls]
|
|
certificate = "/path/to/libervia.pem"
|
|
private_key = "/path/to/libervia-key.pem"
|
|
|
|
[email]
|
|
# settings to let the backend send emails
|
|
server = "localhost"
|
|
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/
|