laranail/installer-headless

Headless installer engine for any Laravel app — requirements checks, .env generate/update, DB connection test, migrations/seeder, user creation, a pluggable step pipeline, an install-once lock, and a full CLI/TUI. The web UI ships separately as laranail/installer-web.

This package contains all the install logic and no UI coupling, so it runs fully headless (CI, Docker, servers with no browser) and can be driven by any front end through a small public API.

Contents

• Requirements
• Installation
• Quick start
• The step pipeline
• License verification
• Documentation
• Local development
• Sister packages
• Contributing & security
• License

Requirements

Requirement	Constraint
PHP	^8.4.1 (8.4, 8.5)
Laravel	^13.0
Depends on	laranail/package-tools, laranail/console, laranail/license-verifier

Installation

composer require laranail/installer-headless

The service provider is auto-discovered. Publish the config to customize:

php artisan vendor:publish --tag=laranail::installer-headless-config

Quick start guide and usage

Getting started

1. Optionally gate the installer behind an access token. Leaving both INSTALLER_TOKEN and INSTALLER_TOKEN_HASH empty means no gate; --hash writes the hashed form to .env:

   php artisan laranail::installer.token --hash

2. Confirm the application is not installed yet, since a completed install writes a lock that makes the installer refuse to run again:

   php artisan laranail::installer.status

Usage

Web wizard: install laranail/installer-web and visit /install.

Headless (CI / Docker):

php artisan laranail::installer.install \
  --db-driver=mysql --db-host=127.0.0.1 --db-name=app \
  --db-username=root --db-password=secret \
  --app-name="My App" --app-url=https://example.com \
  --user-name="Ada" --user-email=ada@example.com --user-password=secret \
  --no-interaction

Programmatic (any front end):

use Simtabi\Laranail\Installer\Headless\InstallerEngine;
use Simtabi\Laranail\Installer\Headless\Support\InstallerContext;

app(InstallerEngine::class)->run(InstallerContext::fromInput($validatedInput));

The step pipeline

The default pipeline (each step is config-toggleable and reorderable):

welcome → requirements → environment → migrate → user → license (off by default) → final.

Steps are held in a StepRegistry you can extend at runtime — register, insert (before/after), reorder (priority), disable, or replace a step without editing the package. A generic, working ChoiceStep ships disabled for re-adding theme/preset-style selection from config alone. See docs/tools/steps.md.

License verification

Off by default (open-source friendly). When enabled, the license step delegates to laranail/license-verifier — pick any driver (Envato, Keygen, Lemon Squeezy, …) via that package's config. See docs/tools/license.md.

Documentation

Hosted at opensource.simtabi.com/installer-headless/docs/; the same pages live under docs/:

• Installation — requirements, install, publishing
• Configuration — every installer.* config key
• Architecture — engine, steps, state, the two-package boundary
• Wizard engine — one definition (fields + rules) drives CLI + web; single validation path
• Release — tag-driven releases
• CLI & TUI — every laranail::installer.* command
• Environment files — EnvFile/EnvWriter (generate + update)
• Extending steps — add/insert/reorder/replace; ChoiceStep; per-product pipelines
• Runtime DSL — the Installer facade: reshape steps/fields/hooks/pipelines from your provider
• Access lockdown — IP allowlist, token/password gate, time window, throttling, headers, auto-disable
• Events & notifications — lifecycle events, the notification layer, Installer::fake()
• Shared hosting — cPanel/no-SSH: file stores, permissions, web-driven setup
• Admin panels — make Filament/Nova (or any tool) succeed via the installer's seams
• License drivers — enable, swap driver, capabilities

Local development

composer install
composer test      # Pest
composer lint      # Pint + PHPStan + Rector (dry run)
composer format    # apply Pint

Sister packages

• laranail/installer-web — the web wizard UI
• laranail/license-verifier — license verification
• laranail/database-tools — optional SQL-dump import

Contributing & security

See CONTRIBUTING.md. Report vulnerabilities per SECURITY.md (→ opensource@simtabi.com).

License

MIT © Simtabi LLC. See LICENSE.