From 0c955f6abd5a696efaa06223b5651753a98ec5b0 Mon Sep 17 00:00:00 2001 From: Goffi Date: Tue, 3 Nov 2026 18:22:57 +0100 Subject: [PATCH] doc (apps): fix the apps documentation: The page was a messy reference, with several fields missing or incomplete. It is now completed and easier to read. --- doc/apps.rst | 139 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 87 insertions(+), 52 deletions(-) diff --git a/doc/apps.rst b/doc/apps.rst index 4aa89dd8..007ea6cc 100644 --- a/doc/apps.rst +++ b/doc/apps.rst @@ -1,21 +1,27 @@ .. _libervia-app-config: -================================= -Libervia App Configuration (YAML) -================================= +Libervia Apps +============= -The Libervia application uses a YAML configuration file to define various aspects of the -application's behavior, environment, and settings. +Libervia Apps are third party software, embedded and integrated in Libervia, usually as +containers (Podman, Docker). -The file will be parsed by `PyYAML`_ which is a full-featured YAML implementation. Check -its documentation for details. +Each app is defined by a YAML configuration file, which describes how to run it and which +settings are exposed. App files are named ``libervia_app_.yaml`` and are discovered +from the app manager plugin directories. -Below is the documentation explaining the structure and functionality of each field in the -YAML file. +Below is the documentation of each field of the YAML file. -================= +----------------- Root-Level Fields -================= +----------------- + +- ``name``: Human readable name of the application. The file name (without the + ``libervia_app_`` prefix) is used when not specified. + +- ``single_instance``: When ``True`` (default), only one instance of the application can + be started at a time, and its data are kept between restarts. When ``False``, each start + creates a new temporary instance directory, removed when the backend is unloaded. - ``type``: Specifies the type of the application. See :ref:`libervia-app_type`. @@ -27,16 +33,18 @@ Root-Level Fields - ``expose``: Specifies configurations exposed to frontends or administrators. See :ref:`libervia-app_expose`. -================== +------------------ Detailed Sections -=================== +------------------ .. _libervia-app_type: type ^^^^ -Currently, the only supported type is ``docker-compose``. +Currently, the only supported type is ``docker-compose``. The container engine is chosen +with the ``engine`` plugin setting: ``auto`` (default, Podman is tried first), ``docker`` +or ``podman``. .. _libervia-app_prepare: @@ -46,7 +54,7 @@ prepare The ``prepare`` section specifies things like git repositories to be cloned before running the application. Example -------- +~~~~~~~ Cloning the repository at `https://example.org/some/repository.git` to prepare the app: .. code-block:: yaml @@ -65,7 +73,7 @@ The YAML key is the name of the file to be created, and the content specified wi populate that file. Example -------- +~~~~~~~ Creating a file named `settings-override.py` with the content `USE_X_FORWARDED_HOST = True`: .. code-block:: yaml @@ -86,7 +94,7 @@ creates a ``docker-compose.override.yml`` file that will be merged with the defa `_. Example -------- +~~~~~~~ Overriding the `ports` for the `example_app` service to expose port `8080`: .. code-block:: yaml @@ -102,9 +110,31 @@ Overriding the `ports` for the `example_app` service to expose port `8080`: Exposing Data ^^^^^^^^^^^^^ -The `expose` section specifies the configurations that are exposed to users or frontends. -See :ref:`libervia-app_param` for a reference of some exposed data. Ports and generated -passwords are exposed in dicts, respectively at the ``ports`` and ``passwords`` key. +The ``expose`` section specifies the data exposed to users, frontends or administrators. + +The following keys are used by the Web frontend: + +url_prefix + The internal URL where the app will be served. +web_label + Label which will be used in the Web frontend. +web_url_path + Public facing URL path which will be used in the Web frontend to access the app. +web_external + If True, the Web frontend will open the app in a separated page instead of embedding + it. +front_url + Whole URL to access the app, useful when it has its own domain or subdomain. The + ``https`` scheme is added if not specified. + +Ports and generated passwords are exposed in dicts, respectively at the ``ports`` and +``passwords`` keys. Each entry of ``ports`` maps a name to the compose ``service`` and +``private`` (container) port, it is resolved to the exposed ``host:port`` when the app is +running. Each entry of ``passwords`` maps a name to the list of keys leading to the value +to expose in the application data. + +``url_prefix`` and ``front_url`` can also be specified as a list of keys leading to the +value in the application data. .. _libervia-app_yaml-tags: @@ -116,32 +146,49 @@ The following YAML tags can be used in the Libervia App configuration file: .. _libervia-app_conf: !libervia_conf -++++++++++++++ +^^^^^^^^^^^^^^ -Get a value from Libervia configuration. A list is expected with either: +Get a value from the Libervia configuration. It takes a list of 1 to 4 items: -- `name` of a config parameter -- `section` and `name` of a config parameter -- `section`, `name`, and `default` value of a config parameter -- `section`, `name`, `default` value, and `filter` (either `first` or `not`) +- ``[NAME]``: the ``NAME`` option of the ``[common]`` section +- ``[SECTION, NAME]``: the ``NAME`` option of the section named ``SECTION`` +- ``[SECTION, NAME, DEFAULT]``: use ``DEFAULT`` if the option is not set +- ``[SECTION, NAME, DEFAULT, FILTER]``: apply a filter to the value (see below) -Filter options: +The ``application.`` section refers to the configuration section of the +```` application (e.g. ``application.peertube``). -- `first`: get the first item of the value -- `not`: get the opposite value (to be used with booleans) +Available filters: -Example -------- -Getting a value from Libervia configuration: +- ``first``: get the first item of the value +- ``not``: get the opposite value (to be used with booleans) + +Examples +~~~~~~~~ +Getting a value from an application configuration section: .. code-block:: yaml - !libervia_conf [section, name, default] + !libervia_conf [application.peertube, hostname] + +Getting the SMTP server from the ``[email]`` section (an empty default is +used when the option is not set): + +.. code-block:: yaml + + !libervia_conf [email, server, ""] + +Getting the first email of the ``[common]`` section admin list (using the +``first`` filter): + +.. code-block:: yaml + + !libervia_conf [common, email_admins_list, "", first] .. _libervia-app_generate_pwd: !libervia_generate_pwd -+++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^ Generate a password and store it in persistent data. If the password has already been generated previously, it is reused. @@ -152,7 +199,7 @@ Arguments: - `size` (int): Size of the password to generate. Default to 30 Example -------- +~~~~~~~ Generating a password named ``some_password`` with a size of 32 characters: .. code-block:: yaml @@ -162,35 +209,23 @@ Generating a password named ``some_password`` with a size of 32 characters: .. _libervia-app_param: !libervia_param -++++++++++++++ +^^^^^^^^^^^^^^^ Get a parameter specified when starting the application. The value can be either the name of the parameter to get, or a list as `[name, default_value]`. - - Available parameters: url_prefix - The internal URL where the app will be served. -web_label - Label which will be used in Web frontend. -web_url_path - Public facing URL path which will be used in the web frontend to access the app. -web_external - If True, the web frontend will open the app in a separated page instead of embedding - it. -front_url - Whole URL to access the app. It is specified when the app has its own domain or - subdomain. + The internal URL where the app will be served, it is given by the Web frontend. +front_url_path + The URL path which will be used in the Web frontend to access the app. Example -------- +~~~~~~~ Getting a parameter: .. code-block:: yaml !libervia_param [url_prefix, /some_app] -.. _PyYAML: https://pyyaml.org/ -