YAML Configuration

YAML ("YAML Ain't Markup Language") is a human-readable data file format, well suited to human-edited configuration files. Nearly all aspects of your project's build and deploy pipeline are controlled via YAML files.

YAML is a whitespace-sensitive format that is especially good at key/value type configuration, such as that used by Platform.sh. There are many good YAML tutorials online and the format is reasonably self-documenting. We especially recommend:

The following is only a cursory look at YAML itself. The tutorials above will provide a more in-depth introduction.

Basic YAML

A YAML file is a text file that ends in .yaml. (Some systems use an alternative .yml extension, but Platform.sh uses the four-letter extension.) It consists primarily of key value pairs, and supports nesting. For example:

name: 'app'
type: 'php:7.1'
build:
    flavor: 'composer'

disk: 1024

This example defines a key name with value app, a key type with value php:7.1, a key disk with a value 1024, and a key build that is itself a nested set of key/value pairs, of which there is only one: flavor, whose value is composer. Informally, nested values are often referenced using a dotted syntax, such as build.flavor, and that format is used in this documentation in various places.

Keys are always strings, and may be quoted or not. Values may be strings, numbers, booleans, or further nested key/value pairs. Alphanumeric strings may be quoted or not. More complex strings (with punctuation, etc.) must be quoted. Numbers should not be quoted. The boolean values true and false should never be quoted.

For quoted values, both single quotes (') and double quotes (") are valid. Double quotes, however, will interpolate common escape characters such as \n and so forth. For that reason using single quotes is generally recommended unless you want escape characters to be processed rather than taken literally.

In general the order of keys in a YAML file does not matter. Neither do blank lines. Indentation may be with any number of spaces, as long as it is consistent throughout the file. Platform.sh examples by convention use four-space indentation.

Multi-line strings

In case of long, multi-line strings, the | character tells the YAML parser that the following, indented lines are all part of the same string. That is, this:

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

creates a nested property hooks.build, which has the value set -e\ncp a.txt b.txt. (That is, a string with a line break in it.) That is useful primarily for hooks, which allow the user to enter small shell scripts within the YAML file.

Includes

YAML allows for special "tags" on values that change their meaning. These tags may be customized for individual applications so may vary from one system to another. The main Platform.sh "local tag" is !include, which allows for external files to be logically embedded within the YAML file. The referenced file is always relative to the YAML file's directory.

string

The string type allows an external file to be inlined in the YAML file as though it had been entered as a multi-line string. For example, given this file on disk named build.sh:

set -e
cp a.txt b.txt

Then the following two YAML fragments are exactly equivalent:

hooks:
    build: |
        set -e
        cp a.txt b.txt
hooks:
    build: !include
      type: string
      path: build.sh

That is primarily useful for breaking longer build scripts or inlined configuration files out to a separate file for easier maintenance.

binary

The binary type allows an external binary file to be inlined in the YAML file. The file will be base64 encoded. For example:

properties:
    favicon: !include
        type: binary
        path: favicon.ico

will reference the favicon.ico file, which will be provided to Platform.sh's management system.

archive

The archive type specifies that the value it tags is a reference to a directory on disk, relative to the location of the YAML file. Essentially it defines the value of key as "this entire directory". Consider this services.yaml fragment:

mysearch:
    type: solr:6.6
    disk: 1024
    configuration:
        core_config: !include
            type: archive
            path: "solr/conf"

In this case, the mysearch.configuration.core_config value is not the string "solr/conf", but the contents of the solr/conf directory (relative to the services.yaml file). On Platform.sh, that is used primarily for service definitions in services.yaml to provide a directory of configuration files for the service (such as Solr in this case). Platform.sh will use that directive to copy the entire specified directory into our management system so that it can be deployed with the specified service.

Alternatively, an older short-hand version of archive is still available. The following fragment has exactly the same meaning as the one above:

mysearch:
    type: solr:6.6
    disk: 1024
    configuration:
        core_config: !archive "solr/conf"

yaml

Finally, the yaml type allows an external YAML file to be inlined into the file as though it had been typed in directly. That can help simplify more complex files, such a .platform.app.yaml file with many highly-customized web.locations blocks.

The yaml type is the default, meaning it may reference a file inline without specifying a type.

For example, given this file on disk named main.yaml:

root: 'web'
expires: 5m
passthru: '/index.php'
allow: false
rules:
    '\.(jpe?g|png|gif|svgz?|css|js|map|ico|bmp|eot|woff2?|otf|ttf)$':
        allow: true
    '^/robots\.txt$':
        allow: true
    '^/sitemap\.xml$':
        allow: true

Then the following three location definitions are exactly equivalent:

web:
    locations:
        '/': !include "main.yaml"
web:
    locations:
        '/': !include 
            type: yaml
            path: 'main.yaml'
web:
    locations:
        '/': 
            root: 'web'
            expires: 5m
            passthru: '/index.php'
            allow: false
            rules:
                '\.(jpe?g|png|gif|svgz?|css|js|map|ico|bmp|eot|woff2?|otf|ttf)$':
                    allow: true
                '^/robots\.txt$':
                    allow: true
                '^/sitemap\.xml$':
                    allow: true