# 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 type.

- `prepare`: Information required to prepare the environment. See prepare.

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

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

- `expose`: Specifies configurations exposed to frontends or administrators. See Exposing Data.

## type

Currently, the only supported type is `docker-compose`.

## 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:

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

## 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:

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

## 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:

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

## Exposing Data

The expose section specifies the configurations that are exposed to users or frontends. See !libervia_param for a reference of some exposed data. Ports and generated passwords are exposed in dicts, respectively at the `ports` and `passwords` key.

## YAML Tags

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

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:

    !libervia_conf [section, name, default]

#### !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:

    !libervia_generate_pwd {name: some_password, size: 32}

#### !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:

    !libervia_param [url_prefix, /some_app]