Instalando e Configurando Kirby CMS no Ambiente ServBay

Kirby é um sistema de gerenciamento de conteúdo (CMS) flexível e poderoso baseado em arquivos, ideal para construir diversos tipos de sites. Diferente de CMS tradicionais que utilizam banco de dados, o Kirby armazena o conteúdo diretamente no sistema de arquivos, tornando-o extremamente leve, fácil de versionar e simples de implantar.

Este tutorial irá guiá-lo pelo processo de instalação e configuração do Kirby 4.2 Starterkit no ServBay – um ambiente de desenvolvimento web local projetado especialmente para desenvolvedores. O ServBay oferece PHP pré-configurado, servidores web como Caddy ou Nginx, além do Composer já instalado, sendo uma plataforma ideal para o desenvolvimento local com Kirby.

Pré-requisitos

Antes de começar, certifique-se de que você já:

1. Instalou e está rodando o ServBay no macOS.
2. Tem a versão necessária do PHP ativada no ServBay (neste exemplo, usaremos PHP 8.2).
3. O Composer já vem incluso com o ServBay, não sendo necessário nenhuma instalação adicional.

Passos para Instalar o Kirby

Veja em detalhes como instalar e configurar o Kirby no ambiente ServBay:

Passo 1: Crie o Diretório do Projeto

Primeiro, abra o aplicativo Terminal. Navegue até o diretório raiz padrão dos sites do ServBay /Applications/ServBay/www, e então crie um novo diretório para o projeto. Vamos usar servbay-kirby-app como exemplo de nome do projeto.

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

Passo 2: Crie o Projeto Kirby com Composer

O ServBay já tem o Composer integrado, assim, você pode usá-lo diretamente no Terminal. Estando no diretório servbay-kirby-app, execute o comando abaixo para baixar e criar o Starterkit do Kirby:

composer create-project getkirby/starterkit .

Este comando fará o download dos arquivos principais do Kirby, suas dependências, além do Starterkit (com conteúdo e templates básicos) para o diretório atual (.).

Passo 3: Configurando o Servidor Web (Adicionando um site no ServBay)

Para que o servidor web do ServBay (Caddy ou Nginx, por exemplo) possa atender seu projeto Kirby, será necessário adicionar uma nova configuração de site pelo aplicativo.

1. Abra o aplicativo ServBay: Inicie o ServBay normalmente.
2. Vá até a gestão de sites: Clique na aba “Sites” na barra de navegação à esquerda da janela do ServBay.
3. Adicione um novo site: Clique no botão “+” no rodapé ou utilize a opção de adicionar site.
4. Preencha os detalhes do site: Na janela de configuração que será exibida, preencha:
   • Nome: Escolha um nome fácil de identificar, por exemplo My Kirby Site.
   • Domínio: Defina um domínio local, recomendando usar os sufixos .local ou .servbay.demo – exemplo: servbay-kirby.local. O ServBay faz a configuração automática do DNS local.
   • Tipo do site: Selecione PHP, pois o Kirby é uma aplicação PHP.
   • Versão do PHP: Escolha a versão desejada, como 8.2. Certifique-se de que é compatível com os requisitos mínimos do Kirby.
   • Diretório raiz do site: Aponte para o diretório onde está o index.php do seu projeto Kirby. No Starterkit, normalmente é o próprio diretório do projeto criado no passo 1: /Applications/ServBay/www/servbay-kirby-app.
5. Salve as configurações: Confirme todos os dados e clique em salvar. O ServBay aplicará a nova configuração automaticamente, e pode ser necessário reiniciar o servidor web correspondente.

Passo 4: Primeira Configuração do Kirby

A configuração central do Kirby é feita pelo arquivo site/config/config.php. No Starterkit, a configuração básica já é suficiente para rodar o site, mas você pode adicionar ajustes como:

• Ativar o modo debug (c::set('debug', true);)
• Definir idioma padrão do painel
• Configurar rotas customizadas, entre outros

No diretório raiz do seu projeto, o diretório content já é criado automaticamente pelo Starterkit do Kirby, servindo para armazenar todo o conteúdo das páginas.

Passo 5: Rodando e Acessando o Site Kirby

Após configurar tudo no ServBay, seu site Kirby já pode ser acessado pelo domínio que você definiu.

