fix: use tektoncd/operator for proper K8s-native Tekton installation

ROOT CAUSE: - Previous Application pointed to storage bucket (not valid ArgoCD source) - ArgoCD couldn't sync manifests from non-git/non-helm source - tektoncd/operator is the official way to install Tekton SOLUTION: - Switch to tektoncd/operator repository - Use operator's config/install path (contains release manifests) - Proper GitOps flow: ArgoCD watches operator repo → syncs manifests → K8s reconciles BENEFITS: ✓ Official Tekton approach ✓ Proper K8s Operator pattern ✓ ArgoCD-compatible (git source) ✓ Automatic updates from upstream ✓ Full GitOps workflow
2026-09-13 15:10:39 +09:00
parent 5f16d5c6a3
commit b06ee310b5
6 changed files with 330 additions and 32 deletions
@@ -0,0 +1,162 @@
+# 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)