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á:
- Instalou e está rodando o ServBay no macOS.
- Tem a versão necessária do PHP ativada no ServBay (neste exemplo, usaremos PHP 8.2).
- 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
2
3
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.
- Abra o aplicativo ServBay: Inicie o ServBay normalmente.
- Vá até a gestão de sites: Clique na aba “Sites” na barra de navegação à esquerda da janela do ServBay.
- Adicione um novo site: Clique no botão “+” no rodapé ou utilize a opção de adicionar site.
- 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
.
- Nome: Escolha um nome fácil de identificar, por exemplo
- 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.
- Garanta que o ServBay está rodando: Verifique se o aplicativo, o servidor web (Caddy ou Nginx) e o pacote do PHP estão ativos.
- 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.
- Acesse a página de instalação do painel: No navegador, adicione
/panel
ao seu domínio, comohttps://servbay-kirby.local/panel
. - 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. - 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
2
3
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') ?>
2
3
4
5
6
7
8
9
10
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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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>
2
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.