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

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):

{
  "status": "success",
  "messageId": "[email protected]"
}

Response (error):

{
  "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

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:

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:

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

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:

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:

kubectl -n api exec -it api-gateway-xyz -- \
  nc -zv $SMTP_HOST $SMTP_PORT

"authentication failed"

Wrong SMTP username/password. Verify credentials:

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
• Gotify Server Docs
• SMTP Configuration Best Practices