Instalando e Configurando o OctoberCMS no Ambiente ServBay

Visão Geral

OctoberCMS é um sistema de gerenciamento de conteúdo (CMS) open source construído sobre o poderoso framework Laravel, reconhecido por sua simplicidade, flexibilidade e foco nos desenvolvedores. Este documento tem como objetivo guiá-lo no processo de instalação e configuração do OctoberCMS no ServBay — uma solução local tudo-em-um para desenvolvimento web no macOS — para que você possa iniciar rapidamente seus projetos com OctoberCMS.

O que é o OctoberCMS?

OctoberCMS oferece uma interface administrativa intuitiva e poderosas capacidades de desenvolvimento frontend, permitindo que desenvolvedores utilizem conceitos conhecidos do Laravel (como Eloquent ORM, engine de templates Blade, e outros) para criar desde blogs simples até aplicações corporativas complexas.

Pré-requisitos

Antes de instalar o OctoberCMS, certifique-se de atender às seguintes condições:

1. O ServBay já está instalado e em execução no seu macOS.
2. Os pacotes PHP (recomendado 7.4 ou superior) e MySQL/MariaDB estão habilitados e rodando no ServBay.
3. O pacote Composer está ativado no ServBay.
4. Você tem conhecimentos básicos de uso do terminal/linha de comando.

Passos para Instalar o OctoberCMS

Veja abaixo o passo a passo detalhado para instalar e configurar o OctoberCMS no ServBay:

Passo 1: Criar o Diretório do Projeto

Primeiro, navegue até o diretório raiz sugerido pelo ServBay para sites, /Applications/ServBay/www, e crie um novo diretório para seu projeto OctoberCMS.

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

Passo 2: Instalar o OctoberCMS com Composer

O ServBay já inclui e configura o Composer automaticamente. Verifique se o pacote Composer está habilitado no painel do ServBay. Agora, dentro do diretório recém-criado, execute o comando Composer para baixar e instalar os arquivos principais do OctoberCMS:

composer create-project october/october .

Esse comando irá baixar a versão mais recente do OctoberCMS do repositório oficial diretamente para o diretório atual (.).

Passo 3: Criar Banco de Dados e Usuário

OctoberCMS exige um banco de dados para armazenar conteúdos, usuários, configurações, entre outros. Vamos utilizar a ferramenta phpMyAdmin fornecida pelo ServBay para criar o banco e o usuário correspondente.

1. Acessar o phpMyAdmin do ServBay

   Abra o navegador e vá até o painel de desenvolvimento local do ServBay: https://servbay.host/. Clique ou navegue até o link do phpMyAdmin, geralmente https://servbay.host/phpmyadmin/, para acessar o gerenciador de banco de dados.

2. Criar Usuário do Banco de Dados

   Para segurança e isolamento, é recomendado criar um usuário e banco de dados específicos para cada aplicação.

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

      Na página inicial do phpMyAdmin, clique no menu superior em "Contas de Usuário".

   2. Adicione um novo usuário

      Clique em "Adicionar conta de usuário" e preencha as seguintes informações:

      • Nome de usuário: Defina um nome que será usado para o acesso do OctoberCMS ao banco, como october_user.
      • Host: Selecione localhost ou 127.0.0.1, garantindo que o acesso só ocorra localmente, aumentando a segurança.
      • Senha: Crie uma senha forte e exclusiva. Nunca use senha de exemplo como password123 em produção.
      • Repetir: Insira novamente a senha escolhida.
      • Na seção "Banco de dados para o usuário", selecione "Criar um banco de dados com o mesmo nome e conceder todos os privilégios". Assim, será criado um banco chamado october_user e o usuário terá privilégios totais sobre ele.
      • Certifique-se de marcar a opção de conceder todos os privilégios em "Privilégios globais" (geralmente já é feita automaticamente ao criar o banco de dados junto ao usuário).
      • Clique em "Executar" ao final da página para finalizar a criação do banco e usuário.

Passo 4: Configurar o Servidor Web (Adicionar Site no ServBay)

Para acessar seu app OctoberCMS pelo navegador, é preciso configurar um site local pelo painel do ServBay.

1. Adicionar novo site

   Abra o painel do ServBay, clique na barra lateral na seção "Sites" (em versões mais antigas, pode estar como "Host"). Toque em "Adicionar site".

   Preencha os seguintes campos:

   • Nome: Escolha um nome identificador, como Meu Site OctoberCMS.
   • Domínio: Insira um domínio local, por exemplo servbay-octobercms.local. Utilize sempre a extensão .local para evitar conflitos com domínios reais.
   • Tipo de site: Escolha PHP.
   • Versão do PHP: Selecione a versão a ser usada pelo OctoberCMS, garantindo que ela está ativada no ServBay e atende aos requisitos do OctoberCMS.
   • Diretório raiz: Clique para escolher o diretório criado no passo 1: /Applications/ServBay/www/servbay-octobercms-app.

2. Salvar configurações e reiniciar o ServBay

   Após preencher tudo, clique em salvar. O ServBay solicitará a aplicação das mudanças, sendo necessário reiniciar os serviços envolvidos (Caddy ou Nginx e, às vezes, o próprio ServBay). Siga as instruções, garantindo que o domínio servbay-octobercms.local aponte para o localhost (127.0.0.1).

