Instalación y configuración de OctoberCMS en el entorno ServBay

Introducción

OctoberCMS es un sistema de gestión de contenidos (CMS) de código abierto basado en el potente framework Laravel. Destaca por su simplicidad, flexibilidad y su enfoque amigable para desarrolladores. Este documento te guiará en la instalación y configuración de OctoberCMS en ServBay, un entorno local de desarrollo web todo-en-uno para macOS, para que puedas comenzar rápidamente el desarrollo de tus proyectos con OctoberCMS.

¿Qué es OctoberCMS?

OctoberCMS ofrece una interfaz de administración intuitiva y potentes capacidades de desarrollo en el frontend. Permite a los desarrolladores construir todo tipo de sitios web, desde blogs sencillos hasta aplicaciones empresariales complejas, utilizando conceptos familiares de Laravel como Eloquent ORM y el motor de plantillas Blade.

Requisitos previos

Antes de instalar OctoberCMS, asegúrate de cumplir con los siguientes requisitos:

1. ServBay está instalado y ejecutándose en tu sistema macOS.
2. Los paquetes de PHP (se recomienda 7.4 o superior) y MySQL/MariaDB están habilitados y activos en ServBay.
3. El paquete de Composer está habilitado en ServBay.
4. Conocimientos básicos de uso de la línea de comandos.

Pasos para instalar OctoberCMS

Estos son los pasos detallados para instalar y configurar OctoberCMS en tu entorno ServBay:

Paso 1: Crear el directorio del proyecto

Primero, navega hasta el directorio raíz recomendado por ServBay para tus sitios web: /Applications/ServBay/www y crea una nueva carpeta para tu proyecto de OctoberCMS.

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

Paso 2: Instalar OctoberCMS usando Composer

Composer ya viene instalado y configurado en ServBay, solo asegúrate de tener el paquete Composer activado en el panel de control de ServBay. Ahora, ejecuta el siguiente comando en el directorio de tu proyecto para descargar e instalar los archivos principales de OctoberCMS:

composer create-project october/october .

Este comando descarga la versión más reciente de OctoberCMS desde el repositorio oficial en el directorio actual (.).

Paso 3: Crear la base de datos y usuario

OctoberCMS necesita una base de datos para almacenar contenido, usuarios, configuraciones, etc. Usaremos la herramienta phpMyAdmin incluida en ServBay para crear la base de datos y el usuario correspondiente.

1. Accede a phpMyAdmin de ServBay

   Abre tu navegador y ve al panel local de desarrollo de ServBay: https://servbay.host/. Haz clic o navega al enlace de phpMyAdmin proporcionado, que suele ser https://servbay.host/phpmyadmin/ para entrar a la herramienta de administración de bases de datos.

2. Crear un usuario de base de datos

   Por motivos de seguridad y aislamiento, se recomienda crear una base de datos y un usuario independiente para cada aplicación.

   1. Ir a la página de Cuentas de Usuario

      En la página principal de phpMyAdmin, haz clic en el menú superior “Cuentas de usuario”.

   2. Agregar un nuevo usuario

      Haz clic en “Agregar cuenta de usuario”. Rellena los campos:

      • Nombre de usuario: Escribe un nombre para el usuario, por ejemplo, october_user.
      • Host: Selecciona localhost o 127.0.0.1 para que el usuario solo pueda conectarse localmente, aumentando la seguridad.
      • Contraseña: Introduce una contraseña fuerte y única. No uses la contraseña de ejemplo password123 en entornos de producción.
      • Repetir: Vuelve a escribir la contraseña.
      • En la parte de “Base de datos para el usuario”, selecciona “Crear base de datos con el mismo nombre y otorgar todos los privilegios”. Esto crea automáticamente una base de datos llamada october_user y otorga todos los permisos a ese usuario.
      • Asegúrate de marcar los privilegios globales de “Otorgar todos los privilegios” (normalmente se marca automáticamente con la opción anterior).
      • Haz clic en “Ejecutar” al final de la página para crear el usuario y la base de datos.

Paso 4: Configurar el servidor web (Agregar sitio en ServBay)

Para acceder a tu aplicación de OctoberCMS desde el navegador, es necesario configurar un sitio local en ServBay.

1. Agregar nuevo sitio

   Abre el panel de control de ServBay y haz clic en la pestaña “Sitios” (en versiones antiguas puede aparecer como “Host”). Haz clic en “Agregar sitio”.

   Completa los siguientes campos:

   • Nombre: Asigna un nombre identificativo, por ejemplo, My OctoberCMS Site.
   • Dominio: Elige el dominio local por el que accederás, por ejemplo, servbay-octobercms.local. Se recomienda usar el sufijo .local para evitar conflictos con dominios reales.
   • Tipo de sitio: Selecciona PHP.
   • Versión de PHP: Elige la versión de PHP que usará OctoberCMS, asegúrate que sea la misma que tienes activada y compatible con OctoberCMS.
   • Directorio raíz del sitio: Selecciona la carpeta de tu proyecto /Applications/ServBay/www/servbay-octobercms-app.

2. Guarda la configuración y reinicia ServBay

   Cuando termines, haz clic en “Guardar”. ServBay puede pedirte que apliques los cambios, normalmente requiere reiniciar algunos servicios (como Caddy o Nginx) y el propio ServBay. Sigue las instrucciones para que los cambios se apliquen correctamente. El propio ServBay hará que el dominio servbay-octobercms.local apunte a tu localhost (127.0.0.1).

Paso 5: Configurar las variables de entorno de OctoberCMS

OctoberCMS (basado en Laravel) utiliza un archivo .env para gestionar variables de entorno, incluyendo información de la base de datos y clave de la aplicación.

