(application-templates-feature)=

# Application templates

```{contents}
:depth: 4
:backlinks: none
```

This document explains the **Application templates** feature in Fleio.

A Fleio **Application template** consists of a set of customizable scripts that can be used to configure an instance 
when it is created.

Currently, application templates are only compatible with Linux instances with cloud init support.

## User flow

When the user creates an instance, if the **Application templates** features is enabled and some application templates 
were configured in Fleio, the user will be presented with a list of applications template to select from.

The user can the select one of the available applications, configure required and optional parameters, and proceed to 
launch the instance.

If the instance is launched with a configured application template, Fleio will automatically deploy the selected 
application within the launched instance.

## Application repository

Fleio supports loading and using application templates from Git repositories. It can search for application templates 
either in the root of the repository or within a specified path.

Each directory within the designated repository path that follows the correct structure is recognized as an application 
template.


### Application template directory structure

An application template directory must contain a **scripts** subdirectory and a **fleio-metadata.yaml** file. If both
are present and the **fleio-metadata.yaml** file loads successfully, the directory is treated as a valid application 
template and imported into Fleio.

#### Scripts folder

Scripts folder can contain any script file. Parameters are replaced in these files based on **fleio-medatata.yaml** 
specifications.

On deploy all the files in this directory will be copied to the target instance in **"/root/init-scripts"** directory.

### Fleio Metadata File (YAML)
The Fleio metadata file is a YAML file that defines metadata for an application. The following top-level tags are 
supported:

#### Top-Level Tags
-  Optional: **`version`**
   - The metadata schema version (currently `1`). This may increase in the future if breaking changes are introduced.

-  Required: **`application_info`**
   - Contains essential details about the application.
   - **Required:** `name`
   - **Optional:** `description`, `image_url`

-  Optional: **`requirements`**
   - Defines resource and distribution requirements for the application.
   - **Optional:** `vcpus`
   - **Optional:** `memory_mb` - minimum required memory MB
   - **Optional:** `disk_gb` - minimum required root disk space in GB, 
   - **Optional:** `distribution` - a list of distributions supported by this template (e.g., `ubuntu`, `centos`).

-  Optional: **`parameters`**
   - Defines configurable parameters for the application scripts.
   - Each parameter may include the following fields:

| Field               | Description                                                                        |
|---------------------|------------------------------------------------------------------------------------|
| **`display_name`**  | Human-readable name for the parameter.                                             |
| **`description`**   | Explanation of the parameter's purpose.                                            |
| **`type`**          | Data type (`string`, `number`, `date`, `choices`, etc.).                           |
| **`options`**       | For `choices` type: an array of `{name, value}` pairs.                             |
| **`validation`**    | Validation rules (e.g., `required`, `min`, `max`, `regex`).                        |
| **`default_value`** | Default value if none is provided.                                                 |
| **`script_file`**   | Path (relative to the `scripts` folder) where the parameter will be inserted.      |
| **`placeholder`**   | A placeholder in the script file that Fleio will replace with the parameter value. |

-  Optional: **`initial_command`**

An optional command executed **after** the **scripts** directory is copied to the instance. Runs inside the **scripts**
directory on the target machine. 

If not specified it defaults to `bash ./setup.sh`.

## How are applications deployed

When deploying an application, Fleio follows these steps:

1. **Copy the application folder** from the repository.
2. **Replace parameters** in the script files as needed.
3. **Create an archive** of the `scripts` folder contents.
4. **Generate a cloud-init script** that performs the following actions:
   - Writes the scripts archive to the instance.
   - Extracts the archive into the `/root/init-scripts` folder.
   - Executes the `initial_command` (default: `bash ./setup.sh`).