# Quick Start Cheat Sheet
## The 3 files you edit
| File | What to change |
|---|---|
| `php/config.php` | DB password, `ingest_token`, `dashboard_token`, `allowed_origins`, `alert_to` |
| `dashboard/dashboard.js` | `queryBase` URL + `dashboardToken` (top of file) |
| `deploy/nginx-monitor.conf` | Your real domain name, PHP-FPM socket path |
## The 2 tokens you generate
```bash
openssl rand -hex 32 # → paste into INGEST_TOKEN
openssl rand -hex 32 # → paste into DASHBOARD_TOKEN
```
Same tokens go in both `config.php` and `dashboard.js` (for the dashboard one).
## The 2 cron jobs you install
```cron
* * * * * /usr/bin/php /var/www/monitoring/php/cron/alert_engine.php >> /var/log/monitoring-alerts.log 2>&1
0 3 * * 0 /usr/bin/php /var/www/monitoring/php/cron/retention.php >> /var/log/monitoring-retention.log 2>&1
```
## How to add a new system
1. Add it to DB:
```sql
INSERT INTO systems (name) VALUES ('new_system');
```
2. For PHP APIs — top of `index.php`:
```php
require_once '/var/www/monitoring/php/bootstrap.php';
monitor_bootstrap('new_system');
```
3. For web/mobile — in ``:
```html
```
## Verification ping (run after deploying)
```bash
curl -X POST https://monitor.yourdomain.com/api/ingest.php \
-H "X-Ingest-Token: YOUR_INGEST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"metric","system_name":"jobcard_api","endpoint":"/ping","method":"GET","response_time":10,"status_code":200}'
```
Expect `{"ok":true}`. Then open the dashboard — you should see the ping within 2 seconds.
## Common gotchas
| Symptom | Fix |
|---|---|
| Dashboard red dot, console 401 | Token in `dashboard.js` doesn't match `config.php` |
| Browser console: CORS error | That domain isn't in `allowed_origins` |
| No data from PHP APIs | Wrong path in `require_once` in your `index.php` |
| Alert emails not arriving | Use `alert_engine_phpmailer.php` instead (see below) |
| "unauthorized" from curl test | Wrong token, or spaces around header value |
## Want reliable email alerts?
PHP's built-in `mail()` usually lands in spam. Switch to PHPMailer:
```bash
cd /var/www/monitoring
sudo -u www-data composer require phpmailer/phpmailer
```
Add SMTP settings to `config.php`:
```php
'smtp_host' => 'smtp.yourprovider.com',
'smtp_port' => 587,
'smtp_secure' => 'tls',
'smtp_user' => 'alerts@yourdomain.com',
'smtp_pass' => 'your-smtp-password',
```
Change the cron line to use `alert_engine_phpmailer.php` instead.
## Files reference
```
php/
├── config.php ← EDIT
├── Monitor.php ← do not edit (the logger class)
├── bootstrap.php ← do not edit
├── api/
│ ├── ingest.php ← public ingest endpoint
│ └── query.php ← dashboard read API
└── cron/
├── alert_engine.php ← runs every minute (mail())
├── alert_engine_phpmailer.php ← runs every minute (SMTP)
└── retention.php ← runs weekly
dashboard/
├── index.html
├── dashboard.css
├── dashboard.js ← EDIT (CONFIG block at top)
└── monitor-client.js ← copied from client-sdk/
client-sdk/
└── monitor-client.js ← the JS SDK for web/mobile apps
deploy/
└── nginx-monitor.conf ← EDIT (domain + socket)
```