1. Copia el archivo de ejemplo de configuración

   En el directorio raíz de tu proyecto /Applications/ServBay/www/servbay-octobercms-app, copia el archivo .env.example y renómbralo como .env:

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

2. Edita el archivo .env

   Abre el archivo .env con tu editor de texto favorito. Localiza la sección de configuración de la base de datos y modifica los valores con los datos que creaste en el paso anterior:

   # ... otras configuraciones ...
   
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=october_user  # Reemplaza con el nombre de la base de datos que creaste
   DB_USERNAME=october_user  # Reemplaza con el usuario que creaste
   DB_PASSWORD=password123   # Reemplaza con la contraseña que configuraste
   
   # ... otras configuraciones ...

   Importante: Asegúrate de reemplazar los valores de DB_DATABASE, DB_USERNAME y DB_PASSWORD por los realmente creados en el paso 3.

Paso 6: Ejecutar el instalador de OctoberCMS

OctoberCMS incluye un asistente web de instalación para finalizar la configuración, incluyendo la migración de la base de datos y la creación del usuario administrador.

1. Accede a la página de instalación

   Abre tu navegador y accede al dominio local que configuraste en el paso 4, añadiendo /install.php. Por ejemplo:

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

   Deberías ver la pantalla de instalación de OctoberCMS.

2. Introduce los datos de la base de datos

   El asistente te pedirá la conexión a la base de datos. Introduce los mismos datos que pusiste en el archivo .env:

   • Tipo de base de datos: MySQL
   • Host de la base de datos: localhost o 127.0.0.1
   • Nombre de la base de datos: october_user
   • Usuario de la base de datos: october_user
   • Contraseña de la base de datos: password123

   (Repite, usa tu contraseña real creada en el paso 3)

3. Introduce los datos del administrador

   Completa el formulario con el usuario, contraseña y correo que usarás para acceder al panel de administración de OctoberCMS.

4. Finaliza la instalación

   Haz clic en “Instalar” o el botón correspondiente en el asistente. El proceso ejecutará las migraciones de la base de datos, generará la clave de la aplicación, etc. Espera a que finalice la instalación.

Paso 7: Instalar plugins y temas (opcional)

Tras la instalación, puedes entrar al panel administrativo de OctoberCMS en https://servbay-octobercms.local/backend.

1. Instalar plugins

   Desde el panel, navega a “Sistema” -> “Actualizaciones” -> “Plugins”. Allí puedes buscar e instalar plugins del Marketplace de OctoberCMS para añadir funcionalidades.

2. Instalar temas

   Ve a “Sistema” -> “Actualizaciones” -> “Temas”. Podrás explorar e instalar temas según las necesidades de tu proyecto.

Configuración y uso básico tras la instalación

Con OctoberCMS instalado, puedes comenzar a construir tu sitio web. Algunas de las tareas básicas iniciales son:

• Ver el frontend: Accede a tu dominio local https://servbay-octobercms.local/ para ver la página principal (usando el tema predeterminado).
• Acceder al backend: Ingresa a https://servbay-octobercms.local/backend usando la cuenta de administrador creada en la instalación.
• Crear páginas: En el panel, navega a “CMS” -> “Páginas” para crear y editar páginas del sitio.
• Crear fragmentos de contenido: Desde “CMS” -> “Contenido” puedes generar bloques reutilizables.
• Configurar temas: En “CMS” -> “Temas” podrás modificar la configuración del tema actual, layouts, partials, etc.
• Gestionar usuarios y permisos: En “Sistema” -> “Administrar” podrás gestionar los usuarios del backend y sus permisos.

Preguntas frecuentes (FAQ)

• Pregunta: ¿Al acceder a servbay-octobercms.local veo la página por defecto de ServBay o un error?
  • Respuesta: Verifica que se haya agregado correctamente el sitio servbay-octobercms.local en el panel de ServBay y que el directorio raíz apunte a /Applications/ServBay/www/servbay-octobercms-app. Tras agregar o modificar la configuración, asegúrate de reiniciar ServBay para que los cambios surtan efecto. También comprueba que los servicios de Caddy/Nginx y PHP estén en ejecución.
• Pregunta: ¿Acceder a https://servbay-octobercms.local/install.php muestra una página en blanco o error?
  • Respuesta: Normalmente esto indica un error de PHP. Revisa los logs de errores de PHP en el panel de control de ServBay para información detallada. Las causas más comunes incluyen: problemas de permisos de archivos (asegúrate de que los directorios storage, themes y plugins y sus subcarpetas sean escribibles por el usuario del servidor web), versión de PHP incompatible o extensiones faltantes.
• Pregunta: ¿Error de conexión a la base de datos durante la instalación?
  • Respuesta: Revisa cuidadosamente la información de conexión (DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD) en el archivo .env y confirma que coincidan exactamente con los datos creados en phpMyAdmin. Verifica también que el servicio MySQL/MariaDB está activo en ServBay.
• Pregunta: ¿El comando composer create-project falla?
  • Respuesta: Asegúrate de que el paquete Composer está habilitado en ServBay, al igual que el paquete PHP y que tienes la versión adecuada. Comprueba tu conexión a Internet, ya que Composer necesita descargar archivos.

Resumen

Con el entorno sencillo y eficiente de ServBay, puedes instalar y configurar OctoberCMS fácilmente en tu Mac. Siguiendo los pasos de esta guía, estarás listo para crear una potente plataforma local para tu próximo proyecto web, amigable para desarrolladores. ¡Ahora puedes comenzar a explorar todas las funciones de OctoberCMS y construir sitios web increíbles!