Back to documentation

Secure installer and recovery

# Secure installation and recovery

Use one installation node and a dedicated MySQL database. Keep the application offline or access-restricted until setup finishes. HTTPS is required for public deployments.

## Prepare a fresh installation

1. Extract a clean source package. Copy `.env.example` to `.env`; configure hosting, install dependencies and build the assets as described in the main guide.
2. Run `php artisan key:generate` only when the fresh installation has no key. Never rotate an existing application's key to retry setup.
3. Run `php artisan installer:token`. Paste the private token into the wizard's **Private setup token** field. Without a token, public visitors cannot submit a valid installation. On hosting without a terminal, generate at least 32 random characters using your hosting control panel's secure password generator, set `INSTALLER_TOKEN` in `.env`, and remove stale configuration cache using the hosting's supported Laravel tools. Never use an example/shared token.
4. Grant the PHP worker write/replace access to `.env`, its parent directory, `bootstrap/cache`, and the nested private storage, sessions, compiled-view and cache directories. Do not grant blanket 777 permissions. Ensure adequate free disk space and inodes.
5. Supply an existing empty database and a database user with migration privileges (CREATE, ALTER, INDEX, REFERENCES, DROP and normal read/write privileges). The installer does not create the database or grant privileges. Reset mode permanently deletes the selected database's tables and views and requires explicit confirmation.
6. Submit the form once. Keep the page open. If the proxy times out but PHP is alive, the wizard keeps polling without a fixed ten-minute cutoff. A percentage is estimated, not migration-by-migration progress.

## Interrupted setup

Private checkpoints are written beside `storage/app/private/installed.json` as `installed.json.pending`. They contain a keyed fingerprint and completed steps, not database/admin passwords.

After a disconnect or server restart, reopen `/install` and submit exactly the same database, administrator and store details, including both passwords and the original database mode. Completed migration/seeding steps are skipped; owner creation and finalization can be retried without wiping again. Reset mode does not wipe again once its wipe checkpoint has been saved. The setup token may be regenerated without changing the recovery fingerprint.

MySQL DDL cannot be made transactional. A process killed inside a migration or inside the wipe itself can leave partial DDL. If a migration retry reports an existing table/column, stop and have the server administrator inspect the private log and selected database. Do not blindly reset a database containing valuable data. A deliberate clean restart requires inspecting that database, archiving/removing only the pending journal, and selecting/resetting that database with fresh explicit consent. Never delete the completed installation marker to recover a running store.

If `.env` or cache finalization fails, correct permissions/disk space and retry the same details. The database, seed data and owner are retained. The installer commits its permanent lock only after writing working configuration and clearing cached configuration. If the final optional `APP_INSTALLED=yes` mirror cannot be written, the permanent marker still locks setup; installation is complete and the private log records that warning.

Web-server/proxy and PHP-FPM hard termination limits, memory exhaustion, disk failure and database outages cannot be overridden by browser JavaScript or `set_time_limit`. Ask the host to allow a sufficiently long setup request. Installation is not a detached queue job. The installer uses a filesystem lock plus a MySQL advisory lock; do not run installation across multiple independent nodes. Use one node with durable private storage, then deploy the completed configuration to other nodes.

## Public storage on restricted hosting

Normally run `php artisan storage:link`. When symlinks are prohibited, configure your web server/control panel to serve `/storage/` directly from this application's `storage/app/public/`, with PHP/script execution disabled. Only after checking that mapping, set `INSTALLER_STORAGE_MAPPING_READY=true`. This is an explicit hosting-administrator assertion, not a file-copy fallback; new uploads must be visible through the mapping. An unrelated existing `public/storage` file or directory is never overwritten.

## Distribution and copied installation locks

Never ship your live `.env`, private storage, `installed.json`, pending journals, lock files, sessions, logs, configuration cache, or database credentials. Ship `.env.example` with `APP_INSTALLED=false` and an empty `INSTALLER_TOKEN`. Run `php artisan installer:package-check` on the clean extracted distribution before uploading. Do not run a package-cleanup command against a live deployment. A completed flag/marker intentionally keeps setup locked even when the database is unavailable; it must not automatically unlock based on database health.

## BillOS additional frontend setup

For BillOS only: configure the backend frontend URL, frontend API URL, allowed CORS origins and HTTPS/cookies using the main BillOS guide. Build/deploy its separate Next.js frontend before handing the application to a customer. Backend installation cannot provision or build a separate frontend host; after setup, the owner uses its ordinary frontend login.