Instalación

Visión general

WebBlocks CMS se distribuye como un paquete Composer instalado en una aplicación host Laravel. La aplicación host sigue siendo responsable de su arranque, entorno, base de datos, colas, correo, programador, implementación, copias de seguridad y raíz de documentos públicos. Las notificaciones por correo electrónico por lotes/diarias y los resúmenes diarios por correo electrónico requieren que el programador funcione cada minuto; Los sitios nuevos habilitan estas políticas de forma predeterminada. Ver mensajes guardados y notificaciones del panel no requiere programación ni correo saliente.

Antes de preparar un servidor de producción, revise los Requisitos de alojamiento, evalúe la carga con la Validación de capacidad, compárela con los Resultados de capacidad, expresamente provisionales, y complete la Lista de preparación. Estas páginas separan el contrato básico de instalación de las dependencias opcionales de imágenes, correo, planificador, copias y actualizaciones del paquete; las mediciones parciales actuales no certifican producción.

Para una instalación normal, utilice una aplicación Laravel 12.55+ o Laravel 13 nueva o existente con clave y base de datos configuradas. Instale el paquete con Composer y ejecute después el instalador del CMS.

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

Instalación como paquete de consumo

Desde la raíz de la aplicación Laravel anfitriona, ejecute:

composer require fklavyenet/webblocks-cms
php artisan webblocks:install --name="Admin User" --email="admin@example.com" --password="secret-password"

Abra después /webadmin/login. Esta es la vía principal y admitida para usuarios del CMS. Clonar este repositorio no crea una aplicación Laravel independiente.

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 primer sitio; si se omite, se usa WEBBLOCKS_CMS_DEFAULT_SITE_NAME cuando está configurado, o el host normalizado de APP_URL
--site-handle= handle del sitio por defecto
--repair-partial renombra las tablas CMS parciales vacías antes de las migraciones de instalación nueva
--skip-starter-content publica una página de inicio vacía en lugar de la inicial incluida
--force sobrescribe los assets del CMS propiedad del paquete o los archivos de configuración publicados cuando es necesario

Qué hace webblocks:install:

nombra el primer sitio según el host normalizado de APP_URL, conservando el identificador interno default; omite www., mantiene subdominios significativos y usa Default Site para hosts locales o IP
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
carga de forma idempotente idiomas, sitios, tipos de slot, diseños de página y tipos de bloque principales
carga todo el catálogo de iconos WebBlocks UI desde el manifiesto del paquete; los campos funcionan sin conexión externa ni sincronización manual
crea la página de inicio publicada en /, incluidos sus slots de diseño
rellena esa página con el contenido inicial incluido, salvo que se desactive
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.

En el modelo actual de instalación del paquete, App\Models\User de la aplicación anfitriona sigue siendo el modelo de autenticación y el destino del parche de instalación.

Recuperación de una instalación parcial

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:

php artisan webblocks:install --repair-partial --name="Admin User" --email="admin@example.com" --password="secret-password"

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.

Notificaciones del panel sin programador (CMS 1.96.0)

Para los administradores de operaciones del sitio, la campana de notificación del encabezado del administrador enlaza con Panel → Notificaciones del panel. El panel lee los mensajes de contacto guardados cada vez que se carga una página del panel, incluso cuando el correo electrónico está deshabilitado o el programador nunca se ha ejecutado. Muestra mensajes no leídos y mensajes en espera de respuesta por sitio accesible, con enlaces a la bandeja de entrada de contactos filtrada. Los mensajes no leídos se incluyen en el recuento de espera de respuesta. La insignia de campana cuenta únicamente los mensajes de contacto no leídos; Los mensajes leídos en espera de respuesta y las advertencias del sistema permanecen separados en el Panel. Sin mensajes no leídos, la campana está oculta; el panel de notificaciones del Panel permanece disponible. El ícono Acciones abre la bandeja de entrada del sitio seleccionado para revisar los mensajes en espera de respuesta, que pueden incluir mensajes ya leídos. Los recuentos y enlaces nunca incluyen sitios inaccesibles y el resumen no muestra detalles de los visitantes.

