# Installation

MAVUNO LINK AI runs on PHP 8.2+, Apache, and MySQL 8 or compatible MariaDB. It does not require Node.js, Docker, Python, or a VPS.

## Requirements

- PHP 8.2+ with `pdo_mysql`, `mbstring`, and `fileinfo`.
- MySQL 8 or MariaDB 10.6+ with InnoDB, JSON, and CHECK constraint support.
- Apache with `mod_rewrite` and `.htaccess` overrides enabled.
- A private application directory and a web document root pointed at `public/`.
- Composer is optional for the current application; no external PHP packages are required at runtime.

For cPanel, see [CPANEL_DEPLOYMENT.md](./docs/CPANEL_DEPLOYMENT.md) for document-root fallback, phpMyAdmin-only migration, PHP settings, and hosting-specific security.

## 1. Place the application

Keep the complete project outside the public web root when possible. For example:

```text
/home/account/mavuno-link-ai/       # app/, config/, database/, .env, etc.
/home/account/public_html/          # serves only public/ content
```

Configure Apache's document root as `/home/account/mavuno-link-ai/public`. If you cannot select a document root, use the protected `public_html` shim and copy only public assets as described in the cPanel guide. Do not expose the project root.

## 2. Configure environment variables

Copy `.env.example` to `.env` in the application root. Set the production values:

```dotenv
APP_NAME="MAVUNO LINK AI"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.example
APP_LOCALE=en
APP_TIMEZONE=Africa/Dar_es_Salaam
APP_MAIL_FROM=no-reply@your-domain.example

DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_database_user
DB_PASSWORD=your_long_random_password
DB_CHARSET=utf8mb4

PRIVATE_UPLOAD_PATH=/home/account/mavuno-private-uploads
```

Use the exact database values from the host, keep `.env` outside the document root, and restrict its permissions. Do not commit the real `.env`.

## 3. Create and migrate the database

Create a new database and a dedicated user with privileges limited to that database. Then, from the project root, run:

```sh
php database/migrate.php
```

This CLI-only script applies the SQL files in `database/migrations/` in order and records their checksums. Composer is not required. If CLI is unavailable, import the six migration files in lexical order through phpMyAdmin, then import `database/record-cpanel-import.sql` to record matching checksums. Use this alternative only with the exact migrations shipped with the SQL registry and only against a fresh database.

## 4. Create the first administrator

Use the CLI-only bootstrap after migrations:

```sh
export ADMIN_NAME='Platform Administrator'
export ADMIN_EMAIL='admin@your-domain.example'
export ADMIN_PHONE='+255700000000'
read -s -p 'Temporary administrator password: ' ADMIN_PASSWORD
echo
export ADMIN_PASSWORD
php database/create-admin.php
unset ADMIN_NAME ADMIN_EMAIL ADMIN_PHONE ADMIN_PASSWORD
```

Administrator passwords must be at least 12 bytes. The bootstrap refuses to create another administrator and must never be exposed as an HTTP endpoint. Public registration supports only farmer, transporter, and buyer roles.

## 5. Configure hosting security and writable directories

- Enable HTTPS and set `APP_URL` to the HTTPS origin.
- Set PHP `display_errors=Off` and `log_errors=On`; keep `APP_DEBUG=false`.
- Ensure `public/.htaccess` is active and `mod_rewrite` works.
- Create the `PRIVATE_UPLOAD_PATH` directory outside the document root and allow writes only to the PHP account. Uploaded documents are limited to 5 MiB.
- Keep source, `.env`, migrations, logs, database exports, and backups outside the web root. Keep backups off `public_html`.
- Configure host mail for password-reset messages.

## 6. Verify installation

Check that the public routes render, then test login and actual DB-backed features. Exercise each role with a dedicated test account; verify authorization boundaries, CSRF, uploads, shipments, and notifications. Confirm there are no seeded demo users or activity counts. See [TEST_REPORT.md](./docs/TEST_REPORT.md) for current repository-level test coverage and known integration limits.

If a dashboard returns 503, check the protected PHP error log and verify that `.env` is readable by PHP, the database host is reachable, credentials are correct, and every migration completed. The application intentionally does not expose database exception details publicly.

## External services

No separate payment, road-routing, or machine-learning API credentials are used. Password reset requires the host's PHP mail transport. Bootstrap, Chart.js, Leaflet, and OpenStreetMap tiles load from external services and require browser network access.
