doc (configuration): update (and rewrite for TOML):
- 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
parent
388c451288
commit
2af29e7999
2 changed files with 176 additions and 133 deletions
|
|
@ -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)
|
||||
- ``<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
|
||||
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.
|
||||
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.
|
||||
|
||||
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 <plugin name>]``
|
||||
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
|
||||
``[<website name>]``
|
||||
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.<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/
|
||||
|
|
|
|||
Loading…
Reference in a new issue