1. Garanta que o ServBay está rodando: Verifique se o aplicativo, o servidor web (Caddy ou Nginx) e o pacote do PHP estão ativos.
2. Acesse o site: No navegador, digite o domínio configurado no passo 3, por exemplo https://servbay-kirby.local.

Você verá a página de boas-vindas padrão do Kirby Starterkit. O ServBay já vem com HTTPS habilitado, portanto, o acesso recomendado é via https://.

Passo 6: Instalando e Utilizando o Painel do Kirby (Opcional)

O Kirby conta com um painel administrativo poderoso para gerenciamento de conteúdo, usuários e configurações do site.

1. Acesse a página de instalação do painel: No navegador, adicione /panel ao seu domínio, como https://servbay-kirby.local/panel.
2. Crie uma conta de administrador: No primeiro acesso ao /panel, você será redirecionado para a página de instalação do painel. Complete as informações necessárias (nome de usuário, senha, e-mail) para criar sua conta administrativa.
3. Faça login no painel: Após criar a conta, já poderá acessar o painel do Kirby e gerenciar o conteúdo do site pela interface visual.

Estruturando seu Site com Kirby

Com o Kirby instalado e configurado no ServBay, você já pode aproveitar seus recursos baseados em arquivos para desenvolver o seu site. Veja alguns conceitos e operações fundamentais:

Estrutura de Conteúdo

O conteúdo do Kirby é armazenado dentro do diretório content. Cada página equivale a uma pasta neste diretório, cujos textos são armazenados em arquivos de texto (por exemplo, page.txt), geralmente utilizando sintaxe parecida com Markdown.

Exemplo: Criando uma página “Sobre Nós”

No terminal:

cd /Applications/ServBay/www/servbay-kirby-app
mkdir content/about
echo "Title: Sobre Nós\n----\nEste é o conteúdo da página Sobre Nós." > content/about/about.txt

Depois, acesse https://servbay-kirby.local/about (caso seu template suporte).

Templates

Os arquivos de template ficam em site/templates e determinam como cada página é renderizada. O nome costuma corresponder ao nome da pasta de conteúdo ou ao blueprint (por exemplo, about.php para content/about ou páginas com blueprint about).

Exemplo: Criando o template about.php

No arquivo site/templates/about.php:

<?php snippet('header') ?>

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

<?php snippet('footer') ?>

Aqui, usamos a função snippet() para incluir partes reutilizáveis, como o cabeçalho e o rodapé.

Blueprints

Os blueprints estão na pasta site/blueprints e definem, com arquivos YAML, a estrutura, campos e opções das páginas exibidas no painel.

Exemplo: Criando o blueprint about.yml

No arquivo site/blueprints/pages/about.yml:

title: Página Sobre

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

  - width: 1/3
    fields:
      # Campos da barra lateral, como upload de imagem etc.
      cover_image:
        label: Imagem de capa
        type: files
        max: 1
        uploads:
          template: image

Após definir o blueprint, estes campos ficarão disponíveis ao criar uma nova página “Sobre” pelo painel.

Snippets

Snippets são arquivos PHP reutilizáveis, normalmente utilizados para o cabeçalho, rodapé, navegação, e ficam em site/snippets.

Controllers e Models

Para lógica mais avançada, utilize controllers (site/controllers) para manipular dados das páginas e models (site/models) para criar classes de páginas personalizadas.

Recursos Estáticos (Assets)

Recursos como CSS, JavaScript e imagens devem ser armazenados na pasta assets na raiz do projeto. Nos templates, use o helper url('assets/...') para acessar o caminho desses arquivos.

Exemplo: Incluindo CSS e JS

Em site/templates/default.php ou site/snippets/header.php:

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

Resumo

Seguindo estes passos, você instalou e configurou com sucesso o Kirby CMS em seu ambiente de desenvolvimento local com ServBay. A integração do ServBay simplifica o gerenciamento e deploy de aplicações PHP, permitindo que você foque nos recursos do Kirby e na flexibilidade do seu sistema de arquivos para criar seu site. Agora, aprofunde-se nos conceitos de templates, blueprints, snippets e outros recursos do Kirby para desenvolver estruturas e funcionalidades ainda mais avançadas para seu projeto.