menu

Configuration

From database settings to image optimization and different environments

Support the documentation

This documentation was written by volunteers. Please help support our effort:

Help us improve the documentation

Neos is not a single piece of software but assembled of several different packages. Each package brings it's own configuration keys. We store those settings in YAML files.

How to write configuration?

All Neos and Flow packages use YAML files to describe their settings. This is the same configuration language that is used to define NodeTypes.

# This is an example for a YAML file.
# Those files end with .yml or .yaml

string1: Hello
string2: "Hello"
number: 1233
bool: true

# Both array definitions are equal.
Array:
  - First
  - Second
  - Third

Array: ["First", "Second", "Third"]

# This is a real example. It disabled the automatic
# logout after 60min of inactivity.
Neos:
  Flow:
    session:
      inactivityTimeout: 0

YAML files have strict formatting rules.

You have to get the formatting right. Whenever you are working with YAML files remember the following rules.

Correct formatting of YAML files

  1. Only whitespaces are allowed for indentation. This is very important and the number one issue when something is not working. A single missing whitespace can break a whole config file.
  2. Use two whitespaces to nest configuration keys.
  3. Only UTF-8 as file encoding is allowed.

Tutorials Point has a good introduction into the YAML file format.

Where should I place my configuration?

Configuration changes can be made in several different places but everythingt lives inside one big configuration tree. There is no differentiation between different sites. If you need site specific configurations you need to set up two different Neos instances.

  1. /Packages/Sites/<SiteName>/Configuration/
  2. /Configuration/

Everything related to a specific site should be configured in the respective site package. General settings like database configurations should be in the global Configuration directory.

Neos is based on the Flow Framework. Be sure to check out the official Flow docs.

What settings are available?

Currently, we do not have a extensive list over the configuration options. Although inconvenient, you can directly look in the base configuration files of each packages. There are several important packages to look for:

  1. Neos.Neos (the CMS itself)
  2. Neos.Media (the file and media management)

Troubleshooting

  1. My configuration is not loaded. If you placed your site package directly under Packages/Sites you may have an issue with the loading order of the packages. For this exact reason we recommend a different approach. A hotfix is to store your settings in the global Configuration folder. This is regarded as a bad practice and we recommend switching to the new approach as we may be removing support for storing packages directly in the file system.

Further Reading