Al abrir el panel, no se marcan los mensajes leídos, no se envían correos electrónicos pendientes, no se reintenta la entrega fallida ni se fabrica el estado del programador. Leer un mensaje de contacto reduce el trabajo no leído pero lo deja esperando respuesta; marcarlo respondido o archivado lo elimina de este resumen. El spam y los mensajes en cuarentena permanecen en la bandeja de entrada de moderación en lugar del recuento de trabajos pendientes. Este es el estado de la bandeja de entrada compartida, que se actualiza al cargar la página, no un historial de notificaciones personal. Live Chat conserva su propio indicador de panel autorizado, independientemente del correo electrónico programado.

El correo electrónico solo inmediato con resúmenes diarios deshabilitados también funciona sin un programador, siempre que el correo saliente esté configurado. Los correos electrónicos por lotes/diarios y los recordatorios diarios por correo electrónico aún requieren programación en segundo plano: iniciar sesión en CMS no puede garantizar la entrega a la hora seleccionada cuando nadie visita el panel.

Notificaciones programadas y estado del programador

Los sitios nuevos de CMS 1.95.0 utilizan lotes de mensajes de diez minutos y un resumen diario de mensajes pendientes de forma predeterminada. Antes de habilitar estas funciones en producción, el administrador del servidor o el proveedor de alojamiento debe configurar el programador de Laravel para que se ejecute cada minuto. Las actualizaciones registran CMS trabajos sin instalar silenciosamente una entrada del servidor cron. CMS 1.105.25 también ofrece la configuración opcional CLI confirmada explícitamente a continuación. La persona que opera el CMS selecciona la política de notificación; el administrador del servidor es propietario del tiempo de ejecución en segundo plano.

Agregue una entrada al crontab del usuario de la aplicación o al servicio de tareas programadas de alojamiento equivalente:

* * * * * cd /path/to/laravel-app && /path/to/php artisan schedule:run >> /dev/null 2>&1

Reemplace ambas rutas de ejemplo con el directorio de host Laravel real que contiene artisan y el ejecutable CLI PHP apropiado. Web y CLI PHP deben cumplir los requisitos de CMS. Si esta aplicación ya tiene un programador Laravel en funcionamiento, conserve esa entrada; el nuevo trabajo se une al cronograma existente. Esta implementación de notificación sincrónica no requiere un trabajador de cola permanente.

Desde CMS 1.105.25, abra Limpieza → Retención y automatización → Configuración y verificación del programador, o el enlace de configuración en Estado del sistema. La pantalla de solo lectura muestra comandos para esta instalación, el estado real de los latidos y un enlace de actualización. Verifique la ruta CLI PHP mostrada con su proveedor; si es necesario, configure WEBBLOCKS_CMS_SCHEDULER_PHP_BINARY y actualice la configuración de la aplicación. Herne no es necesario. Cualquier panel de alojamiento que admita un comando cada minuto puede utilizar el comando estándar cron anterior.

En un host Unix compatible con acceso CLI, ejecute los comandos con la cuenta del sistema operativo propietaria de artisan, que pueda leer la aplicación y escribir en sus directorios de ejecución. Nunca utilice root:

php artisan webblocks:scheduler:setup
php artisan webblocks:scheduler:setup --install

El primer comando solo inspecciona. El segundo requiere confirmación después de revisar las tareas de cron, systemd y del panel de alojamiento; para una instalación no interactiva ya revisada, utilice --install --yes. --json devuelve un resultado sin datos sensibles y sin preguntas interactivas. El instalador conserva el contenido del crontab, añade una entrada marcada que se ejecuta cada minuto y la vuelve a leer. Las entradas existentes o ambiguas, la actividad real reciente, las definiciones externas legibles, los shells no compatibles, las cuentas incorrectas y los errores de acceso impiden la instalación. No puede descubrir todas las definiciones del proveedor o ilegibles: revíselas antes de confirmar. Sin acceso CLI/crontab, utilice el panel de alojamiento o pida al proveedor que añada el comando. Una actualización del CMS no garantiza los permisos del sistema operativo en todos los alojamientos.

