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.
This commit is contained in:
Goffi
parent
fc0a385027
commit
0c955f6abd
1 changed files with 87 additions and 52 deletions
139
doc/apps.rst
139
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_<name>.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
|
|||
<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
|
||||
|
|
@ -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.<name>`` section refers to the configuration section of the
|
||||
``<name>`` 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/
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue