diff --git a/doc/configuration.rst b/doc/configuration.rst index a7f27e1e..188048d7 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -4,156 +4,199 @@ Configuration ============= -Libervia main configuration is set in a file named ``libervia.conf`` (which may be prefixed -by a ``.`` if you want to hide it on suitable platforms). It is a common file used both by -backend and all frontends (and even related project like Libervia Pubsub). +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). -This file can be located in the following paths (in order of parsing): - - ``/etc`` - - ``~`` (``$HOME`` or your home directory) - - XDG directory for configuration (most of time it is - ``~/.config/libervia/``) - - the parent directory of Libervia installation path +The file is optional: for most non-server uses, the defaults should be enough. -If several configurations files are found, they are merged. In case of conflict, the -option parsed last is the one used (in other words: if you have an option set in -``/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``). +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. -Format -====== +.. admonition:: Details about the configuration files + :collapsible: closed -``libervia.conf`` is using the `INI`_ file format as understood by Python's `ConfigParser`_ -(meaning that you can use interpolation). + Several files are searched, in this order: -The ``DEFAULT`` section is used for global options, this is where you specify where are -your media. + - ``/etc/_libervia.toml`` (system-wide settings, usually set by distribution + package maintainers, not user) + - ``/etc/libervia.toml`` (system-wide settings, for local admins) + - ``/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 -sensitive), and some backend plugin can use specific sections too (usually named ``plugin -``). The ``pubsub`` section is used by ``Libervia PubSub``. A section can also -have the name of a web site used with Libervia web framework. + These locations follow the `XDG Base Directory Specification `_. + 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]`` - the main, global section -frontend name (in lower case) - frontend specific settings. Some examples: +In isolation mode, an instance specific configuration file is also searched, see +:ref:`configuration_isolation`. - - ``[desktop]`` - - ``[cli]`` - - ``[tui]`` - - ``[web]`` -``[plugin ]`` - backend plugin specific settings. Some examples: +Frontends have their specific settings sections (e.g. ``[cli]``, ``[web]``) which are +documented in their own documentation. - - ``[plugin account]`` - - ``[plugin muc]`` - - ``[plugin search]`` -``[pubsub]`` - Libervia PubSub settings -``[]`` - the settings of a website for Libervia web framework +Environment variables +===================== -.. _INI: https://en.wikipedia.org/wiki/INI_file -.. _SafeConfigParser: https://docs.python.org/2/library/configparser.html +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``). -In the section, the option names suffixes are used to identify the type of settings: - -- ``_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. +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 that you can use as a model to specify your own settings. Check -the comments to get the meaning of each option. +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:: cfg +.. sourcecode:: toml - [DEFAULT] - ; where Libervia media are located - media_dir = ~/workspace/sat_media - log_level = debug - ; domain used for new accounts - 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 + [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 - # uncomment next line if you don't want to use local cache for pubsub items - ; pubsub_cache_strategy = "no_cache" + public_url = "example.com" - [plugin account] - ; where a new account must be created - new_account_server = localhost - 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 + [common.hosts] + # override DNS records + # "example.org".host = "127.0.0.1" [cli] - ; how to use xdotool to refresh Firefox when doing "li blog edit" - 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" - ; and below 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" + # 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] - ; do we want "http", "https" or "both"? - connection_type = both - port = 8080 - port_https = 8443 - ; external port used for HTTPS (0 to use "port_https" value) - port_https_ext = 443 - ; TLS public certificate or private key - ; and public certificate combined (PEM format) - tls_certificate = libervia.pem - ; TLS certificate private key (PEM format) - tls_private_key = libervia-key.pem - ; if true (or 1), HTTP will redirect to HTTPS - redirect_to_https = 1 - ; passphrase for libervia profile - passphrase = something_secure - ; here we redirect main libervia page - ; to the blog of a profile named "some_profile" - url_redirections_dict = { - "/": "/u/some_profile" - } + # 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.]`` 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//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/ diff --git a/libervia/backend/core/constants.py b/libervia/backend/core/constants.py index 4390740a..bd2eb5af 100644 --- a/libervia/backend/core/constants.py +++ b/libervia/backend/core/constants.py @@ -131,7 +131,7 @@ class Const: if ISOLATED_CONFIG_DIR is not None: 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) else: CONFIG_FILES = [isolated_conf]