# Installation guide

1. Provision PHP 8.3+, Composer 2 and MySQL 8. Create a dedicated database and least-privilege database user.
2. Extract the project and run `composer install --no-dev --optimize-autoloader`.
3. Copy `.env.example` to `.env`; set `APP_ENV=production`, `APP_DEBUG=false`, `APP_URL`, DB credentials, secure session/cookie settings and mail transport.
4. Run `php artisan key:generate` once. Keep `.env` secret and outside public web access.
5. Run `php artisan migrate --seed`.
6. Create the first administrator with `php artisan tinker` and follow the secure procedure below. Do not use a shared/default password.
7. Assign a role through the role_user pivot and set `is_active=true`. Require password change through your operational onboarding process.
8. Point the web server document root to `public/`, not the project root. Ensure `storage/` and `bootstrap/cache/` are writable by the PHP service account.
9. Enforce HTTPS, secure cookies, firewall/database network restrictions, backups, monitoring and a privacy impact assessment before real patient data is entered.
10. Run `php artisan test` and `php artisan route:list` after dependency installation.

## First administrator
Run `php artisan tinker`, then create a unique user with a strong one-time password delivered out-of-band: `$u = App\Models\User::create(['name'=>'System Administrator','email'=>'admin@your-authority.example','password'=>Illuminate\Support\Str::random(48),'is_active'=>true,'must_change_password'=>true]);` then attach the seeded role: `$u->roles()->attach(App\Models\Role::where('name','super_administrator')->firstOrFail());`. Reset the password through a controlled secure channel before login. Never commit credentials.

## Local development
Use `php artisan serve`. Production deployments must use PHP-FPM and a supported web server; do not use the development server.


## PWA and offline sync

Serve the app over HTTPS (or localhost for development). The manifest and service worker provide an installable shell and cache only public static assets. The IndexedDB queue is restricted to inventory stocktake counts; never extend it to patient identifiers, clinical notes, diagnoses or other sensitive health data without a dedicated security architecture and privacy review. Users must remain signed in to synchronise queued stocktakes. Review 409 conflicts before performing a fresh stocktake. Browser storage may be cleared by users or the browser and is not a durable backup.

## Optional DHIS2 adapter

Set `DHIS2_BASE_URL`, `DHIS2_USERNAME`, and `DHIS2_PASSWORD` in the protected server environment. Do not place credentials in frontend code or source control. Configure local facility-to-organisation-unit and indicator-to-data-element mappings, validate the payload against the target DHIS2 instance in a test environment, and obtain data governance approval before sending.


## Docker deployment

See `documentation/DOCKER_DEPLOYMENT.md` for the Docker Compose runbook, first-admin command, HTTPS reverse-proxy notes, and backup/restore procedures. The Docker scaffold has not been executed in this environment.
