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

Descripción general

Sculpin es un potente y flexible generador de sitios estáticos basado en PHP, especialmente adecuado para construir blogs, sitios de documentación o cualquier proyecto que requiera convertir contenido dinámico (como plantillas Twig y archivos Markdown) en páginas HTML estáticas de alto rendimiento. Utiliza Composer para la gestión de dependencias y se basa en componentes de Symfony, ofreciendo una experiencia de desarrollo familiar y fiable.

ServBay es un entorno de desarrollo web local diseñado específicamente para macOS, que integra múltiples paquetes populares como PHP, Composer, bases de datos (MySQL, PostgreSQL, MongoDB, Redis), servidores web (Caddy, Nginx), entre otros, y proporciona una cómoda interfaz gráfica de administración. Utilizar ServBay simplifica enormemente el proceso de montar un entorno de desarrollo Sculpin en macOS, especialmente al gestionar versiones de PHP, dependencias y configuración del servidor web.

Esta guía detalla cómo instalar y configurar Sculpin en ServBay, además de establecer un sitio de desarrollo local.

Escenarios de uso

• Construcción de un blog estático de alto rendimiento usando el stack de PHP.
• Generación de sitios de documentación estáticos para proyectos de código abierto o productos.
• Creación rápida de landing pages o sitios corporativos estáticos sin base de datos backend.
• Escritura de contenido mediante el motor de plantillas Twig y Markdown, disfrutando de la velocidad y seguridad de los sitios estáticos.

Requisitos previos

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

1. Tener ServBay ya instalado y en ejecución en macOS. ServBay provee el entorno PHP necesario, el gestor de dependencias Composer y servidores web (Caddy o Nginx).
2. Poseer conocimientos básicos de manejo de la terminal.
3. Entender los conceptos básicos de PHP, Composer y Markdown.

Pasos para instalar Sculpin

A continuación se presentan los pasos detallados para instalar y configurar Sculpin en el entorno ServBay:

Paso 1: Crear el directorio del proyecto

Primero, crea un nuevo directorio para tu proyecto en el directorio raíz de sitios de ServBay (/Applications/ServBay/www). Usaremos servbay-sculpin-app como nombre de proyecto ejemplo.

Abre la terminal y ejecuta los siguientes comandos:

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

Este directorio será donde estarán los archivos de tu proyecto Sculpin.

Paso 2: Crear el proyecto Sculpin usando Composer

ServBay ya incluye Composer, por lo que no es necesario instalarlo aparte. Puedes usar el comando composer directamente desde la terminal.

Para comenzar rápidamente, usaremos una plantilla base de blog proporcionada oficialmente por Sculpin. En el directorio servbay-sculpin-app que acabas de crear, ejecuta el siguiente comando de Composer:

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

Este comando descargará la plantilla base del blog de Sculpin junto con todas sus dependencias mediante Composer, instalándolas en el directorio actual (.).

Paso 3: Configurar el sitio en ServBay

Para poder acceder a tu sitio Sculpin mediante el servidor web de ServBay (Caddy o Nginx), necesitas añadir una configuración de sitio en ServBay.

1. Abre la aplicación ServBay: Lanza la interfaz gráfica de ServBay.
2. Ve a la pestaña "Sitios": Haz clic en la pestaña "Sitios" en la barra de navegación de la ventana.
3. Añade un nuevo sitio: Haz clic en el botón "+" abajo a la izquierda para añadir una nueva configuración de sitio.
4. Completa la información del sitio:
   • Nombre (Name): Ingresa un nombre fácil de identificar, por ejemplo My Sculpin Site.
   • Dominio (Domain): Introduce el dominio que deseas usar localmente, como servbay-sculpin.local. ServBay configurará automáticamente la resolución local y el certificado SSL para los dominios .local (utilizando ServBay User CA).
   • Tipo de sitio (Type): Selecciona PHP, ya que Sculpin es una aplicación PHP.
   • Versión de PHP (PHP Version): Elige la versión de PHP que prefieras. ServBay soporta varias versiones de PHP, selecciona una compatible con Sculpin (usualmente una versión moderna).
   • Directorio raíz del sitio (Document Root): Este paso es clave. Los archivos estáticos generados por Sculpin se encuentran por defecto en los directorios output_dev o output_prod dentro del proyecto. Para el desarrollo local, apunta el directorio raíz del sitio al directorio de salida de desarrollo: /Applications/ServBay/www/servbay-sculpin-app/output_dev
