# HeyStar-style Multi-Tenant Relay — Setup Guide

This replaces the single-school version. One deployment now serves
**any number of schools and devices**.

## Architecture

```
Many devices (any school) --TCP--> hf-tcp-gateway-service (Java, on a VPS you control)
                                              |
                                              | HTTP, single shared endpoint
                                              v
                                        webhook.php
                                   (looks up device -> school -> target URL)
                                              |
                                              v
                                Each school's own web app
```

## Important: this needs a VPS, not shared hosting

Shared hosting (like your current Hostinger plan) **cannot run the
Java gateway** — it needs a persistent process holding TCP ports open
24/7, which shared PHP hosting doesn't allow. You need a VPS (Hostinger,
DigitalOcean, or similar — anything giving you SSH/root access).

The PHP admin panel + webhook can technically stay on shared hosting,
but it's simpler to run everything on the same VPS.

## Setup order

1. **Provision a VPS** (Ubuntu is fine). Install Java 8+ and PHP + MySQL,
   or point PHP/MySQL at a separate host if you prefer.
2. **Run the gateway** on the VPS, same way as your Windows test —
   `java -jar hf-tcp-gateway-service_v1.4.3.jar` (or the equivalent
   startup command for the Linux build). Keep it running permanently —
   set it up as a systemd service so it survives reboots.
3. **Create the database**: `mysql -u root -p < schema.sql`
4. **Deploy the PHP files** (`config.php`, `webhook.php`, `admin/`,
   `includes/`) to your web server.
5. **Fill in `config.php`**: DB credentials, `GATEWAY_HTTP_HOST`/`PORT`
   (usually `127.0.0.1` if PHP and the gateway run on the same VPS),
   and `WEBHOOK_URL` — the public URL of `webhook.php`.
6. **Create your admin login**:
   ```
   php create_admin.php youradmin yourpassword
   ```
   Then delete `create_admin.php` from the server.
7. **Log into the admin panel** at `/admin/login.php`.
8. **Add Al-Amin as a school** — name, base URL
   (`https://alaminschoolapp.com`), and the API key/secret from their
   `heystar_sync` settings page.
9. **Add the FP07 device** — device key (`HF62A20240430000319`),
   device secret (set on the device itself), purpose (`attendance`),
   leave endpoint URL blank to use the default. Saving this
   automatically registers it with the gateway.
10. **Point the physical device** at this VPS's IP, port `10010` (on
    the device's own settings screen) — same as before, just a
    different server now.

## Adding more schools/devices later

All through the admin panel — no code changes, no redeployment. Add a
school, add its devices, done.

## Debugging

The **Event Log** page in the admin panel shows every scan received
and whether forwarding succeeded — this is your first stop if a
school reports missing attendance data.