> ## 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 YAML structure

> A description of the YAML file for Upsun.

{/* Import section */}

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

## YAML file location

When you run the [`upsun project:init` command](/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](/docs/configure-apps/app-reference/single-runtime-image)

<Note>
  Note that `applications` is a **mandatory** top-level key to include in your `config.yaml` file.
</Note>

* `routes`: this section of the file contains all of your [route definitions](/docs/routes) (for each of your apps)
* `services`: this section of the file contains all of your [service definitions](/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](/docs/core-concepts/yaml/platform-yaml-tags) 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).
</Note>

## 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](/docs/configure-apps/app-reference/single-runtime-image).
* All the YAML files in subdirectories of the `.upsun/` folder need to be [manually imported](/docs/core-concepts/yaml/platform-yaml-tags#include) and contain a [valid YAML configuration](/docs/configure-apps/app-reference/single-runtime-image).

<Warning>
  <h4>Warning</h4>
  When Upsun 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 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 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.
</Warning>