Environment Configuration

Grav now has the ability to extend the powerful configuration capabilities for different environments to support different configuration for development, staging, and production scenarios.

Automatic Environment Configuration

What this means is that you can provide as little or as much configuration changes per environment as needed. A good example of this is the Debug Bar. By default, the new Debug Bar is disabled in the core system/config/system.yaml file, and also in the user override file:


If you wanted to turn it on, you can easily enable it in your user/config/system.yaml file, however a better solution might be to have it enabled for your development environment when accessing via localhost, but disabled on your production server.

This can be easily accomplished by providing an override of that setting in the file:


where localhost is the hostname of the environment (this is what the host you enter in your browser, e.g. http://localhost/your-site) and your configuration file contains:

  enabled: true

Similarly, you may want to enable CSS and Js Asset Pipelining (combining + minification) for your production site only (user/www.mysite.com/config/system.yaml):

  css_pipeline: true
  js_pipeline: true

If your production server was reachable via http://www.mysite.com then you could also provide configuration specific for that production site with a file located at user/www.mysite.com/config/system.yaml.

Of course, you are not limited to changes to system.yaml, you can actually provide overrides for any Grav setting in the site.yaml or even in any plugin configuration!

Plugin Overrides

To override a plugin configuration YAML file is simply the same process as overriding a regular file. If the standard configuration file is located in:


Then you can override this with a setting that only overrides specific options that you want to use for local testing:


With the configuration:

  engine: smtp
    server: smtp.mailtrap.io
    port: 2525
    encryption: none
    user: '9a320798e65135'
    password: 'a13e6e27bc7205'

Theme Overrides

You can override themes in much the same way:


Can be overridden for any environment, say some production site (http://www.mysite.com):


Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to make your changes.