Instalación

WebBlocks CMS admite un flujo de instalación como paquete de consumo para aplicaciones Laravel nuevas, un asistente de instalación basado en navegador para instalaciones nuevas desde el repositorio de mantenimiento y una vía de instalación manual mediante la CLI de Laravel.

Para una instalación nueva, empiece por llevar el código fuente de WebBlocks CMS a su máquina. Ejecute Composer, cree .env, use Artisan y abra el asistente de instalación del navegador solo después de que el código fuente exista en local.

Una instalación se considera completa cuando la aplicación dispone de una base funcional del CMS:

• existe una clave de aplicación
• la base de datos es accesible
• existen las tablas requeridas
• existen los datos de siembra básicos
• existe el primer super_admin activo
• hay un marcador de instalación completada almacenado en system_settings

Antes de ejecutar cualquier comando de instalación, asegúrese de que el repositorio de WebBlocks CMS está presente en local.

Clonar en un directorio nuevo:

Clonar en un directorio vacío ya creado:

Cuando el código fuente esté presente en local, continúe con una de las vías de instalación nueva que se describen abajo.

Las instalaciones de WebBlocks CMS son únicamente consumidoras de actualizaciones. Pueden hacer fetch o pull de actualizaciones del CMS, o descargarlas, pero no deben enviar commits ni etiquetas al upstream canónico del CMS. En los clones de instalación locales existentes, ejecute git remote set-url --push origin DISABLED una vez en la copia de trabajo de la instalación.

Use este flujo cuando WebBlocks CMS se instale en una aplicación Laravel nueva mediante Composer.

Opciones admitidas:

• --name= nombre visible del primer super admin
• --email= dirección de correo del primer super admin
• --password= contraseña del primer super admin
• --site-name= nombre del sitio por defecto
• --site-handle= handle del sitio por defecto
• --repair-partial renombra las tablas CMS parciales vacías antes de las migraciones de instalación nueva
• --force sobrescribe los assets del CMS propiedad del paquete o los archivos de configuración publicados cuando es necesario

Qué hace webblocks:install:

• publica config/webblocks-cms.php cuando la aplicación anfitriona todavía no lo tiene
• elimina de routes/web.php la ruta welcome sin modificar de un Laravel nuevo cuando es seguro hacerlo, creando antes una copia de seguridad con marca de tiempo, para que las rutas públicas del CMS puedan servir /
• parchea app/Models/User.php con WebBlocks\Cms\Auth\Concerns\HasWebBlocksCmsAccess
• crea una copia de seguridad con marca de tiempo antes de modificar User.php
• omite el parcheo cuando el trait ya está presente
• falla con un mensaje claro si User.php no es una clase App\Models\User extends Authenticatable reconocible
• ejecuta la vía de migración de instalación nueva del paquete para instalaciones de consumo limpias
• detecta esquemas CMS parciales antes de ejecutar las migraciones de instalación nueva e informa de las tablas CMS existentes, los recuentos de filas, las filas de migración relacionadas y los conflictos de claves foráneas conocidos
• repara los esquemas CMS parciales vacíos solo cuando se indica --repair-partial, renombrando las tablas CMS vacías con un sufijo _before_cms_install_... con marca de tiempo antes de continuar
• rechaza la reparación automática cuando alguna tabla CMS parcial contiene filas
• omite volver a ejecutar ese esquema nuevo cuando las tablas del CMS ya existen
• crea las tablas de soporte de Laravel sin ejecutar las migraciones de la aplicación anfitriona; actualmente cubre los tokens de restablecimiento de contraseña del CMS y sessions, cache y cache_locks cuando esos drivers respaldados por base de datos están configurados
• no ejecuta el conjunto normal de migraciones de Laravel de la aplicación anfitriona como parte de la instalación del paquete, de modo que evita conflictos con la tabla users compatible con el CMS ya creada
• prepara la raíz del disco de sistema de archivos backups que usa Backup / Restore
• instala los assets del CMS propiedad del paquete en public/cms
• crea public/storage cuando falta y el entorno lo permite
• siembra de forma idempotente idiomas, sitios, tipos de slot, page layouts, iconos y tipos de bloque básicos
• registra la versión instalada y el marcador de instalación completada en system_settings
• crea el primer super_admin activo solo cuando todavía no existe ninguno