Una entrada cron instalada permanece sin verificar hasta que se ejecute la tarea realmente programada. Espere 1–2 minutos, actualice la actividad registrada y consulte el comando de estado siguiente. La pantalla de configuración muestra la señal de actividad; el comando completo de salud/estado también comprueba la ejecución de las notificaciones. No añada otro programador solo porque la limpieza esté esperando su hora diaria. Las actualizaciones conservan la política guardada y las categorías automáticas seleccionadas en cada instalación; revíselas y guárdelas por separado.

También configure un transporte de correo saliente real, el HTTPS canónico APP_URL y una caché compartida que admita bloqueos atómicos cuando varios trabajadores puedan procesar notificaciones. La actualización del sitio existente conserva las notificaciones completas/inmediatas con los recordatorios diarios desactivados; esas configuraciones de notificación no requieren programación hasta que se cambien.

CMS 1.95.1 agrega el estado registrado al Panel y Sites → Editar → Contacto, y Live Chat 0.7.1 lo expone en su configuración y estado del complemento. La API de notificación del sitio incluye scheduler_health. Verifique las tareas registradas y luego la evidencia de tiempo de ejecución registrada:

php artisan schedule:list
php artisan webblocks:scheduler:status --json

Los usuarios con acceso a System Health revisan el aviso completo del programador en Mantenimiento → System Health → Notificaciones programadas; su Panel muestra un resumen de salud compacto. Los administradores de operaciones del sitio sin ese acceso conservan la tarjeta del Programador detallada en su Panel de control, incluso cuando todos los sitios accesibles usan notificaciones solo inmediatas con resúmenes diarios deshabilitados. En ese caso la tarjeta es informativa y explica que esas notificaciones no requieren programación. Si algún sitio accesible permite el procesamiento por lotes, la entrega diaria o los resúmenes diarios, el estado no verificado o retrasado genera la advertencia; Los sitios inaccesibles nunca influyen en el aviso.

La lista de trabajos confirma únicamente el registro. Running requiere un latido programado reciente y una ejecución de notificación completada recientemente. Aún no verificado significa que no se han registrado pruebas de ejecución confiables. Delayed significa que un latido o una ejecución completa tiene más de cinco minutos. Un error de procesamiento o un esquema de notificación faltante se muestran por separado. Una ejecución actual puede mostrar brevemente En progreso. El comando de estado sale exitosamente solo cuando se verifica el estado de ejecución; otros estados devuelven un estado distinto de cero.

El latido se produce mediante una devolución de llamada programada real. La ejecución manual de php artisan webblocks:notifications:dispatch puede procesar el correo vencido pero no establece el estado del programador. Las lecturas de salud no crean latidos del corazón. La evidencia se almacena en la base de datos de CMS y permanece visible en los procesos web y CLI. Las marcas de tiempo se devuelven en UTC; Las horas de resumen diarias siguen la zona horaria de cada sitio. Ningún contenido del cliente, secretos o texto de excepción sin procesar ingresan a este registro de salud.

Si la programación no se verifica o se retrasa mientras los lotes o los resúmenes diarios están habilitados, el panel advierte que las notificaciones pueden permanecer pendientes e identifica al administrador/proveedor del servidor como el propietario de la configuración. Pídale a ese propietario que inspeccione cron o el programador de alojamiento, la ruta de la aplicación, CLI PHP, los permisos de proceso y los errores de tiempo de ejecución. Luego confirme un nuevo latido y la ejecución de notificación completa. Estas comprobaciones confirman la ejecución registrada en esta instalación; no garantizan la entrega de la bandeja de entrada del destinatario ni certifican de forma independiente cada nodo del servidor.

