Platform.sh User Documentation

Platform.sh YAML tags

Try for 30 days
Flexible, version-controlled infrastructure provisioning and development-to-production workflows
Activate your trial

In addition to the basic functions you should be familiar with, YAML allows for special tags. Platform.sh accepts certain custom tags to facilitate working with configuration files.

These tags work with Platform.sh configuration files, but may not elsewhere.

Include Anchor to this heading

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 if defined.

By default, path is relative to the current application’s directory (what you would define with source.root).

For example, to include another .platform/app1.yaml file in the main .platform/applications.yaml, follow these steps:

  1. Write and save your .platform/app1.yaml file:
.platform/app1.yaml
source:
root: "/"
type: "nodejs:20"
web:
    commands:
      start: "node index.js"
upstream:
    socket_family: tcp
locations:
    "/":
        passthru: true

And including it:

.platform/applications.yaml
app: !include
    type: yaml
    path: ./app1.yaml
# or as default type is "yaml", it could be:
#api: !include ./app1.yaml

You can also include files from a directory that is parent to the folder.

For example, for the following project structure:

.
โ”œโ”€โ”€ .platform
|ย ย  โ””โ”€โ”€ applications.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:

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

string Anchor to this heading

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:

.platform/applications.yaml
frontend:
    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:

.platform/applications.yaml
frontend:
    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.

binary Anchor to this heading

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:

.platform/applications.yaml
properties:
    favicon: !include
        type: binary
        path: favicon.ico

yaml Anchor to this heading

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
size: S
commands:
    start: python queue-worker.py
variables:
    env:
        type: worker

Then the following three configurations are exactly equivalent:

.platform.app.yaml
workers:
    queue1: !include "worker.yaml"
.platform.app.yaml
workers:
    queue1: !include
        type: yaml
        path: 'worker.yaml'
.platform.app.yaml
workers:
    queue1:
        size: S
        commands:
            start: python queue-worker.py
        variables:
            env:
                type: worker

This can help simplify more complex files.

Archive Anchor to this heading

Use the !archive tag for a reference to an entire directory specified relative to where the YAML file is.

For example, you might want to define a configuration directory for your Solr service. You might do so as follows:

.platform/services.yaml
mysearch:
    type: solr:8.0
    disk: 1024
    configuration:
        conf_dir: !archive "solr/conf"

The !archive tag means that the value for conf_dir isn’t the string solr/conf but the entire solr/conf directory. This directory is in the .platform directory, since that’s where the .platform/services.yaml file is. The solr/conf directory is then copied into the Platform.sh management system to use with the service.

Is this page helpful?