# Deployment: Queue Worker & Scheduler

This folder holds the version-controlled process configs that keep background
work running for Shalom CareSol:

- **Queue worker** — processes queued jobs (SMS broadcasts, mail notifications).
  Required because `QUEUE_CONNECTION=database`.
- **Scheduler** — fires the daily cron-style tasks, including the SMS jobs
  (birthday + appointment reminders at **06:30 Africa/Lagos**).

| File | Purpose |
|------|---------|
| `supervisor/shalom-queue.conf` | Supervisor program for the queue worker (**required in prod**) |
| `supervisor/shalom-scheduler.conf` | Supervisor program for the scheduler (**optional** — use instead of cron) |
| `crontab.txt` | System cron entry for the scheduler (**recommended** approach) |

Server paths assumed: app at `/var/www/html/blouza/shalom-backend`, PHP at
`/usr/bin/php8.4`, run as user `www-data`. Adjust if your host differs.

---

## 1. Install Supervisor (once)

```bash
sudo apt-get update
sudo apt-get install -y supervisor
```

## 2. Queue worker (required)

```bash
sudo cp deploy/supervisor/shalom-queue.conf /etc/supervisor/conf.d/
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status shalom-queue:*     # -> RUNNING
```

Everyday commands:

```bash
sudo supervisorctl status shalom-queue:*
sudo supervisorctl restart shalom-queue:*
sudo supervisorctl stop shalom-queue:*
tail -f storage/logs/queue-worker.log
```

To scale throughput, raise `numprocs` in the conf and re-run
`reread` + `update`.

## 3. Scheduler (choose ONE)

**Option A — system cron (recommended):**

```bash
sudo crontab -u www-data -e
# paste the line from deploy/crontab.txt
```

**Option B — Supervisor:**

```bash
sudo cp deploy/supervisor/shalom-scheduler.conf /etc/supervisor/conf.d/
sudo supervisorctl reread && sudo supervisorctl update
```

Confirm the tasks and their next run:

```bash
php artisan schedule:list
```

---

## Deploy checklist (run on every release)

```bash
git pull
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:cache        # picks up config/sms.php changes
php artisan route:cache
php artisan queue:restart       # REQUIRED: workers reload the new code
```

> **Why `queue:restart` matters:** `queue:work` is a long-running daemon that
> holds your code in memory. Without a restart it keeps running the *old* code
> after a deploy. `queue:restart` signals workers to finish the current job and
> exit; Supervisor immediately respawns them on the new code.

---

## Prerequisites for SMS to actually send

1. `php artisan config:clear` (dev) or `config:cache` (prod) after editing `config/sms.php`.
2. SMS enabled in the admin **SMS Gateway** settings (super-admin master switch).
3. The specific message type toggled on (Birthday / Appointment Reminder).
4. A real provider (Termii) API key configured — keep the driver on `log`
   while testing (writes to `storage/logs/laravel.log`, sends nothing).

## Manual testing (no waiting for 06:30)

```bash
php artisan sms:send-birthday --dry-run
php artisan sms:send-appointment-reminders --dry-run
php artisan sms:send-appointment-reminders --dry-run --date=2026-09-17
```

Drop `--dry-run` to send for real. Broadcasts ("Send to all patients now" in the
UI) only process while the queue worker is running.