Actualizar instalaciones existentes

Consulte Actualizaciones para el flujo, las copias y la compatibilidad. Las instalaciones Publisher anteriores a 1.89.1 deben aplicar el puente de licencia 1.89.1 antes de 1.89.2 o posterior. Compruebe de nuevo después; los clientes nuevos lo hacen automáticamente. Composer permite actualizar directamente sin este puente Publisher.

La documentación se mantiene aparte en docs/ del repositorio webblocks-cms-docs; no se instala con el CMS. El paquete conserva el contrato de autoría resources/contracts/inventory.md, accesible también por GET /webadmin/api/inventory. Docs y guías públicas son destinos de publicación; la separación no introdujo un motor de sincronización.

Migración del estado de ejecución a tablas relacionales en CMS 1.98.5

La actualización del paquete agrega almacenamiento relacional para el diseño de página y referencias de espacios compartidos, marcadores de actualización y restauración por etapas, metadatos de sincronización de origen y espacios administrados, referencias de aplicaciones de bloqueo, API listas de acceso a tokens, políticas de notificación del sitio y estado del programador. Los valores existentes se copian en lotes delimitados; API las cargas útiles y los campos de exportación/importación mantienen su estructura existente.

Los valores asignados se leen desde SQL. Los campos JSON existentes siguen siendo copias temporales de compatibilidad con reversiones y se sincronizan en escrituras admitidas. Las configuraciones no asignadas y las instantáneas de revisión completa conservan su formato de almacenamiento existente en esta fase. Se conservan campos históricos desconocidos, valores mal formados y referencias no resueltas. La migración de la actualización es repetible y su reversión no elimina los datos nuevos. Si un paquete anterior escribe esas copias después de una reversión, concilie esa desviación antes de regresar a la versión autorizada SQL.

Migración de los ajustes de bloques y aplicaciones en CMS 1.98.6

La próxima actualización del paquete mueve las configuraciones de bloque restantes y las listas de activos/soporte/esquema Embedded Application a registros relacionales. Los campos del bloque principal tienen esquemas de apariencia, medios, navegación y contenido escritos. Los enlaces, la configuración de la colección y los valores de la instancia de la aplicación tienen registros separados; Los nodos escritos conservan la estructura anidada y las extensiones históricas/de complementos. Las listas de activos y enumeraciones mantienen el orden y los duplicados, y las definiciones de configuración conservan sus tipos y valores predeterminados.

La migración lee una carga útil heredada a la vez en lotes limitados ID y es repetible. Los campos existentes API, renderizador, configuración regional, exportación/importación y revisión completa mantienen sus estructuras compatibles. SQL tiene autoridad; Las columnas JSON existentes siguen siendo copias de reversión sincronizadas. Una reversión de una actualización conserva los datos SQL, por lo tanto, revise cualquier escritura realizada por un paquete anterior antes de volver a aplicar la nueva versión. La instantánea completa y otro contenido/tiempo de ejecución heredado JSON son trabajos de migración posteriores.

Preparación de la migración relacional restante en CMS 1.98.7

La migración nativa del paquete prepara configuraciones de página, espacio y diseño, metadatos de bloques, instantáneas históricas completas, registros de transferencia, mapas de continuación de importación, datos de recuperación, recibos de actualización, listas de iconos y motivos de moderación en SQL. Los nombres y estructuras API existentes siguen siendo compatibles. El estado del ciclo de vida del complemento y los planes de promoción ahora escriben SQL; Los archivos mutables antiguos se conservan hasta la transición. La preparación es idempotente y no reemplaza el estado del complemento SQL más nuevo en las reejecuciones.

