Kirby is compatible with many different web servers. However, in reality it is mostly Apache and sometimes nginx which are being used as webservers to run Kirby on. But there is also another, modern and very easy-to-configure alternative in the webserver world: Caddy v2.
Just like nginx, the Caddy webserver does not use the famous and project-specific
.htaccess files that Kirby ships with. So instead of using this file, you'll have to configure the webserver manually through a special configuration file called
Caddyfile. Caddy tries to load this file from the current directory, so run Caddy from the same folder that contains your
Caddyfile or pass the path manually with
caddy run --config /path/to/Caddyfile.
Caddy uses its own configuration file format and syntax. These Caddyfiles are typically very short and efficient and allow you to configure a webserver with a low number of lines. This is also due to the fact that Caddy uses a lot of very good and modern defaults compared to older webservers like Apache. Therefore Caddy makes it very easy to host websites with very little configuration and something like TLS only requires a single line in a Caddy configuration.
Web server configuration is a very big topic and there are many things to consider for every individual use case. We can only offer a starting point for a good config and we can't cover every aspect in this article. So this article will not cover every aspect of webserver configuration (e.g. performance-related optimizations).
We're creating two custom snippets here with the names
kirby. Snippets are blocks of configuration directives, which we can later reference and reuse. It's good style to put application-specific settings into their own snippets to know why given settings were initially put in place. So we're splitting our settings into a
common snippet and
This is the line that does the handover to the PHP interpreter. We're using the modern FastCGI interface for this handover. The
php_fastcgi directive takes a network address or unix socket as a parameter, where a PHP-FPM process is listening and waiting for scripts to be run. So this setting depends on your specific setup. If you're using Docker, you can set the name and port of your FPM container (e.g.
php:9000). If you're running PHP-FPM on the same system, you can use
localhost followed by the port number.
php_fastcgi directive also comes with a lot of good default values for PHP-specific configuration values (e.g. it automatically sets
try_files to look for an
index.php file – so a request gets forwarded to PHP when there is no file with a specific name)
This directive will take care of your TLS certificate. If you want to use a free certificate from Let's Encrypt, enter your email address here and you're done. If you want to run your Kirby site locally, use
tls internal for a self-signed certificate.
Here we are defining a custom matcher – which is a statement that we can then use in multiple locations as an argument for other directives. Our matcher is called
@blocked – because we're defining paths which should not be accessible by website visitors: all raw txt/md files and everything in the
kirby folders, as well as hidden files. In the following line, we're redirecting all these requests to the home page of our site.
This is a site block, which is the top level component of a Caddyfile. The block begins with the address of our server. We're defining the domain so that Caddy can route incoming requests to the site and generate a certificate for it. Instead you can also put an IP address or a port number here (like
:80), depending on your server setup.
Here, we're importing/using the two snippets we defined earlier. Also we're setting the root folder for this server, which should point to the absolute filesystem path, where your Kirby files are located.