Instalación y configuración de Kirby CMS en el entorno ServBay

Kirby es un sistema de gestión de contenidos (CMS) flexible y potente basado en archivos, ideal para crear todo tipo de sitios web. A diferencia de los CMS tradicionales que utilizan bases de datos, Kirby almacena el contenido en el sistema de archivos, lo que lo hace muy ligero, fácil de versionar y sencillo de desplegar.

Este tutorial te guiará para instalar y configurar el Starterkit de Kirby 4.2 utilizando Composer dentro de ServBay, un entorno local de desarrollo web personalizado para desarrolladores. ServBay viene con PHP preconfigurado, servidores web (como Caddy o Nginx) y Composer integrados, convirtiéndose en la plataforma ideal para el desarrollo local con Kirby.

Requisitos previos

Antes de comenzar, asegúrate de haber:

1. Instalado y ejecutado ServBay en macOS.
2. Habilitado la versión de PHP necesaria en ServBay (en este ejemplo se utiliza PHP 8.2).
3. ServBay ya incluye Composer, por lo que no hace falta instalarlo por separado.

Pasos para instalar Kirby

A continuación, se describen los pasos detallados para instalar y configurar Kirby en el entorno de ServBay:

Paso 1: Crear el directorio del proyecto

Primero, abre la aplicación Terminal. Navega al directorio raíz predeterminado de los sitios web de ServBay en /Applications/ServBay/www y crea un nuevo directorio para el proyecto. Usaremos servbay-kirby-app como nombre de ejemplo.

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

Paso 2: Crear el proyecto de Kirby con Composer

ServBay incluye Composer integrado, por lo que puedes usarlo directamente desde la terminal. Dentro del directorio del proyecto servbay-kirby-app, ejecuta el siguiente comando para descargar e instalar el Starterkit de Kirby:

composer create-project getkirby/starterkit .

Este comando descargará los archivos principales de Kirby, sus dependencias y un Starterkit con contenido y plantillas básicas en el directorio actual (.).

Paso 3: Configurar el servidor web (añadir el sitio en ServBay)

Para que el servidor web de ServBay (por ejemplo, Caddy o Nginx) pueda servir tu proyecto Kirby, necesitas añadir una nueva configuración de sitio web en la app de ServBay.

1. Abre la app de ServBay: Lanza ServBay.
2. Ingresa a la administración de sitios: Haz clic en la pestaña “Sitios” en la barra lateral izquierda de ServBay.
3. Añade un nuevo sitio: Haz clic en el botón “+” en la parte inferior o selecciona la opción correspondiente para añadir un sitio.
4. Completa la información del sitio: Introduce los siguientes datos en la ventana de configuración:
   • Nombre: Ponle un nombre identificable, por ejemplo My Kirby Site.
   • Dominio: Define un dominio local de desarrollo. Se recomienda usar el sufijo .local o .servbay.demo, por ejemplo servbay-kirby.local. ServBay configurará automáticamente la resolución DNS local.
   • Tipo de Sitio: Selecciona PHP, ya que Kirby es una aplicación PHP.
   • Versión de PHP: Elige la versión que prefieras, por ejemplo 8.2. Asegúrate de que cumpla los requisitos mínimos de Kirby.
   • Directorio raíz del sitio: Indica el directorio donde se encuentra el archivo index.php de Kirby. Normalmente, para Starterkit, es el propio directorio raíz del proyecto. Introduce o selecciona la ruta que creaste en el paso 1: /Applications/ServBay/www/servbay-kirby-app.
5. Guarda la configuración: Verifica que todo esté correcto y haz clic en guardar. ServBay aplicará automáticamente la nueva configuración y puede que necesite reiniciar el servidor web correspondiente.

Paso 4: Configuración inicial de Kirby

La configuración principal de Kirby se realiza a través del archivo site/config/config.php. Con Starterkit, la configuración básica ya está lista, así que puedes empezar a usarlo directamente. Si lo deseas, puedes añadir ajustes personalizados en este archivo, como por ejemplo:

• Activar el modo debug (c::set('debug', true);)
• Configurar el idioma del panel
• Definir rutas personalizadas, entre otros

En el directorio raíz del proyecto, el directorio content ya ha sido creado automáticamente por el Starterkit de Kirby y servirá para almacenar todo el contenido de las páginas.

Paso 5: Ejecutar y acceder al sitio Kirby

Tras configurar ServBay, tu sitio Kirby estará accesible a través del dominio que elegiste.