5. Guarda la configuración: Una vez lleno el formulario, haz clic en "Guardar". ServBay aplicará automáticamente la nueva configuración en su servidor web (Caddy o Nginx). Normalmente no hace falta reiniciar los servicios de ServBay manualmente.

Paso 4: Construir el sitio Sculpin

Con la configuración del sitio completada en ServBay, es el momento de generar los archivos estáticos de tu sitio con Sculpin.

En la terminal, asegúrate de seguir en el directorio raíz del proyecto /Applications/ServBay/www/servbay-sculpin-app y ejecuta el siguiente comando para instalar las dependencias del proyecto (si ya completaste el paso 2 anteriormente, este paso es opcional, pero ejecutarlo asegura que todas las dependencias estén correctas):

composer install

Luego, ejecuta el comando de generación de Sculpin para construir el sitio:

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin: Ruta al ejecutable de Sculpin instalado mediante Composer.
• generate: Comando de Sculpin para generar el sitio estático. Lee el contenido y plantillas del directorio source y luego coloca los archivos generados en el directorio de salida configurado (por defecto, output_dev).
• --watch: Esta opción indica a Sculpin que observe cambios en el directorio source. Al modificarse algún archivo, Sculpin regenera el sitio automáticamente, lo cual es ideal durante el desarrollo.

Cuando el comando se complete y aparezca el mensaje "Sculpin has generated your site!" o similar, los archivos estáticos estarán en el directorio output_dev.

Paso 5: Acceder a tu sitio local de desarrollo

Ahora puedes acceder a tu sitio Sculpin utilizando el dominio que configuraste en ServBay.

Abre tu navegador web y visita el dominio que configuraste en el paso 3:

https://servbay-sculpin.local

Como la raíz del sitio en ServBay apunta a output_dev y tienes el comando sculpin generate --watch ejecutándose (escuchando cambios), podrás previsualizar en tiempo real cualquier modificación que hagas en el contenido y las plantillas del sitio en https://servbay-sculpin.local. Gracias al certificado SSL automático de ServBay, puedes acceder a tu sitio local usando HTTPS de forma segura.

Desarrollo con Sculpin

Ahora que ya tienes Sculpin instalado y configurado en ServBay, puedes comenzar a construir tu sitio estático. Aquí algunos conceptos básicos para el desarrollo:

Breve estructura del proyecto Sculpin

Comprender la estructura básica del proyecto Sculpin te ayudará durante el desarrollo:

servbay-sculpin-app/
├── app/                # Configuración de la aplicación y caché
├── output_dev/         # Directorio de salida de archivos estáticos para desarrollo (la raíz del sitio en ServBay apunta aquí)
├── output_prod/        # Directorio de salida de archivos estáticos para producción
├── source/             # Archivos fuente del sitio (contenido Markdown, plantillas Twig, recursos estáticos, etc.)
│   ├── _layouts/       # Archivos de layout de Twig
│   ├── _posts/         # Artículos del blog en formato Markdown
│   ├── assets/         # Recursos estáticos (CSS, JS, imágenes, etc.)
│   └── index.md        # Archivo Markdown para la Home
├── vendor/             # Dependencias instaladas por Composer
├── sculpin.yml         # Archivo principal de configuración de Sculpin
├── composer.json       # Archivo de configuración de dependencias Composer
└── ...otros archivos

Tu trabajo principal se realizará dentro del directorio source.

Crear una entrada de blog

Para crear una nueva entrada en tu blog Sculpin, solo necesitas crear un nuevo archivo Markdown en el directorio source/_posts. Los nombres de archivo suelen seguir el formato YYYY-MM-DD-slug.md.

Por ejemplo, crea el archivo 2024-06-06-my-first-post.md:

---
title: "Mi primer post"
date: 2024-06-06
tags: [Tutorial, Sculpin, ServBay]
---

# Mi primer post

Este es el contenido de mi primera entrada de blog en Sculpin. Aquí comparto algunas experiencias sobre el uso de ServBay y Sculpin.

Puedes escribir aquí usando la sintaxis Markdown.

## Subtítulo

Lista:
- Elemento 1
- Elemento 2

Tras guardar el archivo, si tienes el comando sculpin generate --watch corriendo, Sculpin detectará el cambio y reconstruirá el sitio. Al refrescar el navegador en https://servbay-sculpin.local verás la nueva entrada publicada.

