# Installation Guide — A&B Hub

## Requirements

- PHP 8.3+ with extensions: `pdo_mysql`, `mbstring`, `fileinfo`, `zlib`, `openssl`, `curl` (curl is required for AI/integration features — see note below)
- MySQL 8.0+ (or MariaDB 10.6+)
- Apache 2.4+ with `mod_rewrite`, `mod_headers`, and (recommended) `mod_ssl`, or any web server that can be configured to route all non-file requests to `public/index.php`
- Composer (for `phpmailer/phpmailer` — see step 4)

> **Note on this repository's own build environment**: this codebase was developed and tested in a sandbox with no `curl` extension and no outbound internet access. Every AI/integration client (`OpenAiClient`, `TwilioClient`, `ElevenLabsClient`, `GoogleOAuthService`) is written to the real, correct API contract and degrades gracefully when `curl` is unavailable — but a real deployment needs `curl` enabled to actually reach these providers. Everything else (the full CRM, marketing, reporting, and export system) has no such dependency.

## 1. Get the code onto the server

```bash
git clone <your-repo-url> /var/www/ab-hub-backend
cd /var/www/ab-hub-backend
```

Or unzip the delivered archive to `/var/www/ab-hub-backend`.

## 2. Create the database and application user

Edit the password in `deploy/GRANTS.sql`, then:

```bash
mysql -u root -p < deploy/GRANTS.sql
```

This creates the `ab_hub` database and a dedicated `ab_hub_app` MySQL user with only the privileges the application needs (no root access, no access to other schemas) — verified during development to successfully run every migration.

## 3. Configure environment variables

```bash
cp .env.production.example .env
php bin/generate_key.php   # copy the output into APP_KEY= in .env
```

Edit `.env` and fill in: `DB_PASSWORD` (matching what you set in `GRANTS.sql`), `APP_URL` (your real domain, HTTPS), and mail settings (or leave blank and configure SMTP from Admin > Marketing > SMTP Settings after first login instead).

**`.env` must never be inside `public/`** and must never be committed to version control.

## 4. Install PHP dependencies

```bash
composer require phpmailer/phpmailer
```

This is the only external dependency the application needs. Everything else (PDF export, Excel export, ZIP handling) is hand-implemented in `app/services/` and `app/core/` with zero third-party dependencies — see `docs/DEVELOPER_GUIDE.md` for why.

## 5. Run migrations and seed reference data

```bash
php bin/migrate.php
php bin/seed.php
```

`bin/seed.php` prints one-time generated passwords for the 4 demo users it creates (`jordan@abhomecare.com`, `rita@abhomecare.com`, `tomas@abcleaner.com`, `elena@abhomecare.com`) — **copy them immediately**, they are never stored or shown again. Change these on first login, or delete the demo users entirely once real staff accounts are created (User Management > Users).

## 6. Configure the web server

**Apache**: use `deploy/apache-vhost.conf` as a starting point — edit the domain and paths, `a2ensite` it, and reload. `DocumentRoot` **must** point at `/public`, never the project root (`public/.htaccess` and the project root's own `.htaccess` both defend against this being misconfigured, but the vhost should be correct regardless).

**Nginx** (if preferred over Apache): route every request that isn't a real file under `public/` to `public/index.php` via `try_files $uri $uri/ /index.php?$query_string;`, and deny access to `.env`, `*.sql`, `*.log`, `*.md` the same way `public/.htaccess` does.

## 7. Set file permissions

```bash
chown -R www-data:www-data /var/www/ab-hub-backend
chmod -R 750 storage uploads
```

`storage/` (logs, cache, sessions, backups) and `uploads/` (attachments) must be writable by the web server user.

## 8. Set up cron jobs

See the "Background workers" section of the main `README.md` for the full crontab — the email queue, automation engine, appointment reminders, recurring campaigns, and nightly database backup all run on a schedule, not per-request.

## 9. Verify

- Visit `https://your-domain/login` — should load the login page (HTTPS padlock, no mixed-content warnings).
- Log in with one of the seeded demo accounts.
- Visit `/dashboard` — should show real KPI cards, not an error.
- Admin > Integrations — connect OpenAI/Twilio/etc. here once you have real API credentials; nothing AI-related requires them to use the rest of the CRM.

## Upgrading (applying a new release)

```bash
git pull   # or deploy new files
php bin/migrate.php   # applies only new migrations, safe to run repeatedly
```

Always run `deploy/backup-database.sh` (or wait for the nightly cron) before a migration on a production database you care about.
