# 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`](https://github.com/capell-app/capell/edit/4.x/packages/installer/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 ```bash 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: ```bash vendor/bin/pest packages/installer/tests --configuration=phpunit.xml ``` Run the browser installer spec when changing the web installer flow: ```bash npm run test:installer-browser ``` Screenshot capture and validation are run from the monorepo root: ```bash 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](overview.md) | Installer responsibilities and setup boundaries. | | [Install guide](../../docs/getting-started/install.md) | Installing Capell into a Laravel app. | | [Install matrix](../../docs/getting-started/install-matrix.md) | Choosing the right install path. | | [Admin install and setup](../../docs/development/admin-install-setup.md) | Admin setup behavior used during installation. | | [Package catalogue](../../docs/packages/catalog.md) | Host packages and first-party add-ons. |