Crear una nueva página

Para añadir una página independiente (por ejemplo, una página “Sobre nosotros”), crea un archivo Markdown directamente en el directorio source, como about.md:

---
title: "Sobre nosotros"
layout: page.html.twig # Especifica la plantilla que deseas usar
---

# Guía para Sculpin en ServBay

Esta página ofrece una guía para construir un sitio estático con ServBay y Sculpin.

Al guardar el archivo, Sculpin generará un archivo output_dev/about/index.html (si está configurada la generación de URLs amigables). Puedes acceder a ella visitando https://servbay-sculpin.local/about/.

Personalizar estilos y scripts

Los recursos estáticos (como archivos CSS y JavaScript) normalmente se ubican en source/assets. Puedes editarlos directamente.

Por ejemplo, modifica el archivo source/assets/css/style.css para cambiar el estilo de tu sitio.

Estos recursos serán copiados al directorio de salida cuando generes el sitio. Si modificas alguno, la opción --watch de Sculpin detectará el cambio y reconstruirá automáticamente.

Construir el sitio para producción

Cuando tu sitio esté listo para lanzarlo, necesitarás crear una versión optimizada para producción. La build de producción suele aplicar optimizaciones extra, como compresión de recursos.

Ejecuta el siguiente comando para generar el build de producción:

vendor/bin/sculpin generate --env=prod

Este comando generará los archivos estáticos optimizados en el directorio output_prod. Puedes subir el contenido de output_prod a cualquier servicio de hosting estático (como GitHub Pages, Netlify, Vercel, o tu propio servidor web).

Si quieres previsualizar el build de producción en ServBay, simplemente cambia la configuración del "Directorio raíz del sitio" a /Applications/ServBay/www/servbay-sculpin-app/output_prod, guarda la configuración y visita el dominio configurado.

Notas importantes

• Asegúrate de que ServBay esté corriendo y el sitio se encuentre habilitado en la configuración.
• Ten el comando sculpin generate --watch ejecutándose en la terminal para que el sitio se actualice automáticamente durante el desarrollo.
• Verifica que el "Directorio raíz del sitio" en la configuración de ServBay apunte correctamente a la carpeta de salida de Sculpin (usualmente output_dev en desarrollo).
• ServBay genera automáticamente certificados SSL para dominios .local, pero tu sistema operativo podría requerir que confíes en el CA de usuario de ServBay. Consulta la documentación de ServBay para instrucciones detalladas.

Preguntas frecuentes (FAQ)

P: He modificado archivos pero mi sitio no se actualiza, ¿qué hago?

R: Asegúrate de que el comando vendor/bin/sculpin generate --watch esté en ejecución en el directorio del proyecto y que no se haya detenido por errores. Revisa si en la terminal aparece algún error. Limpia la caché del navegador o usa el modo incógnito para descartar archivos antiguos cargados.

P: Veo un error SSL al acceder a https://servbay-sculpin.local, ¿por qué?

R: Esto ocurre porque ServBay genera certificados autofirmados para dominios .local, y necesitas confiar en el CA de usuario de ServBay en tu sistema operativo. Sigue las instrucciones de la documentación de ServBay para instalar y confiar en el certificado raíz.

P: ¿Cómo cambio la versión de PHP?

R: Puedes gestionar múltiples versiones de PHP en la pestaña "Paquetes" dentro de la aplicación ServBay. Luego, en la pestaña "Sitios", edita la configuración de tu sitio Sculpin y selecciona la versión de PHP deseada antes de guardar.

P: ¿Qué motores de plantilla y lenguajes de marcado soporta Sculpin?

R: Sculpin utiliza Twig como motor de plantillas por defecto y soporta ampliamente Markdown para escribir el contenido.

Conclusión

Gracias al entorno integrado de ServBay, instalar y configurar el generador de sitios estáticos Sculpin en macOS es sumamente sencillo. Las instalaciones preconfiguradas de PHP y Composer, junto con servidores web fáciles de administrar y soporte automático de SSL, crean una base sólida para el desarrollo local con Sculpin. Si sigues esta guía, podrás montar rápidamente tu entorno de desarrollo Sculpin y construir y previsualizar eficientemente tus proyectos de sitios estáticos. Aprovechando la flexibilidad de Sculpin y la comodidad de ServBay, te puedes dedicar plenamente a crear contenido de calidad sin preocuparte por la configuración compleja del entorno local.