libervia-backend/doc/apps.rst

.. _libervia-app-config:

Libervia Apps
=============

Libervia Apps are third party software, embedded and integrated in Libervia, usually as
containers (Podman, Docker).

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_<name>.yaml`` and are discovered
from the app manager plugin directories.

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`.

- ``prepare``: Information required to prepare the environment. See :ref:`libervia-app_prepare`.

- ``files``: Specifies files to be created with defined content. See :ref:`libervia-app_files`.

- ``override``: Allows to override or add to default configurations. See :ref:`libervia-app_override`.

- ``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``. The container engine is chosen
with the ``engine`` plugin setting: ``auto`` (default, Podman is tried first), ``docker``
or ``podman``.

.. _libervia-app_prepare:

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

  prepare:
    git: https://example.org/some/repository.git

.. _libervia-app_files:

files
^^^^^

The ``files`` section specifies additional files to be created for the application.

The YAML key is the name of the file to be created, and the content specified will
populate that file.

Example
~~~~~~~
Creating a file named `settings-override.py` with the content `USE_X_FORWARDED_HOST = True`:

.. code-block:: yaml

  files:
    settings-override.py:
      content: |
        USE_X_FORWARDED_HOST = True

.. _libervia-app_override:

override
^^^^^^^^

The ``override`` section allows for the specification or override of configurations. This
creates a ``docker-compose.override.yml`` file that will be merged with the default
``docker-compose.yml``. For more information, see `Docker documentation
<https://docs.docker.com/compose/reference/#specifying-multiple-compose-files>`_.

Example
~~~~~~~
Overriding the `ports` for the `example_app` service to expose port `8080`:

.. code-block:: yaml

  override:
    services:
      example_app:
        ports:
          - "8080"

.. _libervia-app_expose:

Exposing Data
^^^^^^^^^^^^^

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:

YAML Tags
^^^^^^^^^

The following YAML tags can be used in the Libervia App configuration file:

.. _libervia-app_conf:

!libervia_conf
^^^^^^^^^^^^^^

Get a value from the Libervia configuration. It takes a list of 1 to 4 items:

- ``[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)

The ``application.<name>`` section refers to the configuration section of the
``<name>`` application (e.g. ``application.peertube``).

Available filters:

- ``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 [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.

Arguments:

- `name` (str) **required**: Name of the password. Will be used to store it so it kept
  between restarts.
- `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

  !libervia_generate_pwd {name: some_password, size: 32}

.. _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, 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]