1. Asegúrate de que ServBay está ejecutándose: Verifica que la app y los servicios de servidor web (Caddy o Nginx) y PHP están activos.
2. Accede al sitio: Abre tu navegador web e ingresa el dominio que configuraste en el paso 3, por ejemplo https://servbay-kirby.local.

Deberías ver la página de bienvenida predeterminada del Starterkit de Kirby. ServBay tiene HTTPS activado por defecto, así que es recomendable usar https://.

Paso 6: Instalar y usar el Panel de Kirby (opcional)

Kirby cuenta con un potente panel de administración que facilita la gestión de contenido, usuarios y configuraciones.

1. Accede a la página de instalación del panel: En tu navegador, visita tu dominio seguido de /panel, por ejemplo https://servbay-kirby.local/panel.
2. Crea una cuenta de administrador: Si es la primera vez que accedes a /panel, serás dirigido a la página de instalación del panel. Completa los datos requeridos (nombre de usuario, contraseña, correo electrónico) para crear tu cuenta de admin.
3. Inicia sesión en el panel: Tras crear la cuenta, ya podrás acceder al panel y gestionar el contenido de tu web usando una interfaz gráfica.

Crear tu web con Kirby

Ahora que tienes Kirby instalado y configurado en ServBay, puedes aprovechar su estructura basada en archivos para construir tu sitio web. Aquí tienes algunos conceptos y acciones esenciales en el desarrollo con Kirby:

Estructura de contenidos (Content)

El contenido en Kirby se almacena en el directorio content. Cada página corresponde a una carpeta dentro de este directorio. El contenido de la página suele guardarse en archivos de texto (por ejemplo, page.txt), escritos en un formato similar a Markdown.

Ejemplo: Crear la página “Sobre Nosotros”

Desde la terminal:

cd /Applications/ServBay/www/servbay-kirby-app
mkdir content/about
echo "Title: Sobre Nosotros\n----\nEsta es la página sobre nosotros." > content/about/about.txt

Después, puedes acceder a https://servbay-kirby.local/about (si tu plantilla lo soporta).

Plantillas (Templates)

Los archivos de plantilla se encuentran en site/templates y definen cómo se renderiza cada página. Por convención, el nombre del archivo suele coincidir con el nombre de la carpeta de contenido o del blueprint (por ejemplo, about.php para la carpeta content/about o páginas con blueprint about).

Ejemplo: Crear la plantilla about.php

En el archivo site/templates/about.php:

<?php snippet('header') ?>

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

<?php snippet('footer') ?>

Aquí se utiliza la función snippet() para incluir partes reutilizables como el encabezado y pie de página.

Blueprints

Los blueprints están en site/blueprints y definen la estructura, los campos y las opciones de cada página en el panel. Se escriben en formato YAML.

Ejemplo: Crear el blueprint about.yml

En el archivo site/blueprints/pages/about.yml:

title: Página Sobre

columns:
  - width: 2/3
    fields:
      text:
        label: Contenido de texto
        type: textarea
        size: large
        buttons:
          - bold
          - italic
          - link
          - email

  - width: 1/3
    fields:
      # Campos de la barra lateral, por ejemplo subida de imágenes
      cover_image:
        label: Imagen de portada
        type: files
        max: 1
        uploads:
          template: image

Después de definir el blueprint, verás estos campos al crear una nueva página "Sobre" en el panel.

Snippets

Los snippets son archivos PHP reutilizables, generalmente para el encabezado, pie, navegación, etc., y se encuentran en site/snippets.

Controladores y modelos

Para lógica más compleja, puedes usar controladores (site/controllers) para procesar datos de páginas y modelos (site/models) para definir clases de página personalizadas.

Recursos estáticos (Assets)

Los recursos estáticos como CSS, JavaScript e imágenes suelen guardarse en el directorio assets en la raíz del proyecto. En las plantillas puedes obtener la URL de estos recursos usando la función auxiliar url('assets/...').

Ejemplo: Referenciar CSS y JS

En site/templates/default.php o site/snippets/header.php:

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

Resumen

Siguiendo estos pasos, has instalado y configurado exitosamente Kirby CMS en el entorno local de desarrollo de ServBay. El entorno integrado de ServBay simplifica enormemente el despliegue y la gestión de aplicaciones PHP, permitiéndote centrarte en aprovechar toda la potencia de Kirby y la flexibilidad de su sistema basado en archivos para construir y desarrollar tu sitio web. Ahora puedes adentrarte aún más en los conceptos de plantillas, blueprints, snippets, y más de Kirby para crear estructuras y funcionalidades más avanzadas en tus proyectos.