Installation

WebBlocks CMS is distributed as a Composer package installed into a Laravel host application. The host application remains responsible for its bootstrap, environment, database, queues, mail, scheduler, deployment, backups, and public document root. Batched/daily email notifications and daily email summaries require the scheduler every minute; new sites enable these policies by default. Viewing saved messages and panel notifications does not require scheduling or outgoing mail.

Before provisioning a production server, review Hosting Requirements, qualify the intended workload using Hosting Capacity Validation, compare it with the explicitly provisional Hosting Capacity Results, and complete the Hosting Readiness Checklist. Those pages separate the base install contract from optional image, mail, scheduler, backup, and package-native update dependencies; the current partial measurements are not a production certification.

For a normal installation, start in a fresh or existing Laravel 12.55+ or Laravel 13 application with its application key and database configured. Install the package with Composer, then run the CMS installer.

An install is considered complete when the application has a working CMS baseline:

• an app key exists
• the database is reachable
• required tables exist
• core seed data exists
• the first active super_admin exists
• an install completion marker is stored in system_settings

From the root of the Laravel host application, run:

Then open /webadmin/login. This is the primary and supported installation path for CMS users. Cloning this repository does not create a standalone Laravel application.

Supported options:

• --name= first super admin display name
• --email= first super admin email address
• --password= first super admin password
• --site-name= first site name; when omitted, WEBBLOCKS_CMS_DEFAULT_SITE_NAME is used if configured, otherwise the normalized APP_URL host is used
• --site-handle= default site handle
• --repair-partial rename empty partial CMS tables before fresh-install migrations
• --skip-starter-content publish an empty home page instead of the shipped starter page
• --force overwrite package-owned CMS assets or published config files when needed

What webblocks:install does:

• names the first site after the normalized APP_URL host while keeping its internal handle default; www. is omitted from the name, meaningful subdomains are retained, and local or IP hosts fall back to Default Site
• publishes config/webblocks-cms.php when the host app does not already have it
• removes the untouched fresh Laravel welcome route from routes/web.php when it is safe, with a timestamped backup first, so CMS public routes can serve /
• patches app/Models/User.php with WebBlocks\Cms\Auth\Concerns\HasWebBlocksCmsAccess
• creates a timestamped backup before modifying User.php
• skips patching when the trait is already present
• fails clearly if User.php is not a recognizable App\Models\User extends Authenticatable class
• runs the package fresh-install migration path for clean consumer installs
• detects partial CMS schemas before running fresh-install migrations and reports existing CMS tables, row counts, related migration rows, and known foreign key conflicts
• repairs empty partial CMS schemas only when --repair-partial is provided, by renaming empty CMS tables with a timestamped _before_cms_install_... suffix before continuing
• refuses automatic repair when any partial CMS table contains rows
• skips rerunning that fresh schema when CMS tables already exist
• creates Laravel support tables without running host application migrations, currently covering CMS password reset tokens plus sessions, cache, and cache_locks when those database-backed drivers are configured
• does not run the host application's normal Laravel migration set as part of package install, so it avoids conflicts with the already-created CMS-compatible users table
• prepares the backups filesystem disk root used by Backup / Restore
• installs package-owned CMS assets into public/cms
• creates public/storage when it is missing and the environment allows it
• seeds locales, sites, slot types, page layouts, and core block types idempotently
• seeds the complete WebBlocks UI icon catalog from the manifest shipped with the package, so icon fields work with no outbound network and no manual sync
• provisions the published home page served at /, including its layout slots
• fills that home page with the shipped starter content, unless it is turned off
• records the installed version and install completion marker in system_settings
• creates the first active super_admin only when one does not already exist

Package auth is Laravel-native and does not require Breeze, Jetstream, Laravel UI, or Fortify. After install, sign in at /webadmin/login when CMS package auth routes are active. CMS-owned auth views and admin guest redirects use package route names such as webblocks.auth.login and webblocks.auth.logout, so a host product can keep its own global login route, for example /quiztem/login, without stealing CMS form actions or /webadmin redirects.

For the current package-consumer installation model, the host application's App\Models\User remains the auth model and install-time patch target.

If webblocks:install stops after a failed or interrupted prior run, rerun it without repair first and read the partial-install diagnostic. Empty CMS tables can be moved aside explicitly:

The repair mode only renames empty CMS-owned candidate tables. It does not drop tables, does not alter non-empty tables automatically, and does not assume CMS owns the host application.

For site-operation managers, the admin header notification bell links to Dashboard → Panel notifications. The panel reads saved contact messages each time a panel page loads, even when email is disabled or the scheduler has never run. It shows unread messages and messages awaiting reply per accessible site, with links to the filtered contact inbox. Unread messages are included in the awaiting-reply count. The bell badge counts unread contact messages only; read messages awaiting reply and system warnings remain separate on the Dashboard. With no unread messages, the bell is hidden; the Dashboard notification panel remains available. The Actions icon opens the selected site’s inbox to review messages awaiting reply, which can include messages already read. Counts and links never include inaccessible sites, and the summary does not display visitor details.

Opening the panel does not mark messages read, send pending email, retry failed delivery or manufacture scheduler health. Reading a contact message reduces unread work but leaves it awaiting reply; marking it replied or archived removes it from this summary. Spam and quarantined messages remain in the moderation inbox rather than the pending-work count. This is shared inbox state, refreshed on page loads, not a personal notification history. Live Chat retains its own authorized panel indicator, independent of scheduled email.

Immediate-only email with daily summaries disabled also works without a scheduler, provided outbound mail is configured. Batched/daily email and daily email reminders still require background scheduling: logging into the CMS cannot guarantee delivery at the selected time when nobody visits the panel.

Use Updates for the System Updates workflow, backups, and compatibility requirements. Publisher installations older than 1.89.1 must first apply the 1.89.1 license-layout bridge before installing 1.89.2 or later. Check again after the bridge; newer clients perform a follow-up check automatically. Composer installations can update directly through Composer without this Publisher artifact bridge.

User documentation is maintained separately in the webblocks-cms-docs repository under docs/; it is not installed with the CMS package. The package retains resources/contracts/inventory.md as the runtime authoring contract, also available through GET /webadmin/api/inventory. Public docs and guides are publication targets, and no documentation synchronization engine was introduced by the repository split.

The package update adds relational storage for page layout and shared-slot references, staged-update and restore markers, source-sync metadata and managed slots, block application references, API token access lists, site notification policies and scheduler health. Existing values are copied in bounded batches; API payloads and export/import fields keep their existing structure.

Mapped values are read from SQL. Existing JSON fields remain temporary rollback compatibility copies and are synchronized on supported writes. Unmapped settings and full revision snapshots retain their existing storage format in this phase. Unknown historical fields, malformed values and unresolved references are preserved. The update migration is repeatable and its rollback does not delete the new data. If an older package writes those copies after a rollback, reconcile that drift before returning to the SQL-authoritative version.

The next package update moves remaining Block settings and Embedded Application asset/support/schema lists into relational records. Core block fields have typed appearance, media, navigation and content schemas. Bindings, collection settings and application instance values have separate records; typed nodes preserve nested structure and historical/plugin extensions. Asset and enum lists keep order and duplicates, and setting definitions retain their types and defaults.

The migration reads one legacy payload at a time in bounded ID batches and is repeatable. Existing API, renderer, locale, export/import and full revision fields keep their compatible structures. SQL is authoritative; existing JSON columns remain synchronized rollback copies. An update rollback retains SQL data, so review any writes made by an older package before reapplying the new version. Full snapshot and other legacy content/runtime JSON are later migration work.

The package-native migration prepares page, slot and layout settings, block metadata, complete historical snapshots, transfer records, import continuation maps, recovery data, update receipts, icon lists and moderation reasons in SQL. Existing API names and structures remain compatible. Plugin lifecycle state and promotion plans now write SQL; old mutable files are retained until cutover. Preparation is idempotent and does not replace newer SQL plugin state on reruns.

The bridge retains old columns for an updater already executing the previous package. Keep the automatic full backup when installing the subsequent cutover: restoring older code alone cannot restore removed columns or data files. CMS full backups contain the database, public uploads and site-public files; retain the matching package and any required private plugin/local storage separately.

The cutover removes the temporary fields and imported mutable state files after preparation/readback. SQL is the source for all CMS-owned persistent structures, including independent full snapshots. The existing API, signed package, immutable backup and export formats continue to use their established serialization. Publisher offers 1.98.7 first to earlier in-app clients; check again after that bridge to apply 1.98.8. Keep the full backup for a return to older code.

The browser wizard and manual CLI flows below apply only to historical source-maintained or maintenance-repository installations that already contain a complete Laravel host application. They are not alternatives for installing the current package repository by itself. New installations should use the Composer package flow above.

Use the browser wizard for a fresh install.

After the source code is present locally, start with:

Then open http://127.0.0.1:8000/install.

The wizard covers:

• environment readiness checks
• database configuration and connection validation
• core CMS installation
• first super_admin creation
• install locking after completion

Notes:

• the installer is for fresh installs
• if setup is incomplete, the wizard can be reopened and resumed safely
• after completion, install routes are locked and normal auth/admin flow takes over
• the installer writes the selected database configuration into .env

Use the CLI flow when you prefer a standard Laravel setup path for a fresh install.

Notes:

• php artisan db:seed installs the core CMS catalogs, provisions the home page with its starter content, and records the current app version as the installed version for a fresh install
• php artisan storage:link is required if public file serving should use storage/app/public
• runtime directories under storage/framework, storage/logs, and bootstrap/cache are created automatically on first run
• Backup / Restore stores archives on the backups filesystem disk, defaulting to storage/app/backups. The PHP runtime user should own that directory or share a deployment group with read/write access; avoid broad 777 modes.

For a fresh Laravel project running with locally installed PHP and Composer:

Then open:

• public site: /
• admin login: /webadmin/login
• admin: /webadmin

For development of an existing source-maintained Laravel installation:

Notes:

• trusted local development should use .test domains and HTTPS, with https://webblocks-cms.test as the canonical CMS development URL
• php artisan serve remains useful for quick CLI-only checks, but trusted browser workflows should use the native Nginx/PHP-FPM setup documented in docs/native-local-development.md
• local contact form email notifications should use a local SMTP catcher or trusted SMTP test account; the usual local SMTP values depend on the installed tool
• Contact Form notification recipients resolve in this order: block-level recipient_email, current site's default contact recipient, CONTACT_RECIPIENT_EMAIL, then MAIL_FROM_ADDRESS as the last safe fallback
• contact submissions are stored independently from notification delivery, so a public Message sent response confirms storage success even if admin later shows notification Failed, Skipped, or Not configured
• MAIL_MAILER=log, MAIL_MAILER=array, and MAIL_MAILER=null are not real outbound delivery and are shown as not configured for Contact Message notification
• Contact Form blocks render a hidden wrapper (shipped wb-sr-only class) with inert, aria-hidden="true", a renderer-generated form_check_{token} field, tabindex="-1", autocomplete="off", and a form-bound signed timestamp; invalid proof or a filled check field produces the same generic success redirect without storing a Contact Message or attempting notification
• submissions that pass signed proof and the generated check field are scored locally with content, exact and near-duplicate repetition, exact-IP, sender-address, /24 or /64 network, form-burst, and learned site-reputation signals; allowed, quarantined, and spam remain durable admin classifications separate from notification state
• protection requires no CAPTCHA or external service; cache keys use keyed hashes and the 30-day admin metrics contain aggregate decisions rather than submitted content
• when notification delivery fails, admins can inspect the saved message under Admin -> Contact Messages to see the compact failure state in the list and the stored failure detail on the message detail screen

Then open:

• public site: https://webblocks-cms.test
• admin: https://webblocks-cms.test/webadmin
• installer on a fresh install: https://webblocks-cms.test/install

Complete the fresh install in the browser wizard after those setup steps are done.

Cloning the repository is not the normal installation path for application users.

Clone the repository only when developing or contributing to WebBlocks CMS itself:

The repository is package source, not a deployable Laravel application. See the product contributing instructions and the package testing strategy for the development workflow.

• fresh installs automatically redirect to /install
• you can also open the wizard manually at /install
• you can open /install/core to jump directly to the core install step when earlier requirements are already satisfied
• the wizard may advance steps automatically as requirements are completed
• opening / and /install in multiple browser tabs can show different wizard steps; this is expected because the installer tracks progress and routes accordingly

The first super_admin is required for a completed install.

• in the browser wizard, create the first admin during the final setup step
• in the package-consumer CLI flow, provide --name, --email, and --password to webblocks:install
• in a manual install, ensure at least one active super_admin account exists before considering the CMS fully installed

super_admin is the install-level role that can access Users, sites, locales, settings, updates, backups, export/import, and all site content.

A fresh install publishes a home page at / and fills it with starter content: a brand lockup with the product mark beside the heading, a short feature grid, and a closing call to action. These are ordinary blocks, not a hard-coded welcome screen, so the first page a new admin opens in the editor is a working page they can rewrite, reorder, or delete.

The logo is imported into the site's own Media Library at install time and bound to the block like any other image, so it is served from the site's own origin and the operator can replace or delete it in the admin. It is never hot-linked from a remote host: that would make every public visitor issue a third-party request and tie the customer's home page to another host's uptime. An image that cannot be imported — read-only disk, missing file — leaves the block without media instead of failing the install.

Rules that make this safe to ship on every install path:

• starter content is written only into a page that has no blocks at all, so it can never overwrite existing content
• it is install-time only; System Update never adds or restores it
• a missing or unreadable blueprint is reported and skipped, never fatal to an install
• an unknown block type skips that block and its children instead of failing

Controls:

• WEBBLOCKS_CMS_STARTER_CONTENT=false installs an empty published home page. php artisan webblocks:install --skip-starter-content does the same for a single run.
• WEBBLOCKS_CMS_STARTER_CONTENT_PATH points at a directory of your own blueprints when a product should ship its own starter page.
• WEBBLOCKS_CMS_SEND_POWERED_BY_HEADER=true adds X-Powered-By: WebBlocks CMS to CMS public page responses so technology catalogues can identify the product without learning its installed version. Set it to false when an installation policy requires suppressing product identification.

An install created before this feature keeps its empty home page: System Update never adds content. To fill it once:

On a multisite install, --site=handle picks the site; without it the primary site is used.

It provisions the site's page at / if it is missing, then writes the starter blocks only if that page has no blocks. On a site whose home page already has content it does nothing and reports why, and it never touches any other page. Running it twice is safe.

The command takes no class name and does not ask for production confirmation, because both of those break the runners this is for. A hosting panel's Artisan screen cannot answer db:seed's production prompt, and one has been seen to strip the backslashes out of a namespaced --class value, leaving Laravel to resolve Database\Seeders\WebBlocksCmsDatabaseSeedersStarterContentSeeder. The guarantee that would justify a confirmation prompt is structural here instead: starter content is only ever written into a page with no blocks.

The same work is reachable as a seeder, which is what db:seed runs on a fresh install:

Blueprints are JSON files under the package's database/content/starter directory, using the webblocks.cms.starter-content.v1 schema and the same block vocabulary as the AI Page Building Guide. home.json is the shipped default; a locale-specific home.{locale}.json beside it wins for an install whose default locale matches. The directory's README.md documents the file format.

• the installer is locked after completion
• /webadmin is the canonical CMS admin entry point
• package-consumer installs may sign in through /webadmin/login; co-installed apps may keep host-owned /login
• /webadmin/dashboard redirects to /webadmin
• CMS assets stay under /cms, for example /cms/css, /cms/js, and /cms/brand
• package-owned /webadmin/login uses package Blade views, the WebBlocks UI guest auth shell, pinned WebBlocks UI assets, /cms/css/guest.css, and CMS product brand assets from /cms/brand, including normal, dark-surface, on-accent/inverse, and high-contrast favicon/browser-tab variants
• /cms is reserved for CMS-owned static public assets and must not be used as a CMS admin route prefix, alias, or redirect
• /admin is not CMS-owned and must not be restored as a CMS admin route
• new pages start in draft
• if install-level features such as revisions, backups, or updates report missing tables, run php artisan migrate

The /webadmin and /cms split avoids the Nginx try_files collision where /cms/ can be resolved as the physical public/cms/ asset directory before Laravel handles a route. Do not solve admin access by adding a public/cms/index.php handoff; that front-controller bridge must stay absent from root and package public assets.

Configure Laravel mail delivery before publishing a public contact page. A typical SMTP .env setup looks like:

MAIL_* controls Laravel mail delivery for Contact Form notification attempts. MAIL_FROM_ADDRESS is the safe fallback sender/from address and is also the last safe Contact Form recipient fallback when no more specific recipient is configured. CONTACT_RECIPIENT_EMAIL is optional and acts as an environment-level fallback recipient. Prefer configuring the site-level Contact recipient in Site -> Edit -> Contact when available, so contact routing lives with the site instead of only in .env.

After changing production or package-install .env mail settings, clear cached configuration if the install uses config caching:

Contact Form notifications resolve recipients in this order:

1. Contact Form block recipient_email
2. Site default contact recipient from Site -> Edit -> Contact
3. .env CONTACT_RECIPIENT_EMAIL
4. safe MAIL_FROM_ADDRESS fallback

Accepted real Contact Form submissions are stored before email notification is attempted. Notification failure does not mean the public form submission failed. Admins should check /webadmin/contact-messages for stored messages, notification status, and safe failure details. Public visitors should only see normal success or validation feedback, not mail diagnostics.

Sent means the CMS handed the notification to the configured mail transport without an exception; it does not guarantee inbox delivery. Skipped or Not configured means no real notification send was attempted.

Use the native contact_form block for contact pages. Do not replace it with Trusted HTML, raw <form> markup, or mailto: fallbacks. The CMS renderer generates the hidden anti-spam check field automatically; do not create it manually. The old website honeypot field is no longer the public contract.

Practical Contact Form smoke test:

1. Publish or preview a page containing the native contact_form block.
2. Submit a test message with name, email, subject, and message.
3. Open /webadmin/contact-messages.
4. Confirm the message was stored.
5. Review notification status.
6. If email did not arrive, inspect the safe failure details and run mail diagnostics.

Diagnostic commands:

The diagnostic command must not print passwords, tokens, or mail secrets. Use --block=ID to inspect the recipient fallback chain for one Contact Form block. Use --send-test= only for a controlled SMTP send check to an intentional test address.

1. Sign in to /webadmin.
2. Review your site and locale configuration.
3. Configure site identity and domains.
4. Configure Laravel mail settings or approved system mail settings.
5. Configure a Contact Form recipient, preferably on Site -> Edit -> Contact.
6. Run php artisan contact:mail-diagnose.
7. Submit a test native Contact Form and confirm it stores a Contact Message.
8. Review email notification status for that test message.
9. Open the starter home page in the editor and make it your own.
10. Create your first page.
11. Add media, navigation, and blocks.
12. Publish content through the editorial workflow.

The default integrated mode preserves root public URLs. To run beside a Laravel product, configure WEBBLOCKS_CMS_PUBLIC_MOUNT=wb before installation/deployment; public content, search, and sitemap then use /wb, while admin/API/assets/form endpoints retain their dedicated areas. Mounted installation keeps the host welcome route. This is an instance-wide config setting, not a panel or Site setting. Read Public Routing before enabling or changing it, especially for cache rebuilding, host catch-alls, robots ownership, and URL migration.