# Install on Linux or shared hosting

This release contains the existing application, its production PHP dependencies, and the Froiden Laravel Installer 11.0.0 integration. Do not run `laravel new`: that would create a different application. No Composer or Node build is required on the hosting server.

## Install

1. Create an empty MySQL 8+ or MariaDB 10.4+ database and a dedicated user with access to it in your hosting panel. Enable PHP 8.2+ and the extensions shown by the installer. Use HTTPS.
2. Extract the package into a private directory outside `public_html`. Configure the domain/subdomain document root to the release's `application/public` directory. Only that directory is public. Do not put the whole application, INSTALLATION.txt or setup token in a public web directory.
3. Give the hosting PHP user temporary write access to the application root and `.env`, plus write access to `storage` and `bootstrap/cache`. The first request creates a unique application encryption key and environment; no key from the development machine is shipped.
4. Open `https://your-domain/install`, enter the private token from the package's **INSTALLATION.txt**, follow the requirements/permissions screens, choose **Production** or **Testing / Demo**, enter the database and first administrator details, then click **Install application**. You can optionally supply real Turnstile keys at this step.
5. Sign in using the Super Admin email and password you chose. The installer is locked automatically. Keep the generated `.env` and application key safe. Make application source and `.env` read-only to the web user after setup; keep storage and bootstrap/cache writable. Never use permissions such as 777.

The server must support PHP file uploads of at least 160 MB per request, with sufficient `upload_max_filesize` and `post_max_size`. If a host does not support changing the document root, ask it to configure the domain to the application's `public` directory rather than exposing application files.

## What setup does

Froiden supplies the requirement/permission checks and installed marker. Application-specific protected routes replace its stock destructive migration and GET configuration endpoints. Setup requires a private token and CSRF-protected POST requests. It accepts only an empty database, uses normal additive migrations, creates default roles/permissions/services and bootstraps the server owner's first Super Admin. It never runs `migrate:fresh` or drops existing tables. Interrupted setup can resume only with its original database and administrator email.

The installer is for a fresh installation. Do not extract it over an existing application or point it at the development database. Existing sites should use a reviewed update process and preserve their environment, key, storage and backups.

No existing accounts, passwords, project uploads, payment credentials, database data, encryption recovery material, logs or backups are included. Database-file encryption is a hosting/database feature and is not enabled merely by running this installer; field encryption uses the fresh application key. Arrange equivalent storage encryption and protected backup/key recovery with the hosting provider.

## Configure after setup

- Add real institutions, managers, production employees and teams. Default service labels are configurable; confirm the approved catalogue/prices.
- Set the business/billing identity and approved privacy, refund and cancellation policies.
- Configure SMTP/transactional mail, real Turnstile keys and approved payment providers, and test each integration.
- Configure ClamAV or the supported scanner command. Real uploaded files remain quarantined until scanned.
- Configure a queue worker and a scheduler cron (`php /private/path/application/artisan schedule:run` every minute). On shared hosting without a persistent worker, arrange a bounded recurring `php artisan queue:work --stop-when-empty` through the hosting panel; avoid overlapping workers.
- Configure encrypted backups and an off-server destination/retention plan. Verify recovery separately.
- Run `php artisan platform:check` when shell access is available. Configuration readiness does not replace live acceptance tests.

See DEPLOYMENT.md, TURNSTILE.md and UPLOAD_STORAGE.md for details. The package does not provision hosting, a database server, mail/payment accounts or system-level scanner services.

## Test credentials below the login form

Choose **Testing / Demo** during installation to generate role credentials below the hosted testing login form. They can be copied or selected with **Use this account**. Testing mode supports new-account signup and session-limited password-reset previews without SMTP, with normal CSRF/password/Turnstile checks. Production always hides these features even if demo flags are enabled. See [TESTING_GUIDE.md](TESTING_GUIDE.md).

For a private existing demo, configure `APP_ENV=staging` (or local), `DEMO_TESTING_ENABLED=true`, `AUTH_EMAIL_VERIFICATION_REQUIRED=false` and `DEMO_LOGIN_CHOICES=true`, then run `php artisan demo:accounts`. The web installer does this automatically for its Testing/Demo option. Use disposable data on the testing copy and install production separately for real users.

## Verification and package integrity

The ZIP includes a file manifest and an adjacent SHA-256 checksum file. Dependencies are locked in composer.lock and installed without development packages. Check the SHA-256 after transferring the ZIP. Linux hosting still needs the supported PHP/database services; those cannot be installed by a PHP application on shared hosting.

Sources: [Froiden Laravel Installer](https://github.com/Froiden/laravel-installer), [Laravel deployment requirements](https://laravel.com/docs/12.x/deployment).