La autenticación del paquete es nativa de Laravel y no requiere Breeze, Jetstream, Laravel UI ni Fortify. Después de la instalación, inicie sesión en /webadmin/login cuando las rutas de autenticación del paquete del CMS estén activas. Las vistas de autenticación propiedad del CMS y las redirecciones de invitado en la administración usan nombres de ruta del paquete como webblocks.auth.login y webblocks.auth.logout, de modo que un producto anfitrión puede conservar su propia ruta global login, por ejemplo /quiztem/login, sin apropiarse de las acciones de formulario del CMS ni de las redirecciones a /webadmin.

Para el límite actual de consumo del paquete v1.32.x, el App\Models\User de la aplicación anfitriona sigue siendo el modelo de autenticación y el objetivo del parcheo en el momento de la instalación.

Si webblocks:install se detiene tras una ejecución anterior fallida o interrumpida, vuelva a ejecutarlo primero sin reparación y lea el diagnóstico de instalación parcial. Las tablas CMS vacías pueden apartarse de forma explícita:

El modo de reparación solo renombra las tablas candidatas vacías propiedad del CMS. No elimina tablas, no altera automáticamente las tablas no vacías y no presupone que el CMS sea propietario de la aplicación anfitriona.

Use el asistente del navegador para una instalación nueva.

Cuando el código fuente esté presente en local, empiece con:

Luego abra http://127.0.0.1:8000/install.

El asistente cubre:

• comprobaciones de preparación del entorno
• configuración de la base de datos y validación de la conexión
• instalación del núcleo del CMS
• creación del primer super_admin
• bloqueo de la instalación al completarse

Notas:

• el instalador es para instalaciones nuevas
• si la configuración está incompleta, el asistente puede reabrirse y reanudarse con seguridad
• una vez completada, las rutas de instalación quedan bloqueadas y toma el relevo el flujo normal de autenticación/administración
• el instalador escribe la configuración de base de datos seleccionada en .env

Use el flujo por CLI cuando prefiera una vía de configuración estándar de Laravel para una instalación nueva.

Notas:

• php artisan db:seed instala los catálogos básicos del CMS y registra la versión actual de la aplicación como versión instalada en una instalación nueva
• php artisan storage:link es necesario si el servicio de archivos públicos debe usar storage/app/public
• los directorios de runtime bajo storage/framework, storage/logs y bootstrap/cache se crean automáticamente en la primera ejecución
• Backup / Restore almacena los archivos comprimidos en el disco de sistema de archivos backups, que por defecto es storage/app/backups. El usuario del runtime de PHP debería ser propietario de ese directorio o compartir un grupo de despliegue con acceso de lectura/escritura; evite modos 777 amplios.

Para un proyecto Laravel nuevo que se ejecuta con PHP y Composer instalados localmente:

Luego abra:

• sitio público: /
• inicio de sesión de administración: /webadmin/login
• administración: /webadmin

Cuando el código fuente esté presente en local:

Notas:

• el desarrollo local de confianza debería usar dominios .test y HTTPS, con https://webblocks-cms.test como URL canónica de desarrollo del CMS
• php artisan serve sigue siendo útil para comprobaciones rápidas solo por CLI, pero los flujos de trabajo de confianza en el navegador deberían usar la configuración nativa de Nginx/PHP-FPM documentada en docs/native-local-development.md
• las notificaciones por correo del formulario de contacto en local deberían usar un capturador SMTP local o una cuenta SMTP de prueba de confianza; los valores SMTP locales habituales dependen de la herramienta instalada
• los destinatarios de las notificaciones de Contact Form se resuelven en este orden: recipient_email a nivel de bloque, el destinatario de contacto por defecto del sitio actual, CONTACT_RECIPIENT_EMAIL y, por último, MAIL_FROM_ADDRESS como reserva segura
• los envíos de contacto se almacenan de forma independiente de la entrega de la notificación, de modo que una respuesta pública Message sent confirma que el almacenamiento tuvo éxito aunque después la administración muestre la notificación como Failed, Skipped o Not configured
• MAIL_MAILER=log, MAIL_MAILER=array y MAIL_MAILER=null no son una entrega saliente real y se muestran como no configurados para la notificación de Contact Message
• los bloques Contact Form renderizan un envoltorio oculto .wb-form-check propiedad del CMS con inert, aria-hidden="true", un campo form_check_{token} generado por el renderizador, tabindex="-1" y autocomplete="off"; cuando ese campo de comprobación generado se rellena, el servidor devuelve la misma redirección genérica de éxito y no almacena ningún Contact Message ni intenta la notificación
• los envíos que superan el campo de comprobación generado todavía pueden clasificarse como spam mediante señales almacenadas conservadoras, como lenguaje de captación comercial, densidad de enlaces, envíos repetidos desde la misma IP o un argumentario de venta desde correo gratuito con un asunto genérico; este estado es una clasificación administrativa duradera y es independiente del estado de la notificación por correo
• cuando la entrega de la notificación falla, el personal administrador puede inspeccionar el mensaje guardado en Admin -> Contact Messages para ver el estado de fallo compacto en la lista y el detalle del fallo almacenado en la pantalla de detalle del mensaje

Luego abra:

• sitio público: https://webblocks-cms.test
• administración: https://webblocks-cms.test/webadmin
• instalador en una instalación nueva: https://webblocks-cms.test/install

Complete la instalación nueva en el asistente del navegador una vez realizados esos pasos de configuración.

• las instalaciones nuevas redirigen automáticamente a /install
• también puede abrir el asistente manualmente en /install
• puede abrir /install/core para saltar directamente al paso de instalación del núcleo cuando los requisitos anteriores ya se cumplen
• el asistente puede avanzar de paso automáticamente a medida que se completan los requisitos
• abrir / e /install en varias pestañas del navegador puede mostrar pasos distintos del asistente; es lo esperado, porque el instalador sigue el progreso y enruta en consecuencia

El primer super_admin es necesario para que una instalación se considere completa.

• en el asistente del navegador, cree el primer administrador durante el paso final de configuración
• en el flujo por CLI como paquete de consumo, proporcione --name, --email y --password a webblocks:install
• en una instalación manual, asegúrese de que existe al menos una cuenta super_admin activa antes de dar el CMS por completamente instalado

super_admin es el rol a nivel de instalación que puede acceder a Users, sitios, idiomas, ajustes, actualizaciones, copias de seguridad, exportación/importación y todo el contenido de los sitios.

• el instalador queda bloqueado una vez completado
• /webadmin es el punto de entrada canónico de administración del CMS
• las instalaciones como paquete de consumo pueden iniciar sesión a través de /webadmin/login; las aplicaciones coinstaladas pueden conservar su /login propiedad del anfitrión
• /webadmin/dashboard redirige a /webadmin
• los assets del CMS permanecen bajo /cms, por ejemplo /cms/css, /cms/js y /cms/brand
• el /webadmin/login propiedad del paquete usa vistas Blade del paquete, el shell de autenticación de invitado de WebBlocks UI, assets de WebBlocks UI fijados, /cms/css/guest.css y los assets de marca del producto CMS de /cms/brand, incluidas las variantes de favicon y de pestaña de navegador normal, para superficie oscura, sobre color de acento/inversa y de alto contraste
• /cms está reservado a los assets públicos estáticos propiedad del CMS y no debe usarse como prefijo, alias ni redirección de rutas de administración del CMS
• /admin no es propiedad del CMS y no debe restablecerse como ruta de administración del CMS
• las páginas nuevas empiezan en draft
• si funciones de nivel de instalación como las revisiones, las copias de seguridad o las actualizaciones informan de tablas que faltan, ejecute php artisan migrate

