General Kirby configuration settings and configuration settings for plugins go into
/site/config/config.php. The config file contains a return statement with an array of config options.
Make sure to only use a single return statement in your
config.php file (with all your options defined in that one return array.
If you want to keep your
config.php clean when using more complex options, you can outsource them to individual files that you require in the return array:
Since Kirby is not being fully initialized yet when reading the configuration, you cannot use the
$kirby object or
kirby() helper in the
Config options can be used anywhere in Kirby with the
Or with the
You can pass option fallbacks as second parameter in the option methods. This can be useful if a option does not necessarily have to be set in the config file.
All configuration options
Hooks and Routes
You can register hooks or routes in your
config.php if you don't want to create a plugin for them.
You can set different options based on the domain by adding additional config files containing the domain.
By setting different options in those config files, you get a very flexible system that can be deployed to different servers and react to the current environment accordingly.
Note that the settings in the standard
config.php file are always used. If you need different settings in another environment, you will have to override those settings in the domain specific configuration file (or only set those options in your domain specific config file).
General settings for all environments should be included in the standard
config.php file to avoid code duplication.
Custom folder setup
Kirby lets you adjust its default folder setup. Every path to a system-relevant directory is called root in Kirby. All roots can be configured when Kirby is initialized, which normally happens in your
Here is an example in which the site and content folders are renamed.
All configurable roots
Public folder setup
In our Starterkit, we offer a flat setup that installs all folders directly in the document root of your server. This is not always the best solution, but it's the solution that is most compatible with all types of hosting.
A typical setup for secure, modern web applications has every private folder behind the document root and the domain points to a public folder with the
index.php and additional public assets like CSS files, images, etc.
The key to this setup is the
index.php in the
Note that the path to
/vendor/autoload.php might vary depending on your setup, for example when you install Kirby with Composer.
Shared storage folder
This example does not only use a public folder setup, it also places accounts, cache and sessions folders in a shared storage folder. This can be a useful pattern to keep track of those additional folders that need to be writable by Kirby.
Custom URL setup
If you want to serve media and assets from other domains than your main domain, you can define custom URLs for all public facing folders.
This allows you to store your media or assets in other locations on your server or even on a CDN.
Your custom URLs can be configured when Kirby is initialized, which normally happens in your
index.php. In the example below, custom URLs are set for the
All configurable URLs
The Panel has additional configuration options to include custom CSS and JS files, to move it to a different subfolder or to switch it off entirely.