Instalando e Configurando o Sculpin no Ambiente ServBay

Visão Geral

O Sculpin é um gerador de sites estáticos robusto e flexível baseado em PHP, ideal para construir blogs, sites de documentação ou qualquer projeto que exija a conversão de conteúdos dinâmicos (como templates Twig e arquivos Markdown) em páginas HTML estáticas de alta performance. Ele utiliza o Composer para gestão de dependências e é construído sobre componentes do Symfony, oferecendo aos desenvolvedores uma experiência confiável e familiar.

O ServBay é um ambiente de desenvolvimento web local projetado para macOS, integrando diversos pacotes populares, como PHP, Composer, bancos de dados (MySQL, PostgreSQL, MongoDB, Redis) e servidores web (Caddy, Nginx), além de fornecer uma interface gráfica amigável para gerenciamento. Utilizar o ServBay simplifica bastante o processo de configuração do ambiente Sculpin no macOS, especialmente no gerenciamento de versões do PHP, dependências e configuração dos servidores web.

Este guia apresenta em detalhes como instalar e configurar o Sculpin no ambiente ServBay e preparar um site de desenvolvimento local.

Cenários de Aplicação

• Construção de blogs estáticos de alta performance utilizando o stack PHP.
• Geração de sites de documentação estática para projetos open source ou produtos.
• Montagem rápida de landing pages estáticas ou websites corporativos que não necessitam de banco de dados backend.
• Escrita de conteúdos usando o motor de templates Twig e Markdown, aproveitando velocidade e segurança de sites estáticos.

Pré-requisitos

Antes de começar, certifique-se de que você atenda aos seguintes requisitos:

1. ServBay já instalado e em execução no sistema macOS. O ServBay fornece o ambiente PHP, o gerenciador de dependências Composer e servidores web (Caddy ou Nginx) necessários.
2. Conhecimentos básicos de utilização da linha de comando.
3. Entendimento básico de PHP, Composer e Markdown.

Passos para Instalar o Sculpin

Veja a seguir o passo a passo detalhado para instalar e configurar o Sculpin no ambiente ServBay:

Passo 1: Criar o Diretório do Projeto

Primeiro, crie um novo diretório de projeto dentro do diretório raiz do ServBay (/Applications/ServBay/www). Usaremos o nome de exemplo servbay-sculpin-app.

Abra o Terminal e execute os comandos abaixo:

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

Esse diretório irá armazenar os arquivos do seu projeto Sculpin.

Passo 2: Criar o Projeto Sculpin Usando o Composer

O ServBay já vem com o Composer pré-instalado, então não é necessário realizar instalação adicional. Você pode usar o comando composer diretamente no terminal.

Vamos utilizar a estrutura de blog oficial do Sculpin para facilitar o início. No diretório recém-criado servbay-sculpin-app, execute:

composer create-project sculpin/sculpin-blog-skeleton .

Esse comando irá baixar a estrutura de blog do Sculpin e todas as dependências necessárias, instalando-as no diretório atual (.).

Passo 3: Configurar o Site no ServBay

Para acessar o site Sculpin pelo servidor web do ServBay (Caddy ou Nginx), você precisa adicionar uma configuração de site dentro do ServBay.

1. Abra o aplicativo ServBay: Inicie a interface gráfica do ServBay.
2. Vá até a aba "Sites": No ServBay, clique na aba "Sites" no menu de navegação.
3. Adicione um novo site: Clique no botão "+" no canto inferior esquerdo para criar uma nova configuração de site.
4. Preencha as informações do site:
   • Nome (Name): Um nome fácil de reconhecer, como My Sculpin Site.
   • Domínio (Domain): O domínio que você deseja usar no acesso local, como servbay-sculpin.local. O ServBay irá configurar a resolução local e SSL automaticamente para domínios .local (usando ServBay User CA).
   • Tipo do site (Type): Selecione PHP, pois o Sculpin é uma aplicação PHP.
   • Versão do PHP (PHP Version): Selecione a versão do PHP que deseja usar. O ServBay suporta múltiplas versões; escolha uma compatível com o Sculpin (normalmente as versões mais recentes).
   • Diretório raiz (Document Root): Etapa crucial! Os arquivos estáticos gerados pelo Sculpin ficam por padrão em output_dev ou output_prod. Para desenvolvimento local, aponte o root para: /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. Salve a configuração: Após preencher, clique em "Salvar". O ServBay aplicará automaticamente as novas configurações ao servidor web (Caddy ou Nginx). Geralmente não é necessário reiniciar os serviços manualmente.

