homelab/project-usage/gotify-notifications.md

# Gotify Notifications Setup

## Overview

Gotify is a self-hosted push notification server deployed in the `notifications` namespace. The homelab-frontend gateway provides a `sendMsg` endpoint that accepts email and SMS notification requests and sends them directly via SMTP (SMS provider TBD).

## Architecture

```
App → X-Service: notification header
    → homelab-frontend gateway (api namespace)
    → notification/sendMsg handler
    → SMTP relay (email) or SMS provider (stubbed)
    → recipient email/SMS
```

**Not used:** Gotify's native message store is available for UI/push notifications, but the sendMsg flow bypasses it (direct send, no storage).

## Usage

### Send Email

```bash
curl -X POST https://api.riotpiao.com \
  -H 'X-Service: notification' \
  -H 'X-Resource: sendMsg' \
  -H 'Content-Type: application/json' \
  -d '{
    "format": "smtp",
    "title": "Alert",
    "message": "System CPU high",
    "priority": 5,
    "extras": {
      "to_email": "[email protected]",
      "cc": "[email protected]"
    }
  }'
```

**Response (success):**
```json
{
  "status": "success",
  "messageId": "[email protected]"
}
```

**Response (error):**
```json
{
  "status": "error",
  "error": "failed to send email: connection refused"
}
```

### Send SMS (Stubbed)

SMS support is stubbed. Currently returns "not implemented" error. To enable:

1. Choose SMS provider (Twilio, AWS SNS, Vonage, etc.)
2. Set `SMS_API_URL` and `SMS_API_KEY` environment vars in gateway Deployment
3. Implement provider integration in `internal/notification/handler.go` sendSMS() method

```bash
curl -X POST https://api.riotpiao.com \
  -H 'X-Service: notification' \
  -H 'X-Resource: sendMsg' \
  -H 'Content-Type: application/json' \
  -d '{
    "format": "sms",
    "message": "System CPU high",
    "extras": {
      "phone": "+12025551234"
    }
  }'
```

## Configuration

### SMTP Settings

Gateway reads SMTP config from environment variables (pulled from `smtp-credentials` Secret in `api` namespace):
- `SMTP_HOST` — SMTP server hostname
- `SMTP_PORT` — SMTP server port (587 TLS or 465 SSL)
- `SMTP_FROM` — Sender email address
- `SMTP_USER` — SMTP auth username
- `SMTP_PASS` — SMTP auth password

Secret is SOPS-encrypted in git. Create via:
```bash
kubectl create secret generic smtp-credentials \
  --from-literal=host=mail.riotpiao.com \
  --from-literal=port=587 \
  --from-literal=from=[email protected] \
  --from-literal=user=smtp-user \
  --from-literal=password=smtp-password \
  -n api \
  -o yaml | sops -e /dev/stdin > k8s/smtp-secrets.enc.yaml
```

Then add to `k8s/kustomization.yaml`:
```yaml
resources:
- smtp-secrets.enc.yaml
```

### Gotify Server

Gotify runs in `notifications` namespace with:
- PostgreSQL backend (CNPG)
- SMTP emailer sidecar (unused by sendMsg, but available for UI notifications)
- Health check on `:80/health`

Config: `k8s/apps/gotify/`

## Testing

```bash
cd homelab-frontend
bash examples/sendmsg-email.sh https://api.riotpiao.com
```

## Roadmap

- [ ] SMS provider integration (pick: Twilio/SNS/Vonage)
- [ ] Request rate limiting per source
- [ ] Message queuing for retries (via SQS if high volume expected)
- [ ] Audit logging (who sent what, to whom, when)
- [ ] Template support (subject + body with placeholders)

## Troubleshooting

### "SMTP_HOST not set"
Gateway env vars not loaded. Check:
```bash
kubectl -n api describe pod api-gateway-xyz
kubectl -n api logs api-gateway-xyz | grep SMTP
```

### "connection refused" on SMTP
SMTP server unreachable. Verify:
```bash
kubectl -n api exec -it api-gateway-xyz -- \
  nc -zv $SMTP_HOST $SMTP_PORT
```

### "authentication failed"
Wrong SMTP username/password. Verify credentials:
```bash
kubectl -n api get secret smtp-credentials -o yaml | grep password | base64 -d
```

### "X-Resource: sendMsg not found"
Notification handler not registered. Check `internal/server/router.go`:
- Verify `X-Service: notification` case exists
- Confirm `notification.NewHandler()` called in `NewRouter()`

## References

- [API Documentation](../homelab-frontend/API.md#notification-services)
- [Gotify Server Docs](https://gotify.net)
- [SMTP Configuration Best Practices](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol)