# Installing Infinity People HRM — Standalone Edition

The standalone edition runs **one company** on your own server (Windows with XAMPP or Laragon, or any Linux box
with PHP and MySQL). There is no tenant sign-up, no subscription and no two-factor authentication: users sign in with
their email address and password.

## 1. What you need

| Component | Version |
|---|---|
| PHP | 8.3 or newer, with the extensions `pdo_mysql` (or `pdo_sqlite`), `mbstring`, `openssl`, `tokenizer`, `xml`, `dom`, `ctype`, `fileinfo`, `json`, `intl`, `gd`, `zip`, `curl` |
| Database | MySQL 8 / MariaDB 10.6+ (recommended) or SQLite (small office / trial) |
| Composer | 2.x — https://getcomposer.org |
| Web server | Apache (XAMPP / Laragon) or Nginx, document root = the `public/` folder. Node.js is **not** needed. |

The setup wizard checks all of this for you.

## 2. Windows — XAMPP

1. Install XAMPP (PHP 8.3) and Composer. In `xampp\php\php.ini` make sure these lines have **no leading `;`**:
   `extension=pdo_mysql`, `extension=mbstring`, `extension=intl`, `extension=gd`, `extension=zip`, `extension=fileinfo`, `extension=curl`, `extension=openssl`.
   Restart Apache from the XAMPP control panel.
2. Unzip `Infinity-People-HRM-Standalone.zip` to `C:\xampp\htdocs\hrm`.
3. Open a command prompt in that folder and install the PHP packages:
   ```bat
   cd C:\xampp\htdocs\hrm
   composer install --no-dev --optimize-autoloader
   ```
4. Point Apache at the `public` folder. Either
   * add a virtual host (recommended) — in `xampp\apache\conf\extra\httpd-vhosts.conf`:
     ```apache
     <VirtualHost *:80>
         ServerName hrm.local
         DocumentRoot "C:/xampp/htdocs/hrm/public"
         <Directory "C:/xampp/htdocs/hrm/public">
             AllowOverride All
             Require all granted
         </Directory>
     </VirtualHost>
     ```
     add `127.0.0.1 hrm.local` to `C:\Windows\System32\drivers\etc\hosts`, restart Apache and browse to `http://hrm.local/`; or
   * simply browse to `http://localhost/hrm/public/` (works, but the URL is longer).
5. Browse to the site. You are sent to the **setup wizard** (`/install`):
   1. *Requirements* — everything should be green.
   2. *Database* — type **MySQL**, host `127.0.0.1`, port `3306`, user `root`, password empty (XAMPP default), database
      `infinity_people_hrm` (created for you). The wizard writes `.env`, runs the migrations and loads the Belize
      Social Security and PAYE rate tables.
   3. *Company & administrator* — company name, contact email, and the first administrator (becomes the **Owner**).
   4. *Done* — open the back office and sign in.

## 3. Windows — Laragon

1. Install Laragon (PHP 8.3 + MySQL). Laragon ships Composer and auto-creates `*.test` hostnames.
2. Unzip to `C:\laragon\www\hrm`, then in Laragon's terminal:
   ```bat
   cd C:\laragon\www\hrm
   composer install --no-dev --optimize-autoloader
   ```
3. Laragon serves Laravel projects from `public/` automatically: browse to `http://hrm.test/` and follow the wizard
   (MySQL user `root`, password empty by default).

## 4. Linux (Ubuntu / Debian example)

```bash
sudo apt install php8.3 php8.3-{cli,fpm,mysql,mbstring,xml,intl,gd,zip,curl,bcmath} mariadb-server composer unzip
sudo mkdir -p /var/www && cd /var/www
sudo unzip Infinity-People-HRM-Standalone.zip -d hrm && cd hrm
composer install --no-dev --optimize-autoloader
sudo chown -R www-data:www-data storage bootstrap/cache && sudo chmod -R ug+rw storage bootstrap/cache
sudo chown www-data:www-data . && cp .env.example .env && sudo chown www-data:www-data .env   # the wizard writes .env
```

Nginx server block (Apache: point `DocumentRoot` at `public/` and allow `.htaccess` overrides):

```nginx
server {
    listen 80;
    server_name hr.example.bz;
    root /var/www/hrm/public;
    index index.php;
    location / { try_files $uri $uri/ /index.php?$query_string; }
    location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php8.3-fpm.sock; }
    location ~ /\.(?!well-known).* { deny all; }
}
```

Browse to the site and follow the wizard, **or** install from the command line:

```bash
php artisan hrm:install                                  # interactive
# or fully scripted:
php artisan hrm:install --db-name=infinity_people_hrm --db-user=hrm --db-pass='secret' \
    --company="My Holdings Ltd." --contact-email=payroll@example.bz \
    --admin-name="Jane Doe" --admin-email=jane@example.bz --admin-password='Str0ng-Passw0rd!' \
    --url=https://hr.example.bz -n
```

Add `--db-connection=sqlite --db-name=database/database.sqlite` for SQLite.

## 5. After installation

* **Settings → Companies**: TIN, Social Security employer and business numbers, address, GL accounts (you may add more
  than one payroll company). **Settings → Company profile**: company name, logo, approval rule, careers page.
* **Settings → Users & roles**: invite the Payroll Officer, Approvers and Viewers (they receive a set-password email).
* `.env`: fill in `MAIL_*` so payslips, invitations and password resets can be emailed. Then run a queue worker:
  `php artisan queue:work --tries=3` (Windows: as a service with NSSM, or a scheduled task at log-on).
* Scheduler (nightly attendance exceptions): cron `* * * * * cd /var/www/hrm && php artisan schedule:run`
  (Windows: a Task Scheduler job every minute running `php artisan schedule:run`).
* Production tuning: `php artisan optimize` after any `.env` change (`php artisan optimize:clear` to undo).
* HTTPS: when `APP_URL` starts with `https://` the app forces secure URLs and cookies. On a plain-HTTP LAN install the
  wizard sets `SESSION_SECURE_COOKIE=false`; set `FORCE_HTTPS=true` once you add a certificate.
* **Back up `.env`** — its `APP_KEY` decrypts Social Security numbers and bank accounts — and the database nightly.

URLs: back office `/app`, employee self-service `/portal`, mobile app `/mobile/`, public careers page `/careers`.

## 6. Importing data from the VB6 HR PayCheck program

Restore the client's `paymaster` MySQL dump, set `LEGACY_DB_*` in `.env`, then:

```bash
php artisan paycheck:import-legacy --with-history --dry-run   # check counts
php artisan paycheck:import-legacy --with-history
```

## 7. Updating

```bash
php artisan down
# unzip the new release over the old one (keep .env, storage/ and public/mobile/icons)
composer install --no-dev --optimize-autoloader
php artisan migrate --force && php artisan optimize
php artisan up
```

## 8. Troubleshooting

| Symptom | Fix |
|---|---|
| Wizard says `.env` is not writable | Give the web server write access to the project folder (XAMPP normally has it), or run `php artisan hrm:install` from the command line instead. |
| "Unknown database" / cannot create database | Create it in phpMyAdmin (`utf8mb4_unicode_ci`) and enter its name again. |
| Blank page or 500 after install | `php artisan optimize:clear`; check `storage/logs/laravel.log`; make sure `storage/` is writable. |
| Login page keeps reloading over HTTP | `.env` has `SESSION_SECURE_COOKIE=true` or `FORCE_HTTPS=true` without HTTPS — set both to `false`. |
| Styles missing | `php artisan filament:assets` (runs automatically on `composer install`). |
| Need to re-run setup | Delete `storage/app/installed.json` (and the database) and browse to `/install` again. |