Passo 4: Gerar o Site Sculpin

Com o site devidamente configurado no ServBay, você precisa que o Sculpin gere os arquivos estáticos do website.

No terminal, estando no diretório /Applications/ServBay/www/servbay-sculpin-app, execute o comando para instalar as dependências do projeto (caso já tenha feito no Passo 2, não é estritamente necessário, mas garante que tudo está instalado):

composer install

Em seguida, execute o comando para construir o site com o Sculpin:

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin: Caminho do executável Sculpin instalado via Composer.
• generate: Comando do Sculpin para gerar o site estático, lendo o conteúdo e templates da pasta source e gerando arquivos no diretório de saída (output_dev por padrão).
• --watch: Indica para o Sculpin monitorar alterações na pasta source. Se houver modificações, o site é recompilado automaticamente — recurso essencial em desenvolvimento.

Quando o comando exibir "Sculpin has generated your site!" ou algo similar, os arquivos estáticos já estarão no diretório output_dev.

Passo 5: Acessar o Site de Desenvolvimento Local

Agora você pode acessar seu site Sculpin usando o domínio configurado no ServBay.

Abra o navegador de sua preferência e acesse:

https://servbay-sculpin.local

Como o root do site aponta para output_dev e o comando sculpin generate --watch está em execução monitorando mudanças, você pode visualizar em tempo real as alterações de conteúdo e templates por https://servbay-sculpin.local. O SSL gerado automaticamente pelo ServBay garante acesso seguro via HTTPS ao site local.

Desenvolvendo com o Sculpin

Com o Sculpin instalado e configurado no ServBay, você já pode iniciar a construção do seu site estático. Veja algumas operações básicas de desenvolvimento:

Estrutura Básica de um Projeto Sculpin

Compreender a estrutura do Sculpin auxilia no desenvolvimento:

servbay-sculpin-app/
├── app/                # Configurações e cache da aplicação
├── output_dev/         # Diretório de saída dos arquivos estáticos de desenvolvimento (root do site no ServBay)
├── output_prod/        # Diretório de saída para produção
├── source/             # Arquivos-fonte do site (conteúdo Markdown, templates Twig, assets etc.)
│   ├── _layouts/       # Arquivos de layout Twig
│   ├── _posts/         # Postagens do blog em Markdown
│   ├── assets/         # Recursos estáticos (CSS, JS, imagens...)
│   └── index.md        # Página inicial em Markdown
├── vendor/             # Dependências instaladas via Composer
├── sculpin.yml         # Arquivo principal de configuração do Sculpin
├── composer.json       # Configurações de dependências do Composer
└── ...outros arquivos

A maior parte do seu trabalho será dentro do diretório source.

Criando uma Postagem no Blog

Para criar uma nova postagem no seu blog Sculpin, basta criar um novo arquivo Markdown dentro do diretório source/_posts. O nome do arquivo deve seguir o padrão YYYY-MM-DD-slug.md.

Por exemplo, crie o arquivo 2024-06-06-my-first-post.md:

---
title: "Minha Primeira Postagem"
date: 2024-06-06
tags: [Tutorial, Sculpin, ServBay]
---

# Minha Primeira Postagem

Este é o conteúdo da minha primeira postagem do blog Sculpin. Aqui compartilho algumas experiências sobre o uso do ServBay e Sculpin.

Você pode escrever conteúdos aqui usando a sintaxe Markdown.

## Subtítulo

Lista:
- Item 1
- Item 2

Após salvar o arquivo, como o comando sculpin generate --watch está rodando, o Sculpin detectará a mudança e irá regenerar o site automaticamente. Basta atualizar a página em https://servbay-sculpin.local para ver sua nova postagem.

