Skip to main content
In addition to the basic functions you should be familiar with, YAML structure is important. Upsun accepts a specific structure for YAML configuration files.

​
YAML file location

When you run the upsun project:init command, 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. 
.
├── .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
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 (for each of your apps)
  • services: this section of the file contains all of your service definitions (for each of your apps)
This looks like:
apps
<Tooltip tip="Complete list of all available properties">[applications](/docs/create-apps/app-reference/single-runtime-image.html)</Tooltip>:
  myapp:
    ...

<Tooltip tip="Click to see the complete list of all available services">[services](/docs/add-services.html#available-services)</Tooltip>:
  mariadb:
    type: mariadb:10.6 # All available versions are: 10.6, 10.5, 10.4, 10.3

<Tooltip tip="The routes of the project. Each route describes how an incoming URL is going to be processed by Upsun (Staging). Click for more information.">[routes](/docs/define-routes.html)</Tooltip>:
  "https://{default}/":
    type: upstream
    upstream: "myapp:http"
Below these three top-level key sections, you can use any of the available YAML tags you need.
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

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

Warning

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:
.upsun/app.yaml
applications:
  myapp:
    type: nodejs:16
    source:
      root: folder1
    ...
.upsun/app-bis.yaml
applications:
  myapp:
    type: nodejs:20
    build:
      flavor: none
    ...
Once Upsun has combined the two configuration files, the blended configuration will be the following:
YAML config result
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.
Last modified on March 10, 2026