Passo 5: Configurar Variáveis de Ambiente do OctoberCMS

OctoberCMS (assim como o Laravel) utiliza o arquivo .env para gerenciar variáveis de ambiente, como informações do banco de dados e chave de aplicação.

1. Copie o arquivo de modelo .env

   No diretório do seu projeto (/Applications/ServBay/www/servbay-octobercms-app), copie o arquivo .env.example e renomeie para .env:

   cd /Applications/ServBay/www/servbay-octobercms-app
   cp .env.example .env

2. Edite o arquivo .env

   Abra o arquivo .env com seu editor de texto favorito. Localize a seção de configuração do banco de dados e ajuste os valores conforme criados no passo 3:

   # ... outras configurações ...
   
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=october_user  # Substitua pelo nome do banco criado
   DB_USERNAME=october_user  # Substitua pelo usuário criado
   DB_PASSWORD=password123   # Substitua pela senha definida
   
   # ... outras configurações ...

   Importante: Certifique-se de substituir DB_DATABASE, DB_USERNAME e DB_PASSWORD pelos dados reais criados no passo anterior.

Passo 6: Executar o Instalador do OctoberCMS

OctoberCMS disponibiliza um assistente web para finalizar a configuração, incluindo migração do banco de dados e criação do usuário administrador.

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

   No navegador, acesse o domínio local configurado no passo 4, acrescentando /install.php. Por exemplo:

   https://servbay-octobercms.local/install.php

   Você verá o assistente de instalação do OctoberCMS.

2. Preencha as informações do banco de dados

   O assistente solicitará os dados de conexão do banco. Insira os mesmos configurados no .env:

   • Tipo de banco de dados: MySQL
   • Host do banco: localhost ou 127.0.0.1
   • Nome do banco: october_user
   • Usuário do banco: october_user
   • Senha do banco: password123

   (Reforçando: use sempre a senha que você definiu)

3. Preencha as informações do administrador

   Siga as instruções para criar o usuário admin do painel OctoberCMS (usuário, senha, e-mail etc.).

4. Finalize a instalação

   Clique no botão de instalação. O sistema executará as migrações, gerará a chave da aplicação e finalizará a configuração. Aguarde até a conclusão.

Passo 7: Instalação de Plugins e Temas (Opcional)

Após instalar, acesse o backend do OctoberCMS (https://servbay-octobercms.local/backend).

1. Instalando plugins

   No painel administrativo, vá em "Sistema" -> "Atualizações" -> "Plugins". Pesquise e instale plugins do Marketplace para adicionar mais recursos.

2. Instalando temas

   Navegue até "Sistema" -> "Atualizações" -> "Temas" para encontrar e instalar temas adequados ao seu projeto.

Configurações e Uso Básico Após a Instalação

Com o OctoberCMS instalado, você pode começar a construir seu site. Veja algumas ações úteis iniciais:

• Acessar o frontend: Visite o domínio local https://servbay-octobercms.local/ para ver o site (normalmente exibe o tema padrão).
• Acessar o backend: Visite https://servbay-octobercms.local/backend e faça login com o usuário admin criado na instalação.
• Criar páginas: No backend, navegue em "CMS" -> "Páginas" para criar e editar páginas do site.
• Criar blocos de conteúdo: No backend, vá em "CMS" -> "Conteúdo" para criar blocos de conteúdo reutilizáveis.
• Configurar temas: Em "CMS" -> "Temas", personalize as opções, layouts e seções do tema ativo.
• Usuários e permissões: Em "Sistema" -> "Gerenciar", administre usuários do backend e suas permissões.

Perguntas Frequentes (FAQ)

• Pergunta: Ao acessar servbay-octobercms.local aparece a página padrão do ServBay ou erro?
  • Resposta: Verifique se o site servbay-octobercms.local foi realmente adicionado no painel do ServBay e se o diretório raiz está apontando para /Applications/ServBay/www/servbay-octobercms-app. Após qualquer ajuste, reinicie o ServBay para aplicar a configuração. Cheque se Caddy/Nginx e o pacote PHP estão funcionando corretamente.
• Pergunta: Ao acessar https://servbay-octobercms.local/install.php aparece tela em branco ou erro?
  • Resposta: Geralmente é erro do PHP. Consulte o log de erros do PHP no painel do ServBay para detalhes. As causas mais comuns são: permissões de arquivo (garanta que as pastas storage, themes e plugins são graváveis pelo usuário do servidor web), versão incompatível do PHP ou módulos/extensões ausentes.
• Pergunta: Erro de conexão com o banco na instalação?
  • Resposta: Confira com atenção os dados de acesso no .env (DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD) e se MySQL/MariaDB está rodando no ServBay. Dados divergentes causarão falhas.
• Pergunta: O comando composer create-project falha?
  • Resposta: Garanta que o pacote Composer está habilitado no painel do ServBay e o PHP está ativado na versão certa. Verifique ainda sua conexão de internet — o Composer precisa baixar arquivos.

Conclusão

O ServBay fornece um ambiente prático para instalação e configuração do OctoberCMS no macOS. Seguindo os passos deste guia, você terá uma plataforma local poderosa e amigável para o desenvolvimento de sites e aplicações web com OctoberCMS. Agora, explore os recursos do OctoberCMS e comece a criar sites incríveis!