# Installation Guide

## Requirements

- PHP 8.4 or newer.
- PHP extensions: BCMath, Ctype, cURL, DOM, Fileinfo, JSON, Mbstring, OpenSSL, PDO, PDO MySQL, Tokenizer and XML.
- Composer 2.
- MySQL 8 or a compatible MariaDB release.
- HTTPS for production.
- Web document root set to the project `public/` directory.

## Fresh installation

1. Upload and extract the project outside the public web root where possible.
2. In the project directory run:

```bash
composer install --no-dev --optimize-autoloader
cp .env.example .env
php artisan key:generate
```

3. Edit `.env` and set `APP_URL` and all `DB_*` values. Keep `SESSION_DRIVER=file` and `CACHE_STORE=file` until the browser installer has completed.
4. Grant the web-server user write access to `storage/` and `bootstrap/cache/`.
5. Create the public storage link:

```bash
php artisan storage:link
```

6. Point the domain document root to `<project>/public`.
7. Open `https://your-domain.example/install` and complete the company, VAT, branch, branding and administrator form.
8. After successful installation, configure mail, queue and scheduler settings. Database sessions and cache may then be enabled if desired.
9. Run the release verification:

```bash
./scripts/verify.sh
```

Do not go live until migrations, automated tests, PDFs, permissions, backup/restore and accountant acceptance have passed on staging.

## Manual non-browser installation

```bash
php artisan migrate --force
php artisan db:seed --class=FoundationSeeder --force
php artisan storage:link
```

Create the first administrator through the browser installer whenever possible because it also writes the installation marker. For automated deployment, create `storage/app/installed` only after company and administrator setup is complete.

## Production optimisation

```bash
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache
```

Run one scheduler invocation every minute and keep a queue worker supervised. Examples are available in `deploy/`.