# HG changeset patch # User Goffi # Date 1717146498 -7200 # Node ID 00852dd546954e8f318a7baeb821f4befd914711 # Parent 4aa62767f5015d43d38d1815736874b1decb9848 doc: documentation to create a Libervia app, first draft diff -r 4aa62767f501 -r 00852dd54695 doc/apps.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/apps.rst Fri May 31 11:08:18 2024 +0200 @@ -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 +`_. + +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/ + diff -r 4aa62767f501 -r 00852dd54695 doc/developer.rst --- a/doc/developer.rst Fri May 31 11:08:14 2024 +0200 +++ b/doc/developer.rst Fri May 31 11:08:18 2024 +0200 @@ -80,3 +80,10 @@ .. _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`.