Upsun YAML structure
Back to home
On this page
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> Mandatory top-level keys
In the config.yaml file, there are only three mandatory top-level YAML keys:
applications: this section of the file contains all of your app definitionsroutes: 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:
applications:
app:
...
services:
mariadb:
type: mariadb:10.6 # All available versions are: 10.6, 10.5, 10.4, 10.3
routes:
"https://{default}/":
type: upstream
upstream: "app:http"Below these three top-level key sections, you can use any of the available 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
The following rules apply to YAML files contained in the .upsun folder:
- All the existing YAML files located at the first level of the
.upsunfolder are taken into account. - All the existing YAML files located at the first level of the
.upsunfolder must feature the mandatory top-level keys, and must contain a valid YAML configuration. - All the YAML files in subdirectories of the
.upsunfolder need to be manually imported and contain a valid YAML configuration.
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 app in two different YAML files, Upsun only takes the second one into account.
Example:
applications:
app:
type: nodejs:16
source:
root: folder1
...applications:
app:
type: nodejs:20
build:
flavor: none
...Once Upsun has combined the two configuration files, the blended configuration will be the following:
applications:
app:
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.