Instalando e Configurando o Craft CMS no ServBay

Visão Geral

O Craft CMS é um sistema de gerenciamento de conteúdo (CMS) avançado, muito apreciado por desenvolvedores graças à sua modelagem de conteúdo flexível, interface intuitiva e recursos amigáveis para quem desenvolve. Ele é perfeito para a criação de sites personalizados e complexos.

Utilizar o ServBay como ambiente local para o Craft CMS traz diversas vantagens, incluindo PHP pré-configurado, banco de dados (como MySQL ou PostgreSQL), servidores web (Caddy ou Nginx) e ferramentas integradas como Composer e terminal, o que simplifica demais o processo de instalação e configuração.

Este guia descreve em detalhes como instalar e configurar um projeto Craft CMS no ambiente ServBay.

Pré-requisitos

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

1. ServBay já instalado e rodando: Garanta que o ServBay está instalado em seu macOS e que a versão de PHP compatível com o Craft CMS (verifique os requisitos oficiais do Craft CMS) e o pacote de banco de dados necessários (geralmente MySQL ou PostgreSQL) estejam ativos. O ServBay suporta múltiplas versões do PHP e bancos de dados, permitindo alternar e configurar facilmente conforme a necessidade do Craft CMS.
2. Familiaridade básica com linha de comando: Você precisará usar o terminal para executar alguns comandos, como criar diretórios e rodar o Composer.
3. Conhecimento básico do Composer: O Craft CMS usa Composer para gerenciamento de dependências. O Composer já vem instalado no ServBay, mas é importante saber como executar o comando composer create-project.

Passos para Instalar o Craft CMS

Veja a seguir as etapas para instalar e configurar o Craft CMS no ambiente ServBay.

Passo 1: Crie o Diretório do Projeto

Primeiro, crie um novo diretório de projeto dentro do diretório raiz padrão de sites do ServBay, que é /Applications/ServBay/www. O ServBay já configura essa pasta como diretório raiz do servidor web, facilitando o acesso ao projeto.

Abra o terminal e execute:

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

Isso criará uma nova pasta chamada servbay-craft-app em /Applications/ServBay/www e entrará nesse diretório.

Passo 2: Crie o Projeto Craft CMS com Composer

Como o Composer já está incluso no ServBay, você pode utilizá-lo diretamente para criar seu projeto Craft CMS. O método recomendado oficialmente é a instalação via Composer.

No diretório servbay-craft-app, execute:

composer create-project craftcms/craft .

Esse comando irá baixar a versão mais recente do Craft CMS e todas as suas dependências para o diretório atual (.). Aguarde até que o Composer finalize o download e a instalação.

Passo 3: Crie o Banco de Dados e Usuário

O Craft CMS precisa de um banco de dados para armazenar conteúdos e configurações. Usaremos uma das ferramentas integradas do ServBay, como phpMyAdmin ou Adminer, para criar o banco e o usuário. Usaremos o phpMyAdmin como exemplo.

1. Acesse a ferramenta de administração de banco de dados (phpMyAdmin) do ServBay

   Abra o navegador e acesse o painel local do ServBay em https://servbay.host/. No painel, clique no link “phpMyAdmin” para abrir a ferramenta.

   Dica: O usuário padrão do phpMyAdmin no ServBay normalmente é root e a senha padrão é ServBay.dev. Por motivos de segurança, recomenda-se alterar a senha do root ou criar um novo usuário após a conexão.

2. Crie um usuário de banco de dados

   Embora seja possível conectar o Craft CMS como root, o ideal é criar um usuário exclusivo para cada aplicativo, para melhor segurança e gestão de permissões.

   1. Acesse a página de contas de usuários

      No painel principal do phpMyAdmin, clique em “Contas de usuários” no menu superior.

   2. Adicione uma nova conta de usuário

      Clique em “Adicionar conta de usuário” e preencha:

      • Nome de usuário: Defina um nome para o usuário que conectará ao banco, como craft_user.
      • Host: Escolha localhost para restringir acesso ao próprio servidor.
      • Senha: Defina uma senha segura. Não utilize exemplos simples como password123, especialmente em produção. No ambiente local, use uma senha fácil apenas para testes temporários e sempre considerando a questão de segurança.
      • Repetir senha: Repita a senha para confirmar.
      • Em “Banco de dados para o usuário”, escolha “Criar banco de dados com o mesmo nome e conceder todos os privilégios”. Assim, será criado automaticamente o banco craft_user já com permissões totais para o usuário.
      • Certifique-se de marcar “Conceder todos os privilégios”.
      • Clique em “Executar” ao final da página.

   Pronto! Agora você tem um banco chamado craft_user e um usuário com mesmo nome, já com as permissões configuradas.

Passo 4: Configure o Servidor Web (Criando o Site no ServBay)

Para que o servidor web do ServBay (Caddy ou Nginx) possa servir seu projeto Craft CMS, é necessário adicionar uma configuração de “site” no painel do ServBay.

1. Abra o aplicativo ServBay

   Inicie o ServBay.

