.. _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/