Instalación y configuración de Craft CMS en el entorno ServBay

Resumen

Craft CMS es un potente sistema de gestión de contenidos (CMS) apreciado por desarrolladores por su modelado de contenido flexible, interfaz intuitiva y características amigables para el desarrollador. Es ideal para construir sitios web complejos y altamente personalizados.

Usar ServBay como entorno de desarrollo local para Craft CMS ofrece múltiples ventajas, como PHP preconfigurado, bases de datos (tales como MySQL o PostgreSQL), servidores web (Caddy o Nginx), y la integración de Composer y herramientas de línea de comandos, lo que simplifica enormemente la instalación y configuración.

Esta guía explica en detalle cómo instalar y configurar un proyecto Craft CMS dentro del entorno ServBay.

Requisitos previos

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

1. ServBay instalado y en funcionamiento: Verifica que tienes instalado correctamente ServBay en tu macOS, y que la versión de PHP necesaria (consulta los requisitos oficiales de Craft CMS) y la base de datos (usualmente MySQL o PostgreSQL) están activas. ServBay permite fácilmente cambiar y configurar múltiples versiones de PHP y bases de datos según lo requiera Craft CMS.
2. Conocimientos básicos de la terminal: Deberás ejecutar algunos comandos en la terminal, como crear carpetas y utilizar Composer.
3. Familiaridad con Composer: Craft CMS maneja sus dependencias mediante Composer. ServBay ya incluye Composer, pero debes saber cómo utilizar el comando composer create-project.

Pasos para instalar Craft CMS

A continuación, se detallan los pasos para instalar y configurar Craft CMS en el entorno ServBay.

Paso 1: Crear el directorio del proyecto

Primero, crea un nuevo directorio para tu proyecto dentro del directorio raíz de ServBay, que suele ser /Applications/ServBay/www. ServBay configura este directorio como la raíz del servidor web, facilitando el acceso directo a tus proyectos.

Abre la terminal y ejecuta los siguientes comandos:

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

Esto creará una nueva carpeta llamada servbay-craft-app dentro de /Applications/ServBay/www y cambiará el directorio de trabajo a ella.

Paso 2: Crear el proyecto Craft CMS usando Composer

ServBay ya incluye Composer, por lo que puedes crear el proyecto directamente en el directorio del paso anterior. Se recomienda instalar Craft CMS a través de Composer.

Dentro del directorio servbay-craft-app, ejecuta el siguiente comando:

composer create-project craftcms/craft .

Este comando descargará la última versión de Craft CMS y sus dependencias en el directorio actual (.). Espera pacientemente a que Composer finalice el proceso.

Paso 3: Crear la base de datos y el usuario

Craft CMS necesita una base de datos para almacenar el contenido y la configuración. Utilizaremos phpMyAdmin o Adminer incluidos en ServBay para crear la base de datos y el usuario. Usaremos phpMyAdmin como ejemplo.

1. Acceder a la herramienta de gestión de bases de datos de ServBay (phpMyAdmin)

   Abre tu navegador y visita el panel de desarrollo local de ServBay en https://servbay.host/. Busca y haz clic en el enlace "phpMyAdmin" para abrir la herramienta de gestión de bases de datos.

   Consejo: El usuario por defecto para phpMyAdmin en ServBay suele ser root, y la contraseña predeterminada es ServBay.dev. Por seguridad, es recomendable cambiar la contraseña de root o crear un nuevo usuario administrador tras iniciar sesión.

2. Crear un usuario de base de datos

   Si bien puedes conectar Craft CMS usando el usuario root, lo más seguro y recomendable es crear un usuario específico para cada aplicación.

   1. Ir a la página de cuentas de usuario

      En el panel principal de phpMyAdmin, haz clic en la pestaña "Cuentas de usuario" en el menú superior.

   2. Agregar nueva cuenta de usuario

      Haz clic en "Añadir cuenta de usuario" y completa los siguientes datos:

      • Nombre de usuario: Escribe un usuario, como craft_user, para la conexión de Craft CMS.
      • Servidor: Escoge localhost o Local, para limitar el acceso al entorno local.
      • Contraseña: Introduce una contraseña segura. No uses ejemplos como password123, aunque en desarrollo local puedes usar algo sencillo para pruebas, ten en cuenta la seguridad.
      • Repetir: Vuelve a escribir la contraseña para confirmar.
      • En la sección "Base de datos para la cuenta de usuario", selecciona "Crear una base de datos con el mismo nombre y otorgar todos los privilegios". Así, se creará automáticamente una base de datos llamada craft_user y ese usuario tendrá todos los derechos sobre ella.
      • Asegúrate de marcar "Otorgar todos los privilegios".
      • Haz clic en el botón "Continuar" o "Ejecutar" al final de la página.

   Ahora tendrás un usuario de base de datos craft_user y una base de datos con el mismo nombre, con permisos completos.

Paso 4: Configuración del servidor web (añadir sitio en ServBay)

Para que el servidor web de ServBay (Caddy o Nginx) pueda servir tu proyecto Craft CMS, debes crear una nueva configuración de sitio en ServBay.

1. Abrir la aplicación de ServBay

   Inicia la aplicación ServBay.

