# Deployment & Online Server Setup Guide

This guide details the deployment architecture and online installation procedures for the **Hospital Management Information System (HMIS)** SaaS platform.

---

## 🚀 Deployment Methods Overview

The system supports two independent deployment pathways:

1. **Zero-Terminal Web GUI Installer (`/install`)**: Designed for hosting accounts without shell access (cPanel, Plesk, DirectAdmin, CyberPanel, or Managed Shared Hosting). Enables non-technical hospital administrators to set up database connections, seed hospital clinical masters, and initialize administrator credentials completely through their web browser.
2. **Linux VPS / Dedicated Server Deployment**: Designed for high-throughput multi-tenant deployments on Ubuntu 22.04/24.04 LTS with Nginx, MySQL 8, PHP 8.2-FPM, Supervisor workers, and Wildcard SSL for automatic tenant subdomain routing (`*.yourdomain.com`).

---

## 📦 Zero-Terminal Web GUI Deployment

### Workflow Summary
```
+-------------------------------------------------------------+
| 1. Prepare Release ZIP with pre-packaged /vendor folder     |
+-------------------------------------------------------------+
                               |
                               v
+-------------------------------------------------------------+
| 2. Upload & Extract via cPanel / Plesk File Manager         |
+-------------------------------------------------------------+
                               |
                               v
+-------------------------------------------------------------+
| 3. Set Web Root Document Root to /public                    |
+-------------------------------------------------------------+
                               |
                               v
+-------------------------------------------------------------+
| 4. Create MySQL Database & User in cPanel Database Wizard   |
+-------------------------------------------------------------+
                               |
                               v
+-------------------------------------------------------------+
| 5. Open https://yourdomain.com/ in Browser                  |
|    - Automatic Redirect to /install                         |
|    - Step 1: System Requirements & PHP Extensions Check     |
|    - Step 2: Database Credentials & Live Connection Test    |
|    - Step 3: Hospital Profile & Super Admin Setup           |
|    - Step 4: 1-Click Automated Migration & Clinical Seeding |
|    - Step 5: Direct Link to /login (Installer Locked)       |
+-------------------------------------------------------------+
```

### Server Requirements Checklist
* **PHP:** $\ge$ 8.2.0
* **PHP Extensions:** `pdo`, `pdo_mysql`, `gd`, `intl`, `mbstring`, `curl`, `fileinfo`, `xml`, `zip`, `bcmath`, `opcache`
* **Writable Directories (`chmod 775`):**
  * `storage/`
  * `storage/app/`
  * `storage/framework/cache/`
  * `storage/framework/sessions/`
  * `storage/framework/views/`
  * `storage/logs/`
  * `bootstrap/cache/`
* **Document Root:** Must point to the `public/` directory, never the application root.

---

## ⚙️ Background Tasks & Cron Scheduler

For both cPanel and VPS installations, enable the Laravel task scheduler:

### cPanel Cron Setup
In cPanel → **Cron Jobs**, add a new cron job running every minute (`* * * * *`):
```bash
/usr/local/bin/php /home/username/hospital_app/artisan schedule:run >> /dev/null 2>&1
```

### Linux VPS Crontab Setup
```bash
sudo crontab -u www-data -e
```
Add:
```cron
* * * * * cd /var/www/hospital-system && php artisan schedule:run >> /dev/null 2>&1
```

---

## 🔒 Security Hardening

1. **Installer Locking:** Once installed, the system creates `storage/installed`. Any subsequent request to `/install` is immediately blocked.
2. **Hidden Files Protection:** Nginx configuration blocks all dotfiles (`.env`, `.git`) with `deny all`.
3. **Storage Isolation:** Patient clinical records and radiology attachments are stored under `storage/app/tenants/{tenant_id}/` and served via authenticated streaming controllers rather than public symlinks.