El puente conserva columnas antiguas para un actualizador que ya ejecuta el paquete anterior. Mantenga la copia de seguridad completa automática al instalar la transición posterior: la restauración del código anterior por sí sola no puede restaurar las columnas o archivos de datos eliminados. CMS las copias de seguridad completas contienen la base de datos, las cargas públicas y los archivos públicos del sitio; conserve el paquete correspondiente y cualquier complemento privado/almacenamiento local requerido por separado.

Transición final a SQL en CMS 1.98.8

La transición elimina los campos temporales y los archivos de estado mutables importados después de la preparación/lectura. SQL es la fuente de todas las estructuras persistentes propiedad de CMS, incluidas las instantáneas completas independientes. Los formatos existentes API, de paquete firmado, de copia de seguridad inmutable y de exportación continúan utilizando su serialización establecida. Publisher ofrece 1.98.7 primero a clientes integrados en la aplicación anteriores; verifique nuevamente después de que se aplique ese puente 1.98.8. Guarde la copia de seguridad completa para volver al código anterior.

Instalaciones antiguas mantenidas desde código fuente

Los flujos de navegador y CLI siguientes solo se aplican a instalaciones históricas desde fuentes o repositorios de mantenimiento que ya incluyen una aplicación Laravel completa. No sustituyen la instalación del repositorio actual del paquete. Las nuevas instalaciones deben usar el flujo Composer anterior.

Asistente de instalación en el navegador

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

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

composer install
cp .env.example .env
php artisan serve

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

Instalación manual por CLI

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

composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan db:seed
php artisan storage:link
php artisan serve

Notas:

php artisan db:seed carga los catálogos principales, crea la página de inicio con contenido inicial y registra la versión actual como 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.

Instalación local nativa

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

composer require fklavyenet/webblocks-cms
php artisan webblocks:install --name="Admin User" --email="admin@example.com" --password="secret-password"

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:

composer install
cp .env.example .env
php artisan key:generate

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 de formulario generan un contenedor oculto con wb-sr-only, inert, aria-hidden="true", el campo form_check_{token}, tabindex="-1", autocomplete="off" y una marca temporal firmada vinculada al formulario. Una prueba inválida o un campo de control lleno producen la misma redirección de éxito sin guardar mensajes ni intentar notificaciones.
Los envíos válidos se puntúan localmente por contenido, repeticiones exactas o similares, IP exacta, dirección del remitente, red /24 o /64, ráfagas del formulario y reputación aprendida del sitio. Permitido, cuarentena y spam son clasificaciones duraderas independientes de las notificaciones.
La protección no requiere CAPTCHA ni servicios externos; las claves de caché usan hashes con clave y las métricas de 30 días contienen decisiones agregadas, no contenido enviado.
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.

Desarrollo del paquete y contribuciones

Clonar el repositorio no es la instalación normal para usuarios de aplicaciones.

Clone el repositorio solo para desarrollar WebBlocks CMS o contribuir al proyecto:

git clone https://github.com/fklavyenet/webblocks-cms.git
cd webblocks-cms
composer install --no-interaction --prefer-dist
composer validate --strict
composer format:test
composer test

El repositorio contiene fuentes del paquete, no una aplicación Laravel desplegable. Consulte las instrucciones para contribuir y la estrategia de pruebas para el flujo de desarrollo.

Acceder al asistente de instalació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

Creación del primer super admin

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.

Contenido inicial

Una instalación nueva publica una página en / con marca junto al título, una cuadrícula breve de funciones y una llamada final a la acción. Son bloques normales, no una bienvenida fija; el nuevo administrador puede reescribirlos, reordenarlos o eliminarlos desde el editor.

El logo se importa a la biblioteca del sitio durante la instalación y se vincula al bloque como cualquier imagen. Se sirve desde el propio origen y puede reemplazarse o borrarse. Nunca se enlaza directamente a otro servidor: eso generaría peticiones de terceros por visitante y dependería de su disponibilidad. Si falla la importación por disco de solo lectura o archivo ausente, el bloque queda sin imagen sin fallar la instalación.

