.. _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_.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 `_. 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.`` section refers to the configuration section of the ```` 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]