feat: documentation site

Docusaurus 3 docs-only site at docsite/, served statically by nginx under /docs on the marketing host. Covers getting started (self-hosted install through first server and first licence), the control plane, Vantage HQ, a reference section and operations. Wired into docker-compose.site.yml as docsite (3005:80) and into the image build workflow, rebuilding on its own directory only. Never added to the self-hosted compose file.
2026-07-28 15:46:33 +01:00
commit 11b1936bb2
44 changed files with 23669 additions and 0 deletions
@@ -0,0 +1,101 @@
+---
+id: notification-channels
+title: Notification channels
+sidebar_label: Notification channels
+---
+
+A channel is a destination for alerts. [Monitors](./monitors.md) reference
+channels by ID, so one destination serves as many monitors as you like.
+
+Manage them at **Settings → Notifications**.
+
+## Types
+
+### Webhook
+
+Posts JSON to a URL you choose.
+
+| Setting | |
+| --- | --- |
+| `url` | Required |
+
+```json
+{
+    "monitor": "API front door",
+    "type": "http",
+    "old_status": "up",
+    "new_status": "down",
+    "message": "HTTP 502",
+    "time": "2026-07-28T09:14:02Z"
+}
+```
+
+Any response of 300 or above counts as a delivery failure. The request times out
+after 10 seconds.
+
+### Discord
+
+| Setting | |
+| --- | --- |
+| `url` | Discord webhook URL |
+
+Posts the alert as message content.
+
+### Slack
+
+| Setting | |
+| --- | --- |
+| `url` | Slack incoming webhook URL |
+
+### Telegram
+
+| Setting | |
+| --- | --- |
+| `token` | Bot token |
+| `chat_id` | Target chat |
+
+### SMTP
+
+| Setting | |
+| --- | --- |
+| `host`, `port` | Required |
+| `from`, `to` | Required |
+| `username`, `password` | Optional; auth is skipped when the username is empty |
+
+Port `465` uses implicit TLS; anything else uses STARTTLS.
+
+Alert emails are rendered by the same email system that sends licence and
+account mail, so a monitor alert and an account email look like the same
+product.
+
+## The message
+
+Non-webhook channels all send the same one-line title:
+
+```
+[Vantage] API front door (http) is DOWN: HTTP 502
+```
+
+Recoveries read `recovered` in place of `is DOWN`. The webhook payload carries
+the same information as fields, which is the one to use if you are routing into
+something that needs to branch on status.
+
+## Testing
+
+Every channel has a **Test** button. It dispatches a fabricated down event for a
+monitor called "Test monitor", through the real delivery path — so a test that
+arrives proves the credentials, the network path and the destination, not just
+the configuration form.
+
+:::tip Test after every change
+Channel settings are only exercised when something breaks, which is the worst
+time to discover a stale webhook URL. Re-test after rotating a token.
+:::
+
+## Choosing destinations
+
+- Use a **chat channel** for awareness, and make sure someone owns it.
+- Use **SMTP** where a durable record matters.
+- Use a **webhook** to reach an on-call system that does escalation properly.
+  Vantage does not do escalation, rotas or acknowledgement; a webhook into
+  something that does is the intended answer.