2. Agregar un nuevo sitio

   Haz clic en la pestaña "Sitios" del panel de navegación izquierdo (en versiones anteriores aparece como "Hosts"). Luego, haz clic en el botón "+" o en "Añadir sitio".

   Completa lo siguiente:

   • Nombre: Pon un nombre identificable, por ejemplo My Craft Site.
   • Dominio: El dominio local a través del cual accederás, por ejemplo servbay-craft.local. ServBay configurará el DNS local para este dominio.
   • Tipo de sitio: Selecciona PHP.
   • Versión de PHP: Elige la versión compatible con Craft CMS. ServBay permite gestionar y utilizar varias versiones de PHP simultáneamente.
   • Directorio raíz del sitio: Este paso es muy importante. Los archivos públicos de Craft CMS (como index.php) están dentro del subdirectorio web del proyecto. Por seguridad, la raíz del servidor web debe apuntar a dicho subdirectorio, no al root del proyecto. Debe ser: /Applications/ServBay/www/servbay-craft-app/web Verifica que la ruta sea correcta y apunte al subdirectorio web que creaste en el paso 1.

3. Guardar la configuración

   Haz clic en "Guardar". ServBay recargará la configuración del servidor web y el nuevo sitio aparecerá en la lista, por ejemplo como servbay-craft.local.

Paso 5: Ejecutar el instalador web de Craft CMS

Ahora puedes instalar Craft CMS accediendo al dominio configurado en tu navegador.

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

   Abre tu navegador e ingresa la URL https://servbay-craft.local/. Craft CMS detectará que no está instalado y te redirigirá automáticamente a la página de instalación, generalmente https://servbay-craft.local/index.php?p=admin/install.

2. Introducir los datos de la base de datos

   En la pantalla de configuración de base de datos, introduce la información creada en el paso 3:

   • Servidor de base de datos: localhost
   • Nombre de la base de datos: craft_user (o el nombre que hayas elegido)
   • Nombre de usuario: craft_user (o el usuario creado)
   • Contraseña: La contraseña establecida para craft_user

   Haz clic en continuar. Si la conexión es exitosa, pasarás al siguiente paso.

3. Crear la cuenta de administrador

   Sigue las instrucciones en pantalla para crear tu cuenta de administrador de Craft CMS. Escribe tu usuario, contraseña y correo electrónico. Elige una contraseña segura.

   Presiona continuar.

4. Configuración del sitio

   Rellena los datos básicos como el nombre de tu sitio.

   Haz clic en "Terminar instalación (Finish Up)". Craft CMS creará las tablas necesarias y generará los archivos de configuración.

   Una vez finalizado, serás redirigido a la pantalla de acceso de Craft CMS.

Paso 6: Configuración inicial y exploración

Una vez dentro del panel de administración de Craft CMS, puedes realizar tareas básicas de configuración y exploración:

1. Revisar el archivo .env: Craft CMS usa el archivo .env para gestionar variables de entorno, incluyendo los datos de la base de datos. Este archivo se genera automáticamente y lo encontrarás en la raíz del proyecto (servbay-craft-app/). Puedes modificar configuraciones como CRAFT_ENVIRONMENT a dev.
2. Instalar complementos: Desde el panel de administración, haz clic en "Plugins" para explorar, instalar y administrar complementos, ampliando las funcionalidades del CMS.
3. Crear estructura de contenido: Explora el apartado "Ajustes" para definir campos personalizados, secciones, categorías, etiquetas y demás estructura de contenido.
4. Configurar el envío de correos: Para probar envíos de correo en local, configura Craft CMS para usar Mailpit o Mailhog de ServBay. En el archivo .env o en los ajustes de correo del panel, selecciona método SMTP, servidor localhost y el puerto indicado por ServBay para Mailpit/Mailhog.

Preguntas frecuentes (FAQ)

• Pregunta: ¿Qué hago si aparece un error de conexión a la base de datos durante la instalación?
  • Respuesta: Revisa que los datos introducidos (servidor, base de datos, usuario y contraseña) sean exactamente iguales a los que creaste en phpMyAdmin. Además, comprueba que el servicio de base de datos (MySQL o PostgreSQL) esté iniciado en ServBay.
• Pregunta: ¿Por qué aparece una página 404 o en blanco al acceder a servbay-craft.local?
  • Respuesta:
    • Verifica que la raíz del sitio esté correctamente apuntando a /Applications/ServBay/www/servbay-craft-app/web. Este es un error común.
    • Confirma que los servicios del servidor web (Caddy o Nginx) y PHP estén activos en ServBay.
    • Asegúrate de que la configuración del sitio servbay-craft.local aparezca y esté activada en la lista de sitios de ServBay.
• Pregunta: ¿La instalación con Composer es muy lenta o falla?
  • Respuesta: Puede deberse a la conexión de red o al mirror de Composer. Intenta cambiar a un mirror local, como el de Aliyun o Packagist China, si te encuentras en China continental.
• Pregunta: Tras la instalación, el panel administrativo o el frontend no muestran estilos o las imágenes no se ven?
  • Respuesta: Generalmente se debe a permisos de archivos. Verifica que el usuario que ejecuta ServBay tenga permisos de escritura sobre los directorios storage y web/cpresources. En caso de problemas, puedes ajustar o restablecer los permisos manualmente.

Conclusión

Siguiendo estos pasos, deberías ser capaz de instalar y configurar exitosamente Craft CMS en tu entorno de desarrollo local ServBay. El entorno integrado de ServBay facilita la gestión de versiones de PHP, bases de datos y configuración del servidor web, permitiéndote centrarte en el desarrollo de tu aplicación Craft CMS. Ahora puedes comenzar a aprovechar el potente modelado de contenido de Craft CMS para construir tu sitio web o aplicación.