Upsun YAML tags

In addition to the basic functions you should be familiar with, YAML allows for special tags. Upsun accepts certain custom tags to facilitate working with configuration files. These tags work with Upsun configuration files, but may not elsewhere.

Include

Use the !include tag to embed external files within a given YAML file. The tag requires two properties:

Property	Type	Possible values	Description
`type`	`string`	`string`, `binary`, or `yaml`	See the descriptions of strings, binaries, and YAML. Defaults to `yaml`.
`path`	`string`		The path to the file to include, relative to the application directory or `source.root`.

By default, path is relative to the current application’s directory (what you would define with source.root). It is possible to include files from a directory parent to the folder however.For example, for the following project structure:

.
├── .upsun/
|   └── .upsun/config.yaml
├── backend
│   ├── main.py
│   ├── requirements.txt
│   └── scripts
│       ├── ...
│       └── common_build.sh
└── frontend
    ├── README.md
    ├── package-lock.json
    ├── package.json
    ├── public
    ├── scripts
    │   └── clean.sh
    └── src

This configuration is valid:

.upsun/config.yaml

applications:
  frontend:
    source:
      root: frontend

    # ...

    hooks:
      build: !include
        type: string
        path: ../backend/scripts/common_build.sh

`string`

Use string to include an external file inline in the YAML file as if entered as a multi-line string. For example, if you have a build hook like the following:

.upsun/config.yaml

applications:
  myapp:
    hooks:
      build: |
        set -e
        cp a.txt b.txt

You could create a file for the script:

build.sh

set -e
cp a.txt b.txt

And replace the hook with an include tag for an identical result:

.upsun/config.yaml

applications:
  myapp:
    hooks:
      build: !include
        type: string
        path: build.sh

This helps you break longer configuration like build scripts out into a separate file for easier maintenance. Even if path is relative to the current application’s directory, it is also possible to include a shell script from a directory parent to the folder however. For example, for the following project structure:

.
├── .upsun/
|   └── config.yaml
├── backend
│   ├── main.py
│   ├── requirements.txt
│   └── scripts
│       ├── ...
│       └── common_build.sh
└── frontend
    ├── README.md
    ├── package-lock.json
    ├── package.json
    ├── public
    ├── scripts
    │   └── clean.sh
    └── src

This configuration is valid:

.upsun/config.yaml

applications:
  frontend:
    source:
      root: frontend
    # ...
    hooks:
      build: !include
        type: string
        path: ../backend/scripts/common_build.sh

Please note that Upsun will execute this ../backend/scripts/common_build.sh script using Dash.

`binary`

Use binary to include an external binary file inline in the YAML file. The file is base64 encoded. For example, you could include a favicon.ico file in the same folder as your app configuration. Then you can include it as follows:

.upsun/config.yaml

some-property:
  favicon: !include
    type: binary
    path: favicon.ico

`yaml`

Use yaml to include an external YAML file inline as if entered directly. Because yaml is the default, you can use it without specifying the type. For example, you could have your configuration for works defined in a worker.yaml file:

worker.yaml

commands:
  start: python queue-worker.py
variables:
  env:
    type: worker

Then the following three configurations are exactly equivalent:

.upsun/config.yaml

workers:
  queue1: !include "worker.yaml"

.upsun/config.yaml

workers:
  queue1: !include
    type: yaml
    path: 'worker.yaml'

.upsun/config.yaml

workers:
  queue1:
    commands:
      start: python queue-worker.py
    variables:
      env:
        type: worker

This can help simplify more complex files. For multiple application project, you can also include another .upsun/apps/my-app.yaml file in the main .upsun/config.yaml.

.upsun/apps/my-app.yaml

source:
  root: "/"
type: "nodejs:18"
web:
  commands:
    start: "node index.js"
  upstream:
    socket_family: tcp
  locations:
    "/":
      passthru: true

and including it:

.upsun/config.yaml

applications:
  myapp:
    !include ./apps/my-app.yaml

Get Started

Core Concepts

Configure Apps & Services

Build, Deploy & Run

Manage Projects

Manage Environments

Manage Resources

Observability & Metrics

Integrations

Troubleshooting

Resources

Include

`string`

`binary`

`yaml`

Archive

​Include

​string

​binary

​yaml

​Archive

Include

`string`

`binary`

`yaml`

Archive