User Guides

Configuration Introduction

Configuration files are written in YAML. This allows configuration files to be easily written and understood by everyone.


Configuration Stages

LexasCMS uses an extension and inheritance approach to configuration. Configs are loaded in three stages, with each stage extending the previous. The three stages are:

Stage 1: Base Configuration

The base configuration is provided by LexasCMS itself and defines defaults for a majority of the systems functionality. For example, this is where the default database configuration is defined as SQLite.

Stage 2: Default Configuration

The default configuration is provided by you, it extends from the base configuration and can be used to define defaults specific to your website. This configuration stage is useful for defining configs that will be same for all environments, for example, in a majority of cases assets will be the same across all of your environments.

Config files that you would like to be loaded in this stage should be placed in the config/default/ directory, e.g. config/default/assets.yaml.

Stage 3: Environment Configuration

Environment specific configurations are provided by you, this stage extends from the default configuration and allows you to define configs that are specific to a particular environment. For example, you would probably want to use a different database configuration for staging and production environments than you would in your development environment. This would be achieved by defining database.yaml files at config/staging/database.yaml and config/production/database.yaml respectively.

These config files would then be loaded when the environment had been configured (see Environment Configuration) as either staging or production.


Dynamic Values

For many reasons, you may not always be able to define config values statically and may require that values are defined dynamically at run time. For these situations you have several methods available for retrieving values from other sources.

Loading from an environment variable

Loading a value from an environment variable is very common. It is good security practice to store sensitive information such as API keys in environment variables instead of directly in config files. This method will usually be preferred by many PaaS hosting environments such as Heroku.

someConfigKey: ENV:ENVIRONMENT_VARIABLE_NAME

Loading a value from a file

It is also possible to load the contents of a file as the value for a config key.

someConfigKey: FILE:somefile.txt

Loading a value from a JSON file

If the file you are loading the value from contains JSON, you can use the JSONKEY prefix to use a particular keys value as the config value.

someConfigKey: JSONKEY:somefile.json:KEY_NAME

Loading a value from a YAML file

If the file you are loading the value from contains YAML, you can use the YAMLKEY prefix to use a particular keys value as the config value.

someConfigKey: YAMLKEY:somefile.yaml:KEY_NAME