Introduction to YAML¶

YAML is a human-friendly format that we use for metadata exports and configuration files because of its simplicity and widespread support. The name originally meant Yet Another Markup Language. Common file extensions are .ymland .yaml.

Values are represented in the form key: value with one entry per line:

Type: image
Title: "La Tour Eiffel 🌈"
Year: 2014
# Key-Value Collection Example:
Details:
  Notes: "Bonjour\nla France!" 
  Keywords: 'paris, france' # Comment

Basic Rules¶

Keys are case-sensitive
Related values must start at the same indentation level
- We recommend using 2 spaces, but any number will work as long as it is consistent
- Tabs are not allowed for indentation and using them may result in errors
Comments begin with #, can start anywhere on a line, and continue until the end of the line
You can generally use all Unicode characters in YAML files, including Emojis
- To avoid ambiguity, it is recommended to enclose text strings in single ' or double quotes ", especially if they contain spaces or Boolean values like "true" or "false"
- The difference between single and double quotes is that double quotes support escape sequences like \t for a tab or \n for a new line
- Additional special characters may need to be escaped, e.g. the $ sign when working with Docker Compose

Multiple Values¶

List are lines that start at the same indentation level and begin with a dash and a space as shown in the example below. They are commonly used to define service dependencies, exposed network ports, or folders shared between host and container in compose.yaml files:

services:
  photoprism:
    depends_on:
      - mariadb
      - nextcloud
    ports:
      # "host:container"
      - "2342:2342"
    volumes:
      # "/host/folder:/container/folder"
      - "/photos:/photoprism/originals"

Key-Value Pairs¶

Collections of key-value pairs are commonly used to specify the names and values of environment variables in compose.yaml files (see below for additional rules). Similar to lists, the keys of related values start at the same indentation level, but without a dash:

services:
  mariadb:
    environment:
      MARIADB_AUTO_UPGRADE: "1"
      MARIADB_INITDB_SKIP_TZINFO: "1"
      MARIADB_ROOT_PASSWORD: "Y(&^UIk34"
      MARIADB_DATABASE: photoprism
      MARIADB_USER: photoprism
      MARIADB_PASSWORD: insecure

Docker Compose¶

When using Docker Compose, some additional rules apply, as compose.yaml or docker-compose.yml files extend the YAML format with features such as variable interpolation.

Dollar Signs¶

If a configuration value in a compose.yaml or docker-compose.yml file contains a literal $ character, for example in a password, you must use $$ (a double dollar sign) to escape it so that e.g. "compo$e" becomes "compo$$e":

services:
  mariadb:
    environment:
      # sets password to "compo$e"
      MARIADB_PASSWORD: "compo$$e"

Values that contain a $ are otherwise interpreted as a variable. In this case, both the $VARIABLE and the ${VARIABLE} syntax are supported. Further details on the use of variables can be found in the file format reference.

True / False¶

Boolean variable values like "true", "false", "yes", "no", "on", or "off" must be enclosed in double or single quotes so that they are passed as intended:

services:
  photoprism:
    environment:
      PHOTOPRISM_DEFAULT_TLS: "true"
      PHOTOPRISM_READONLY: "false"

If you otherwise specify true as a value without quotes, Docker Compose will pass the host variable of the same name to the container instead of setting the value to "true" (results in an empty string if no environment variable with the same name is set on the host):

services:
  photoprism:
    environment:
      # evaluated as "" (false)
      PHOTOPRISM_READONLY: true