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.
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
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.
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.
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 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
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 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.
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
yaml type is the default, meaning it may reference a file inline without specifying a type.
For example, given this file on disk named
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
Another custom tag available is
!archive, which specifies a value 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
mysearch: type: solr:8.0 disk: 1024 configuration: conf_dir: !archive "solr/conf"
In this case, the
mysearch.configuration.conf_dir 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.