La separación entre /webadmin y /cms evita la colisión de try_files en Nginx en la que /cms/ puede resolverse como el directorio físico de assets public/cms/ antes de que Laravel gestione una ruta. No resuelva el acceso a la administración añadiendo un traspaso public/cms/index.php; ese puente de front controller debe seguir ausente de los assets públicos de la raíz y del paquete.

Configure la entrega de correo de Laravel antes de publicar una página de contacto pública. Una configuración SMTP típica en .env tiene este aspecto:

MAIL_* controla la entrega de correo de Laravel para los intentos de notificación de Contact Form. MAIL_FROM_ADDRESS es la dirección de remitente segura de reserva y también la última reserva segura de destinatario de Contact Form cuando no hay configurado un destinatario más específico. CONTACT_RECIPIENT_EMAIL es opcional y actúa como destinatario de reserva a nivel de entorno. Prefiera configurar el destinatario de contacto a nivel de sitio en Site -> Edit -> Contact cuando esté disponible, para que el enrutamiento de contacto viva con el sitio y no solo en .env.

Tras cambiar los ajustes de correo de .env en producción o en una instalación por paquete, vacíe la configuración en caché si la instalación usa caché de configuración:

Las notificaciones de Contact Form resuelven los destinatarios en este orden:

1. recipient_email del bloque Contact Form
2. destinatario de contacto por defecto del sitio, desde Site -> Edit -> Contact
3. CONTACT_RECIPIENT_EMAIL de .env
4. reserva segura MAIL_FROM_ADDRESS

Los envíos reales aceptados de Contact Form se almacenan antes de intentar la notificación por correo. Un fallo de notificación no significa que el envío público del formulario haya fallado. El personal administrador debería consultar /webadmin/contact-messages para ver los mensajes almacenados, el estado de la notificación y los detalles seguros del fallo. Las personas visitantes públicas solo deberían ver la respuesta normal de éxito o de validación, no diagnósticos de correo.

Sent significa que el CMS entregó la notificación al transporte de correo configurado sin excepciones; no garantiza la entrega en la bandeja de entrada. Skipped o Not configured significan que no se intentó ningún envío real de notificación.

Use el bloque nativo contact_form para las páginas de contacto. No lo sustituya por Trusted HTML, por marcado <form> en bruto ni por reservas mailto:. El renderizador del CMS genera automáticamente el campo oculto de comprobación antispam; no lo cree manualmente. El antiguo campo honeypot website ya no es el contrato público.

Prueba de humo práctica de Contact Form:

1. Publique o previsualice una página que contenga el bloque nativo contact_form.
2. Envíe un mensaje de prueba con nombre, correo electrónico, asunto y mensaje.
3. Abra /webadmin/contact-messages.
4. Confirme que el mensaje se almacenó.
5. Revise el estado de la notificación.
6. Si el correo no llegó, inspeccione los detalles seguros del fallo y ejecute los diagnósticos de correo.

Comandos de diagnóstico:

El comando de diagnóstico no debe imprimir contraseñas, tokens ni secretos de correo. Use --block=ID para inspeccionar la cadena de reserva de destinatarios de un bloque Contact Form concreto. Use --send-test= solo para una comprobación de envío SMTP controlada a una dirección de prueba intencionada.

1. Inicie sesión en /webadmin.
2. Revise la configuración de su sitio y de los idiomas (locales).
3. Configure la identidad del sitio y los dominios.
4. Configure los ajustes de correo de Laravel o los ajustes de correo del sistema aprobados.
5. Configure un destinatario del Contact Form, preferiblemente en Site -> Edit -> Contact.
6. Ejecute php artisan contact:mail-diagnose.
7. Envíe un Contact Form nativo de prueba y confirme que se guarda un Contact Message.
8. Revise el estado de la notificación por correo de ese mensaje de prueba.
9. Cree su primera página.
10. Añada medios, navegación y bloques.
11. Publique el contenido mediante el flujo de trabajo editorial.