# Installation Guide

## 1. Requirements

- PHP 8.2 or newer (developed and tested on 8.4), with these extensions:
  `pdo`, `pdo_mysql`, `mysqli` (used by the installer only, to load the
  schema), `mbstring`, `gd`, `fileinfo`, `json`, `session`. The `zip`
  extension is recommended (needed for Excel report exports) but not
  required to install.
- MySQL 5.7+ or MariaDB 10.3+
- Apache (with `mod_rewrite` not required — the app uses plain `.php`
  URLs) or Nginx with PHP-FPM
- HTTPS certificate for production (the app enforces camera-permission
  and cookie security best practices, which browsers gate behind HTTPS)

No Node.js, Composer, or build step is required at any point — everything
the browser loads (Bootstrap, Bootstrap Icons, Chart.js, fonts) is
vendored under `assets/vendor/`.

## 2. Upload the Files

Upload the entire project to your hosting account, e.g. via cPanel File
Manager, FTP, or `git clone`. If the application should be the site's
root, upload the contents of this project directly into `public_html/`.
If it should live in a subfolder (e.g. `public_html/vms/`), that works
too — the app computes all its own links relative to wherever it's
deployed (see `app_url()` / `asset()` in `core/Helpers.php`), so no path
constants need to be edited by hand.

## 3. Create a Database

In cPanel → MySQL® Databases (or your host's equivalent):

1. Create a new database (e.g. `youraccount_dhrubovms`).
2. Create a database user with a strong password.
3. Add that user to the database with **all privileges**.

If your hosting plan does not allow the installer to auto-create the
database, this manual step is required — the installer will use whatever
database you point it at.

## 4. Set Folder Permissions

The web server user needs write access to:

```
config/
storage/
storage/backups/
storage/logs/
storage/photos/
storage/exports/
assets/img/uploads/
```

`chmod 755` on each is normally sufficient on shared hosting; the
installer's Requirements screen (step 1) checks each of these and tells
you exactly which ones aren't writable yet.

## 5. Run the Web Installer

Visit `https://yourdomain.com/install/` (or `https://yourdomain.com/vms/install/`
if deployed in a subfolder) and follow the 5-step wizard:

1. **Requirements Check** — confirms the PHP version, required
   extensions, and folder permissions above. All critical checks must
   pass before continuing (the Zip extension is optional — only report
   Excel export needs it).
2. **Database Connection** — enter the host, port, database name,
   username and password from step 3. The installer tests the connection,
   creates the database if your user has permission and it doesn't exist
   yet, and writes `config/config.php` for you (including a random
   `APP_KEY`). Leave **Application URL** blank to auto-detect it from the
   request, or set it explicitly if you're behind a proxy/load balancer.
3. **Install Schema** — creates every table and loads *reference and
   configuration data only*: the 10 system roles and ~35 permissions
   (fully wired up via `role_permissions`), the default visitor types and
   ID types, a starter batch of 30 visitor cards (`VC-001`–`VC-030`), the
   default approval workflow plus two worked examples (VIP and Interview
   Candidate routing), the 4 GUI themes, default settings, and the
   notification event matrix. **No fictional company or demo people are
   inserted** — this file is safe to run on a real, live installation.
4. **Company & Super Admin** — enter your company profile (name, phone,
   email, address) and create the first Super Admin account. This account
   has every permission in the system; you can create additional staff
   accounts with narrower roles afterwards from
   Administration → Users.
5. **Finish** — writes `install/installed.lock`. The installer refuses to
   run again once this file exists.

## 6. Post-Install Checklist

Immediately after installing:

1. **Lock down `/install`.** Delete the folder entirely (recommended), or
   block web access to it in your web server config. The installer won't
   run again while `install/installed.lock` exists, but removing the
   folder is the stronger guarantee — it also removes `schema.sql` and
   `seed_reference.sql` from being downloadable.
2. **Enable HTTPS** and then turn on *Force HTTPS* under
   Settings → Security.
3. Sign in with the Super Admin account and set up your real
   organization structure: Organization → Branches/Locations,
   Departments, Employees.
4. Add your real visitor card inventory under Cards → Card Management
   (30 starter cards, `VC-001`–`VC-030`, were pre-created — add more or
   remove what you don't need).
5. Review Settings → Security (password policy, session timeout, login
   throttling) and Settings → Visitor (OTP/photo/ID/approval requirements,
   default visit duration) for your organization's policy.
6. Create additional staff user accounts with appropriate roles under
   Administration → Users, and review Administration → Roles &
   Permissions if you need a custom role.
7. Configure your approval workflow(s) if the two worked examples
   (VIP, Interview Candidate) don't match your organization — approval
   rules are fully data-driven; no code changes are needed.
8. Pick a GUI theme under System → Templates & Appearance.
9. Take a first backup from System → Backup & Restore once your
   organization data is in place.

## About `install/seed.sql`

`install/schema.sql` and `install/seed_reference.sql` are the only two
files the web installer runs, and both contain zero fictional data — safe
for a real, live installation. `install/seed.sql` is a separate,
**optional** file kept for setting up a demo/evaluation environment: it
layers illustrative sample companies, employees and visitors on top of the
schema. It is never run automatically. If you want a demo environment,
load it manually (`mysql yourdb < install/seed.sql`) into a database you
don't intend to use for real visitor data — do not run it against a
production installation.

## Reinstalling / Starting Over (development only)

Delete `config/config.php` and `install/installed.lock`, drop and
recreate the database, then revisit `/install/`. **Never do this against
a live database with real visitor data** — it drops and recreates every
table.

## Troubleshooting

- **"Configuration file missing"** when visiting any page other than
  `/install/` — `config/config.php` doesn't exist yet; run the installer.
- **Installer says a folder isn't writable** — `chmod 755` the folder
  listed (or ask your host to do it), then reload the Requirements step.
- **Database connection test fails** — double-check host/port/user/password,
  and that the database user has privileges on that database name.
- **Schema install reports an error** — the database user needs `CREATE`,
  `ALTER`, `INDEX` and `REFERENCES` privileges; on most shared hosts
  granting "All Privileges" on the database (step 3 above) covers this.