shipu/web-installer
Shipu Web Installer adds a browser-based setup wizard to Laravel apps. It checks server requirements and folder permissions, configures the .env and database connection, runs migrations, and creates the first admin user so you can ship a self-installing app.
shipu/web-installer is a drop-in wizard that walks a fresh Laravel deployment through requirements checks, folder permissions, .env creation, database configuration, and initial admin account setup. Start by requiring it in a project that is not yet installed:
composer require shipu/web-installer
php artisan vendor:publish --provider="Shipu\WebInstaller\WebInstallerServiceProvider"
Publishing typically exposes a config file (the installer's step registry and redirect targets), Blade views, and public assets. Skim the published config first — it is the single source of truth for which steps run, in what order, and where the installer redirects on success/failure. Then visit /install in the browser. The first useful use case is a "download and run" distribution: ship a Laravel app to a client, let them point a browser at /install, and avoid them ever touching a terminal.
You will also want a middleware (or a check in AppServiceProvider) that reads the installer's "installed" flag (usually a lock file such as storage/installed.lock or a config/session key) and redirects un-installed apps to /install.
Guard the app with an install check. Register a global or web-group middleware that short-circuits to the installer when the lock file is absent, and short-circuits away from the installer once it exists. This is the pattern that makes the package feel native rather than bolted on.
Custom steps. The config-driven step list is the main extension point: subclass the base step, implement the view(), validate(), and install()-style methods, and append the class to the config array. This is how you add things like SMTP verification, license-key entry, or tenant provisioning to the wizard.
Environment writes. The .env/.env.example handling step rewrites database, app URL, and mail credentials. Treat the generated .env as a deployment artifact: back up .env.example, and template any non-standard keys you need so the installer's env writer has a source to copy from.
Database step. Point the database step at your migrations. The common pattern is: test the connection first, write the credentials to .env, run migrate --force, then optionally run a seeder that creates the admin from the form input. Do this inside a try/catch and surface the exception message to the wizard so operators can fix credentials without a terminal.
Post-install cleanup. After the install completes, write the lock file, clear caches (config:clear, route:clear), and remove or gate the installer routes. A route group with middleware => ['web'] plus the "not installed" middleware is a reliable way to keep /install inert after go-live.
php artisan config:cache throw LogicException: Your configuration files are not serializable. If you are pinned to v1.0.0, any deploy that runs config:cache will break the installer boot. Upgrade to v1.0.1 before wiring this into a CI/CD or Forge/Ploi deploy hook. If you have already customised the published config, audit it for Closure values and replace them with invokable class strings or config scalars — the framework fix only covers the vendor defaults.config:cache after the installer has written .env, not before, and never leave a cached config pointing at stale DB credentials on the install request. If you see "database connection refused" mid-wizard, php artisan config:clear is the first thing to try.SESSION_DRIVER=database or a Redis-backed cache will fail during the early wizard steps. Use file for both until the database step completes, or configure the installer to switch drivers on the fly.storage/ and bootstrap/cache/; be aware these checks reflect the web server user, not your shell user, so chmod from SSH can pass your check while the installer still fails. Test as the FPM/Apache user..env not writable. This is the single most common installer failure. Ensure the file exists and is group-writable by the web server before the first request; do not rely on the installer to create it from scratch unless it is explicitly designed to.storage/installed.lock (or whatever your config names) must be gitignored, but must be present on redeploys — otherwise every deploy re-opens /install to the public. Ship it via a provisioning step, or gate the route by environment as a belt-and-braces measure.install() method rather than the view, and make it idempotent — users double-submit forms, and a half-completed install is worse than a failed one.How can I help you explore Laravel packages today?