Reglas para distribuirlo con seguridad en todas las instalaciones:

el contenido inicial solo se escribe en páginas sin bloques; nunca sobrescribe contenido existente
solo ocurre al instalar; las actualizaciones no lo añaden ni restauran
una plantilla ausente o ilegible se informa y omite sin detener la instalación
un tipo de bloque desconocido se omite junto a sus hijos sin fallar

Controles:

WEBBLOCKS_CMS_STARTER_CONTENT=true
WEBBLOCKS_CMS_STARTER_CONTENT_PATH=
WEBBLOCKS_CMS_SEND_POWERED_BY_HEADER=true

WEBBLOCKS_CMS_STARTER_CONTENT=false instala una página de inicio publicada vacía. php artisan webblocks:install --skip-starter-content hace lo mismo para una sola ejecución.
WEBBLOCKS_CMS_STARTER_CONTENT_PATH apunta al directorio de plantillas propias cuando el producto debe incluir su propia página inicial.
WEBBLOCKS_CMS_SEND_POWERED_BY_HEADER=true añade X-Powered-By: WebBlocks CMS a las respuestas públicas para identificar el producto sin revelar la versión. Use false si la política de instalación exige ocultar su identificación.

Añadir contenido inicial a una instalación existente

Las instalaciones anteriores conservan la página vacía; las actualizaciones no añaden contenido. Para rellenarla una vez:

php artisan webblocks:starter-content

En multisitio, --site=handle selecciona el sitio; sin él se usa el principal.

Crea la página en / si falta y escribe los bloques solo si no tiene ninguno. Si ya tiene contenido no actúa y explica por qué. No toca otras páginas; ejecutarlo dos veces es seguro.

El comando no pide clase ni confirmación de producción, porque los ejecutores previstos no lo permiten. El panel Artisan no puede responder a la confirmación de db:seed; uno eliminó las barras de un valor --class, haciendo que Laravel resolviera Database\Seeders\WebBlocksCmsDatabaseSeedersStarterContentSeeder. La garantía es estructural: solo se escribe contenido inicial en páginas sin bloques.

La misma operación está disponible como seeder, ejecutado por db:seed en una instalación nueva:

php artisan db:seed --class="WebBlocks\Cms\Database\Seeders\StarterContentSeeder" --force

Las plantillas son JSON en database/content/starter, con esquema webblocks.cms.starter-content.v1 y el vocabulario de bloques de la Guía de creación con IA. home.json es la predeterminada; la variante home.{locale}.json tiene prioridad si coincide con el idioma predeterminado. README.md documenta el formato.

Notas de configuración habituales

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.

Preparación del correo y del formulario de contacto

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_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=no-reply@example.com
MAIL_FROM_NAME="Site Name"

CONTACT_RECIPIENT_EMAIL=contact@example.com

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:

php artisan optimize:clear

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

recipient_email del bloque Contact Form
destinatario de contacto por defecto del sitio, desde Site -> Edit -> Contact
CONTACT_RECIPIENT_EMAIL de .env
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:

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

Comandos de diagnóstico:

php artisan contact:mail-diagnose
php artisan contact:mail-diagnose --block=ID
php artisan contact:mail-diagnose --send-test=you@example.com

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.

Siguientes pasos tras la instalación

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

Montaje del contenido público

El modo integrado conserva las URL públicas raíz. Para convivir con un producto Laravel, configure WEBBLOCKS_CMS_PUBLIC_MOUNT=wb antes de instalar/desplegar: contenido, búsqueda y sitemap usan /wb, mientras administración/API/recursos/formularios conservan sus áreas. Se mantiene la ruta de bienvenida anfitriona. Es una configuración global, no del panel o sitio. Lea Rutas públicas antes de cambiarla, especialmente sobre caché, rutas generales del host, robots y migración de URL.