> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsun Cloud YAML structure

> A description of the YAML file for Upsun Cloud.

In addition to the [basic functions you should be familiar with](https://developer.upsun.com/docs/core-concepts/yaml/what-is-yaml.md), YAML structure is important.
Upsun Cloud accepts a specific structure for YAML configuration files.

## YAML file location

When you run the [`upsun project:init` command](https://developer.upsun.com/docs/get-started/here/configure), a default `config.yaml` file is generated in the `.upsun` folder. It contains the minimum default configuration based on your detected local stack.
This YAML file is located in your `.upsun` directory, at the root of your project source code, and is a good starting point before customization.

```text theme={null}
.
├── .upsun/
│   └── config.yaml
└── <SOURCE_CODE>
```

## Top-level keys

In the `config.yaml` file, there are three top-level YAML keys:

* `applications`: this section of the file contains all of your [app definitions](https://developer.upsun.com/docs/configure-apps/app-reference/single-runtime-image.md)

> [!NOTE]
>
> Note that `applications` is a **mandatory** top-level key to include in your `config.yaml` file.

* `routes`: this section of the file contains all of your [route definitions](https://developer.upsun.com/docs/routes) (for each of your apps)
* `services`: this section of the file contains all of your [service definitions](https://developer.upsun.com/docs/add-services) (for each of your apps)

This looks like:

```yaml apps theme={null}
applications:
  myapp:
    ...

services:
  mariadb:
    type: mariadb:10.6 # All available versions are: 10.6, 10.5, 10.4, 10.3

routes:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"
```

Below these three top-level key sections, you can use any of the [available YAML tags](https://developer.upsun.com/docs/core-concepts/yaml/platform-yaml-tags.md) you need.

> [!NOTE]
>
> Any YAML files located at the first level of your `.upsun/` folder, at the root of your project source code, are taken in account. See [Rules on YAML files](#rules-on-yaml-files).

## Rules on YAML files

The following rules apply to YAML files contained in the `.upsun/` folder:

* All the existing YAML files located at the first level of the `.upsun/` folder are taken into account.
* All the existing YAML files located at the first level of the `.upsun/` folder must feature the [mandatory top-level keys](#top-level-keys), and must contain a [valid YAML configuration](https://developer.upsun.com/docs/configure-apps/app-reference/single-runtime-image.md).
* All the YAML files in subdirectories of the `.upsun/` folder need to be [manually imported](https://developer.upsun.com/docs/core-concepts/yaml/platform-yaml-tags.md#include) and contain a [valid YAML configuration](https://developer.upsun.com/docs/configure-apps/app-reference/single-runtime-image.md).

> [!WARNING]
>
> Warning
> When Upsun Cloud combines all the YAML files located at the first level of the `.upsun/` folder, only the top-level keys (`applications`, `services`, and `routes`) are merged. So if you define an app named `myapp` in two different YAML files, Upsun Cloud only takes the second one into account.
>
> Example:
>
> ```yaml .upsun/app.yaml theme={null}
> applications:
>   myapp:
>     type: nodejs:16
>     source:
>       root: folder1
>     ...
> ```
>
> ```yaml .upsun/app-bis.yaml theme={null}
> applications:
>   myapp:
>     type: nodejs:20
>     build:
>       flavor: none
>     ...
> ```
>
> Once Upsun Cloud has combined the two configuration files,
> the blended configuration will be the following:
>
> ```yaml YAML config result theme={null}
> applications:
>   myapp:
>     type: nodejs:20
>     build:
>       flavor: none
>     ...
> ```
>
> Note that `source.root` (and any other `.upsun/app.yaml` parameters) will *not* be included in the final configuration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.