doc: documentation to create a Libervia app, first draft
This commit is contained in:
parent
da80cae625
commit
b1b2fe1aa8
2 changed files with 203 additions and 0 deletions
196
doc/apps.rst
Normal file
196
doc/apps.rst
Normal file
|
|
@ -0,0 +1,196 @@
|
||||||
|
.. _libervia-app-config:
|
||||||
|
|
||||||
|
=================================
|
||||||
|
Libervia App Configuration (YAML)
|
||||||
|
=================================
|
||||||
|
|
||||||
|
The Libervia application uses a YAML configuration file to define various aspects of the
|
||||||
|
application's behavior, environment, and settings.
|
||||||
|
|
||||||
|
The file will be parsed by `PyYAML`_ which is a full-featured YAML implementation. Check
|
||||||
|
its documentation for details.
|
||||||
|
|
||||||
|
Below is the documentation explaining the structure and functionality of each field in the
|
||||||
|
YAML file.
|
||||||
|
|
||||||
|
=================
|
||||||
|
Root-Level Fields
|
||||||
|
=================
|
||||||
|
|
||||||
|
- ``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``.
|
||||||
|
|
||||||
|
.. _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 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.
|
||||||
|
|
||||||
|
.. _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 Libervia configuration. A list is expected with either:
|
||||||
|
|
||||||
|
- `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`)
|
||||||
|
|
||||||
|
Filter options:
|
||||||
|
|
||||||
|
- `first`: get the first item of the value
|
||||||
|
- `not`: get the opposite value (to be used with booleans)
|
||||||
|
|
||||||
|
Example
|
||||||
|
-------
|
||||||
|
Getting a value from Libervia configuration:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
!libervia_conf [section, name, default]
|
||||||
|
|
||||||
|
.. _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.
|
||||||
|
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.
|
||||||
|
|
||||||
|
Example
|
||||||
|
-------
|
||||||
|
Getting a parameter:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
!libervia_param [url_prefix, /some_app]
|
||||||
|
|
||||||
|
.. _PyYAML: https://pyyaml.org/
|
||||||
|
|
||||||
|
|
@ -80,3 +80,10 @@ an user may be doing a low-level pubsub request.
|
||||||
|
|
||||||
.. _JSON: https://docs.sqlalchemy.org/en/14/core/type_basics.html#sqlalchemy.types.JSON
|
.. _JSON: https://docs.sqlalchemy.org/en/14/core/type_basics.html#sqlalchemy.types.JSON
|
||||||
|
|
||||||
|
|
||||||
|
Libervia Apps
|
||||||
|
=============
|
||||||
|
|
||||||
|
Libervia has a mechanism to embed applications and configure them to integrate with the
|
||||||
|
ecosystem. This is notably used to embed docker applications. Description of the
|
||||||
|
application description file is available at :ref:`libervia-app-config`.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue