Capell Installer

Package docs status

This page is generated from public package documentation in capell-4 core packages and the package manifest checked into the source repository.

Field	Value
Composer package	capell-app/installer
Package slug	installer
Product group	Capell Foundation
Tier	free
Bundle	foundation
Runtime contexts	admin, console
Capell version	^4.0
Source repository	capell-app/capell
Source path	packages/installer
Docs source	packages/installer/docs
Manifest	capell.json

capell-app/installer provides the browser installation workflow for fresh Capell CMS applications. It owns the install routes, progress screens, install guide patches, not-installed dashboard warning, and post-install setup package removal.

Use this package while bootstrapping a new Capell app. It is designed to be removable after setup.

Package Boundary

Installer owns:

• /install browser setup routes and progress/report routes
• Filament install pages and the not-installed dashboard widget
• install guide patch discovery and safe patch application
• first-admin defaults, default package selection, environment preflight checks, and setup package removal

Installer does not own:

• Core install primitives, package manifests, or migration orchestration
• Admin resources beyond installer-specific pages/widgets
• runtime package management or marketplace install authorization
• long-term public or admin runtime behavior after the app is installed

The browser installer works without the Admin panel, but the Filament installer pages and dashboard widget only register when capell-app/admin and Filament are present.

Install

composer require capell-app/installer

Open /install in the host app to run the browser flow. The route is guarded by EnsureNotInstalled unless reinstall is explicitly allowed.

The package config supports these setup env values:

Env var	Purpose
CAPELL_SETUP_ALLOW_REINSTALL	Allow the browser installer to run on an already installed app. Defaults to APP_DEBUG.
CAPELL_SETUP_COMPOSER_BINARY	Composer binary used by installer checks and commands.
CAPELL_SETUP_PHP_BINARY	PHP CLI binary used by installer checks and commands.
CAPELL_SETUP_DEFAULT_PACKAGES	Comma-separated package list selected by default.
CAPELL_SETUP_ADMIN_NAME	Prefill the first admin name.
CAPELL_SETUP_ADMIN_EMAIL	Prefill the first admin email.
CAPELL_SETUP_ADMIN_PASSWORD	Prefill the first admin password.

Treat CAPELL_SETUP_ADMIN_PASSWORD, installer progress URLs, and installer reports as bootstrap secrets. Do not commit real setup credentials, and remove or restrict installer access once the app is installed.

Runtime Surfaces

• Provider: Capell\Installer\Providers\InstallerServiceProvider
• Config: packages/installer/config/capell-installer.php
• Routes: packages/installer/routes/web.php
• Controller: Capell\Installer\Http\Controllers\InstallController
• Middleware: Capell\Installer\Http\Middleware\EnsureNotInstalled
• Pages: InstallCapellPage, InstallGuidePage, InstallProgressPage
• Actions: GetActiveInstallAction, RemoveSetupPackageAction, ApplyInstallGuidePatchesAction
• Patch registry: Capell\Installer\Support\InstallGuide\PatchRegistry

The delete-installer route delegates to RemoveSetupPackageAction, which removes the setup package from the host app after installation.

Install Guide Patches

Install guide patches are explicit, reviewable changes for common host-app setup tasks. They are the Installer package’s main extension point and should be small, idempotent, and safe to re-run.

Patch classes implement Capell\Installer\Support\InstallGuide\Patch, live under Capell\Installer\Support\InstallGuide\Patches, and are registered through PatchRegistry. Keep patch behavior covered by focused tests so a failed patch explains what went wrong instead of leaving a half-edited host file.

The browser installer discovers package and theme choices from Capell package metadata. A package that should appear during setup must be installable by the web PHP process, present in Composer repositories, and described by capell.json metadata that the package registry can read.

Verification

Run installer tests after changing installer routes, setup validation, preflight checks, patching, or package removal:

vendor/bin/pest packages/installer/tests --configuration=phpunit.xml

Run the browser installer spec when changing the web installer flow:

npm run test:installer-browser

Screenshot capture and validation are run from the monorepo root:

npm run screenshots
npm run screenshots:check

Troubleshooting

Symptom	Check	Fix
/install is unavailable on a fresh app	php artisan route:list --name=capell-installer	Confirm the provider was discovered and run php artisan optimize:clear.
/install says Capell is already installed	InstallerInstallationState::capellIsInstalled()	Use the admin panel, or set CAPELL_SETUP_ALLOW_REINSTALL=true only for a controlled local reinstall.
Preflight reports the wrong PHP or Composer binary	php artisan config:show capell-installer.php_binary and php artisan config:show capell-installer.composer_binary	Set CAPELL_SETUP_PHP_BINARY or CAPELL_SETUP_COMPOSER_BINARY, then clear config cache.
Optional packages do not appear	composer show vendor/package --available from the same app	Fix Composer repositories/auth so the web process can resolve the package.
Default admin fields are blank	php artisan config:show capell-installer.admin_user	Set the CAPELL_SETUP_ADMIN_* env values or override the config.
Progress says the session expired	Check the cache driver and capell.install.{installId}.* keys	Restart the installer with a persistent cache store or use the CLI installer.
A guide patch fails	Read the patch reason() and matching patch test	Fix the host file or update the patch probe/apply logic with regression coverage.
Reports/progress pages remain reachable after setup	composer show capell-app/installer	Remove the package or restrict access immediately.

Further Reading

Page	Covers
Installer overview	Installer responsibilities and setup boundaries.
Install guide	Installing Capell into a Laravel app.
Install matrix	Choosing the right install path.
Admin install and setup	Admin setup behavior used during installation.
Package catalogue	Host packages and first-party add-ons.