Criar uma Página Nova

Para adicionar uma página independente (como “Sobre Nós”), basta criar um arquivo Markdown diretamente em source, por exemplo, about.md:

---
title: "Sobre Nós"
layout: page.html.twig # Especifica qual layout usar
---

# Guia ServBay Sculpin

Esta página é um guia sobre como construir sites estáticos usando ServBay e Sculpin.

Depois de salvar, o Sculpin irá gerar o arquivo output_dev/about/index.html (caso a configuração permita URLs amigáveis). Assim, você acessa a página em https://servbay-sculpin.local/about/.

Personalizando Estilos e Scripts

Recursos estáticos como arquivos CSS e JavaScript geralmente ficam em source/assets. Você pode editar diretamente esses arquivos.

Por exemplo, para editar o estilo do site, altere o arquivo source/assets/css/style.css.

Esses arquivos são copiados para o diretório de saída durante a geração do site. Ao fazer alterações nesses recursos, o Sculpin com o flag --watch detectará e recompilará o site.

Gerar a Versão para Produção

Quando o site estiver pronto para ir ao ar, gere a versão preparada para produção. Geralmente, o build de produção realiza otimizações como compressão de recursos.

Use o seguinte comando para compilar para produção:

vendor/bin/sculpin generate --env=prod

Os arquivos serão gerados em output_prod. Você pode fazer upload de todo o conteúdo deste diretório para qualquer serviço de hospedagem estática (como GitHub Pages, Netlify, Vercel, ou seu próprio servidor web).

Caso queira visualizar a build de produção pelo ServBay, basta alterar o "Document Root" da configuração do site para /Applications/ServBay/www/servbay-sculpin-app/output_prod, salvar e acessar o domínio.

Observações Importantes

• Certifique-se de que o ServBay está rodando e o site configurado está ativado.
• Verifique se o comando sculpin generate --watch está em execução no terminal para que as mudanças sejam aplicadas automaticamente.
• Confira se o "Document Root" no ServBay está apontando corretamente para a saída do Sculpin (em desenvolvimento, geralmente output_dev).
• O ServBay gera certificados SSL automaticamente para domínios .local, mas talvez seja necessário confiar na CA do ServBay no seu sistema operacional. Consulte a documentação do ServBay para orientações.

Perguntas Frequentes (FAQ)

P: Fiz alterações nos arquivos, mas o site não atualiza?

R: Certifique-se de que o comando vendor/bin/sculpin generate --watch está rodando no diretório do projeto sem erros. Verifique o terminal para mensagens de erro. Limpe o cache do navegador ou tente acessar em modo privativo/incógnito.

P: Ao acessar https://servbay-sculpin.local aparece um erro SSL?

R: Isso ocorre porque o ServBay gera certificados autoassinados para domínios .local. É necessário que o sistema operacional confie na autoridade certificadora do ServBay User CA. Siga as instruções de instalação e confiança do certificado na documentação do ServBay.

P: Como altero a versão do PHP?

R: No ServBay, utilize a aba "Pacotes" para instalar e gerenciar diferentes versões do PHP. Depois, na aba "Sites", edite a configuração do seu site Sculpin e selecione a versão desejada.

P: Quais engines de template e linguagens de marcação o Sculpin suporta?

R: O Sculpin utiliza por padrão o Twig como engine de templates e suporta amplamente Markdown para redação de conteúdos.

Conclusão

O ambiente integrado do ServBay simplifica drasticamente o processo de instalação e configuração do Sculpin em macOS. Com PHP e Composer pré-instalados, servidores web facilmente configuráveis e SSL automático, o ServBay oferece uma base sólida para desenvolvimento local com o Sculpin. Seguindo este guia, você monta rapidamente seu ambiente de desenvolvimento, podendo criar, testar e visualizar sites estáticos de forma eficiente. Aproveite toda a potência do Sculpin combinada com a praticidade do ServBay e foque na criação de conteúdos de qualidade, sem se preocupar com ajustes complexos do ambiente local.