Error

This guide seems to be broken for the current versions of XYZ, we would be happy if you want to work on a solution and create a Pull Request. See also the related issue: https://github.com/Uberspace/lab/issues/1431

Kirby

Kirby is a modern, fast, flexible, file-based (no database) content management system written in PHP.

The idea behind Kirby is to provide a tool for developing websites or applications that is both easy to use for developers and at the same time gives you all the freedom you want to structure your content and render your output.

Kirby was released for the first time in 2009 and is actively developed by the Bastian Allgeier GmbH. Although the code of Kirby is available for download, a per website license is required to use it in production.


Note

For this guide you should be familiar with the basic concepts of

License

Kirby is licensed under the Kirby End User License Agreement which you can find on the official website. You need to purchase a license to use Kirby with your website.

Warning

Please be aware that one license is valid for a single website only. So you need to purchase additional licenses for multiple websites. This is no legal advice. Please review the license options and the Kirby End User License Agreement for yourself and contact the developer if you’re not sure.

Prerequisites

We’re using PHP in the stable version 8.1:

[isabell@stardust ~]$ uberspace tools version show php
Using 'PHP' version: '8.1'
[isabell@stardust ~]$

Your website domain needs to be set up:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Installation

To install Kirby we create a new Kirby Starterkit project using Composer (which is a dependency manager for PHP).

[isabell@stardust ~]$ cd /var/www/virtual/$USER/
[isabell@stardust ~]$ composer create-project getkirby/starterkit html
Creating a "getkirby/starterkit" project at "./html"
Installing getkirby/starterkit (3.5.5)
  - Downloading getkirby/starterkit (3.5.5)
  - Installing getkirby/starterkit (3.5.5): Extracting archive
Created project in /var/www/virtual/sbtest/html
Loading composer repositories with package information
Updating dependencies
[...]
[isabell@stardust ~]$

That’s all the magic. If you visit your previously set up domain you should see a working website with demo contents from the Starterkit.

Configuration

Visit your domain followed by /panel (e.g. isabell.uber.space/panel) to visit the admin panel and create your admin account. Please use a strong password for this.

When you’re ready to launch your website with Kirby you need to purchase a license. To register your license login to the admin panel, click register in the upper right corner and enter the necessary information.

Please make sure to deactivate the debug mode for your site when going live. Edit the site/config/config.php file and set the debug option to false to achieve that.

Best practices

If you want to avoid the demo code and contents of the Kirby Starterkit, there is a minimal setup available known as Plainkit. You can install it by changing the composer command to composer create-project getkirby/plainkit html. However, the use is only recommended for users who are already familiar with Kirby.

Tuning

For larger sites you can switch on Kirby’s cache. The cache stores the entire result of a rendered page. As long as the cache is valid, visitors will be served the cached version which is faster than to regenerate it.

The cache can be activated by adding the cache option to the site/config/config.php file:

return [
  'cache' => [
      'pages' => [
          'active' => true,
      ]
  ]
];

Note

Kirby is using a simple file cache by default. Please make sure that ~/html/site/cache is writable in order to make the cache work. If you’ve not changed the write permissions this should work out of the box.

If you need dynamic output on individual pages you can ignore them from being cached, please switch to the Kirby docs to find out how to achieve this.

Updates

Note

Check the update feed regularly to stay informed about the newest version.

Check Kirby’s releases for the latest versions. If a newer version is available, you should update your installation.

To update Kirby you just need to use the command composer update getkirby/cms in the directory of your installation.

[isabell@stardust ~]$ cd ~/html
[isabell@stardust html]$ composer update getkirby/cms
 Loading composer repositories with package information
 Updating dependencies (including require-dev)
 [...]
[isabell@stardust ~]$

If you’ve enabled the cache, you might need to empty the page cache directory to be sure nothing breaks. Delete all contents from ~/html/site/cache/pages in order to do so.

Warning

Kirby and especially Plugins are not updated automatically, so make sure to regularly check any update options.


Tested with Kirby 3.8.2, Uberspace 7.13, PHP 8.1

Written by: Daniel Kratz <https://danielkratz.com>