2. Adicione um novo site

   Clique na aba “Sites” (em versões anteriores pode estar como “Hosts”) na barra de navegação à esquerda. Depois, clique em “+” ou em “Adicionar Site” para criar uma nova configuração.

   Preencha as seguintes informações:

   • Nome (Name): Dê um nome de fácil identificação, tipo My Craft Site.
   • Domínio (Domains): Informe o domínio local que deseja usar, como servbay-craft.local. O ServBay irá automaticamente configurar o DNS local para acesso via esse domínio.
   • Tipo do site (Type): Selecione PHP.
   • Versão do PHP (PHP Version): Escolha a versão compatível com seu projeto, conforme checado nos pré-requisitos. O ServBay suporta múltiplas versões simultâneas.
   • Raiz do site (Website Root): Muito importante! Os arquivos públicos do Craft CMS (como index.php) ficam na subpasta web do projeto. Por segurança, a raiz precisa apontar para esse diretório, não para a pasta do projeto inteiro. Preencha com: /Applications/ServBay/www/servbay-craft-app/web Confira se o caminho está correto e corresponde ao diretório criado no Passo 1.

3. Salve a configuração

   Após preencher tudo, clique em “Salvar”. O ServBay recarregará a configuração do servidor, tornando o novo site ativo. Você poderá ver o servbay-craft.local listado entre os sites do ServBay.

Passo 5: Execute o Instalador do Craft CMS

Agora basta acessar o domínio configurado pelo navegador para rodar o instalador do Craft CMS via interface web.

1. Acesse a página de instalação

   No navegador, visite https://servbay-craft.local/. O Craft CMS detectará que o sistema ainda não foi instalado e redirecionará automaticamente para a página de instalação, geralmente em https://servbay-craft.local/index.php?p=admin/install.

2. Forneça os dados do banco de dados

   Na etapa de configuração do banco de dados, preencha conforme criado anteriormente:

   • Servidor do Banco (Database Server): localhost
   • Nome do Banco (Database Name): craft_user (ou outro nome criado)
   • Usuário (Username): craft_user
   • Senha (Password): A senha definida para o usuário craft_user.

   Siga para a próxima etapa. O Craft CMS testará a conexão e, se estiver tudo correto, prosseguirá.

3. Crie o usuário administrador

   Siga as instruções para criar a conta admin do Craft CMS, incluindo nome, senha segura e email.

   Clique em continuar.

4. Configurações do site

   Informe o nome do seu site e outras informações básicas.

   Clique em “Finalizar Instalação (Finish Up)”. O Craft CMS concluirá a criação das tabelas e arquivos de configuração.

   Ao fim, você será redirecionado para a tela de login do painel de administração.

Passo 6: Configuração Inicial e Exploração

Após acessar o painel administrativo do Craft CMS, aproveite para realizar configurações iniciais e explorar o sistema:

1. Verifique o arquivo .env: O Craft CMS usa o arquivo .env para variáveis de ambiente, inclusive dados do banco. O instalador já cria esse arquivo no diretório raiz (servbay-craft-app/). Edite CRAFT_ENVIRONMENT para dev conforme necessário.
2. Instale plugins: No painel, em “Plugins”, você pode instalar, gerir e buscar plugins para expandir funcionalidades.
3. Crie a estrutura de conteúdo: Explore a aba “Configurações” para definir campos, seções, categorias, tags e outros elementos estruturais conforme o seu projeto.
4. Configure o envio de e-mails: Para testes locais de envio de email, configure o Craft CMS para usar a ferramenta Mailpit ou Mailhog integrada do ServBay. Use SMTP, com host localhost e porta correspondente ao serviço (veja o painel ServBay para detalhes).

Perguntas Frequentes (FAQ)

• Pergunta: Ocorreu erro de conexão com o banco durante a instalação. O que fazer?
  • Resposta: Verifique se o servidor (localhost), nome do banco, usuário e senha informados no instalador do Craft correspondem exatamente ao que foi criado no phpMyAdmin. Certifique-se de que o serviço de banco (MySQL ou PostgreSQL) está rodando no ServBay.
• Pergunta: Acesso a servbay-craft.local retorna 404 ou página em branco?
  • Resposta:
    • Confirme se o diretório raiz configurado no ServBay está corretamente apontando para /Applications/ServBay/www/servbay-craft-app/web. Este é o erro mais comum.
    • Verifique se o servidor web (Caddy ou Nginx) e o serviço PHP estão ativos no ServBay.
    • Confira na lista de sites do ServBay se o site servbay-craft.local está ativado.
• Pergunta: O Composer está lento ou falha ao instalar o Craft CMS?
  • Resposta: Pode ser problema de rede ou do espelho do Composer. Tente trocar para um mirror local, como o da Aliyun ou Packagist China.
• Pergunta: Após a instalação, o painel administrativo ou páginas do frontend aparecem sem estilos ou as imagens não carregam?
  • Resposta: Geralmente é problema de permissão de arquivos. Garanta que o usuário executando o ServBay tenha permissão de escrita em diretórios como storage e web/cpresources. O ServBay costuma cuidar disso automaticamente, mas em caso de problemas, ajuste as permissões manualmente.

Conclusão

Seguindo os passos acima, você deve conseguir instalar e configurar o Craft CMS com sucesso no ambiente local provido pelo ServBay. O ServBay simplifica o gerenciamento de versões do PHP, configuração de banco de dados e servidor web, permitindo que você foque no desenvolvimento do seu site ou aplicativo em Craft CMS. Agora, explore todos os recursos avançados do Craft para modelagem de conteúdo e comece a construir seu projeto!