Installing and Configuring Kirby CMS in the ServBay Environment

Kirby is a flexible and powerful file-based Content Management System (CMS) that’s ideal for building all kinds of websites. Unlike traditional database-driven CMSs, Kirby stores content on the file system, making it lightweight, easy to version control, and simple to deploy.

This tutorial will guide you through installing and configuring the Kirby 4.2 Starterkit using Composer in ServBay—a tailor-made local web development environment for developers. ServBay comes pre-configured with PHP, web servers (like Caddy or Nginx), and Composer, making it an ideal platform for local Kirby development.

Prerequisites

Before you begin, please make sure you have:

1. Installed and launched ServBay on macOS.
2. Enabled the required PHP version in ServBay (this guide uses PHP 8.2).
3. Composer is already included with ServBay, so no additional installation is necessary.

Steps to Install Kirby

Here are the detailed steps to install and configure Kirby in the ServBay environment:

Step 1: Create the Project Directory

First, open your terminal application. Navigate to ServBay’s default web root directory at /Applications/ServBay/www, and create a new project directory. We'll use servbay-kirby-app as the sample project name.

cd /Applications/ServBay/www
mkdir servbay-kirby-app
cd servbay-kirby-app

Step 2: Create a Kirby Project with Composer

Since Composer is integrated with ServBay, you can use it directly in the terminal. From within your project folder servbay-kirby-app, run the following Composer command to download and set up the Kirby Starterkit project:

composer create-project getkirby/starterkit .

This command will download Kirby’s core files, dependencies, and a Starterkit with basic content and templates into the current directory (.).

Step 3: Configure the Web Server (Add Site in ServBay)

To allow ServBay’s web server (such as Caddy or Nginx) to serve your Kirby project, you need to add a new site configuration in the ServBay app.

1. Open the ServBay App: Launch the ServBay application.
2. Go to Site Management: Click the "Sites" tab in the left sidebar of the ServBay window.
3. Add a New Site: Click the "+" button at the bottom of the interface or a similar option to add a new site.
4. Fill Out Site Information: In the popup configuration window, enter the following information:
   • Name: Give your site an easily recognizable name, such as My Kirby Site.
   • Domain: Set a local development domain. It's recommended to use a .local or .servbay.demo suffix, e.g., servbay-kirby.local. ServBay will auto-configure local DNS resolution for you.
   • Site Type: Select PHP, since Kirby is a PHP application.
   • PHP Version: Choose the PHP version you wish to use, such as 8.2. Make sure it meets Kirby’s minimum requirements.
   • Site Root Directory: Set the directory where your Kirby project’s index.php file is located. For the Kirby Starterkit, this is usually the project root. Enter or select the directory path you created in Step 1: /Applications/ServBay/www/servbay-kirby-app.
5. Save the Configuration: After confirming the details are correct, click the save button. ServBay will automatically apply the new configuration and may need to restart the relevant web services.

Step 4: Initial Kirby Configuration

Kirby’s core settings are managed via the site/config/config.php file. For the Starterkit, the basics are already set up and you can run it immediately. You can add custom settings in this file, such as:

• Enabling debug mode (c::set('debug', true);)
• Configuring panel language
• Defining custom routes, etc.

In your project root directory, the content folder will have already been created by the Kirby Starterkit to store all page content.

Step 5: Run and Access Your Kirby Site

Once ServBay is configured, you can access your Kirby website using the domain you set up.

1. Make Sure ServBay is Running: Ensure that the ServBay app is running, and that the relevant web server (Caddy or Nginx) and PHP services are started.
2. Visit the Site: Open your web browser and enter the domain you configured in Step 3, for example, https://servbay-kirby.local.

You should see Kirby Starterkit’s default welcome page. ServBay enables HTTPS by default, so it's recommended to access the site using https://.

Step 6: Install and Use the Kirby Panel (Optional)

Kirby offers a powerful admin panel for managing site content, users, and settings.

1. Access the Panel Installation Page: In your browser, go to your site domain with the /panel path, for example, https://servbay-kirby.local/panel.
2. Create an Admin Account: If this is your first visit to /panel, you’ll be guided through setting up the panel. Follow the prompts to provide your username, password, and email address to create your first admin account.
3. Log in to the Panel: After account creation, you can log in to the Kirby panel and start managing your site content via a graphical interface.

Building a Website with Kirby

Now that you’ve successfully installed and configured Kirby in the ServBay environment, you can start building your site leveraging its file-driven features. Here are some basic Kirby development concepts and operations:

Content Structure

Kirby stores its content in the content directory. Each page corresponds to a folder under content. The content for each page is usually kept in a text file (e.g., page.txt) inside the folder, often using Markdown-like syntax.

Example: Creating an "About Us" Page

In the terminal:

cd /Applications/ServBay/www/servbay-kirby-app
mkdir content/about
echo "Title: About Us\n----\nThis is the content of our About Us page." > content/about/about.txt

Visit https://servbay-kirby.local/about (if your template supports it).

Templates

Template files are stored in the site/templates directory and determine how pages are rendered. Their filenames usually correspond to the content folder name or the blueprint name (e.g., about.php for the content/about folder or pages using the about blueprint).

Example: Create an about.php Template

In site/templates/about.php:

<?php snippet('header') ?>

<main>
  <h1><?= $page->title() ?></h1>
  <div class="text">
    <?= $page->text()->kt() // Render using KirbyText ?>
  </div>
</main>

<?php snippet('footer') ?>

Here, the snippet() function is used to include reusable parts like the header and footer.

Blueprints

Blueprint files are in the site/blueprints directory and define the structure, fields, and options for pages within the panel. They are written in YAML.

Example: Creating an about.yml Blueprint

In site/blueprints/pages/about.yml:

title: About Page

columns:
  - width: 2/3
    fields:
      text:
        label: Content Text
        type: textarea
        size: large
        buttons:
          - bold
          - italic
          - link
          - email

  - width: 1/3
    fields:
      # Sidebar fields, such as image upload
      cover_image:
        label: Cover Image
        type: files
        max: 1
        uploads:
          template: image

Once defined, these fields will appear in the panel when you create a new "About" page.

Snippets

Snippets are reusable PHP files, typically stored in site/snippets, and are used for common page parts like headers, footers, and navigation.

Controllers and Models

For more complex logic, you can use controllers (site/controllers) to handle page data and models (site/models) to define custom page classes.

Static Assets

CSS, JavaScript, images, and other static assets are usually kept in an assets folder at the project root. You can use the url('assets/...') helper function in templates to get their URLs.

Example: Including CSS and JS

In site/templates/default.php or site/snippets/header.php:

<link rel="stylesheet" href="<?= url('assets/css/style.css') ?>">
<script src="<?= url('assets/js/script.js') ?>"></script>

Summary

By following the steps above, you’ve successfully installed and configured Kirby CMS in the ServBay local development environment. ServBay’s integrated environment dramatically simplifies the deployment and management of PHP applications, allowing you to focus on utilizing Kirby’s powerful features and flexible file-based architecture for your web projects. You can now delve deeper into Kirby’s templates, blueprints, snippets, and more to build complex website structures and features.