Netdata.cloud bot for Zulip
anil.recoil.org
1# Netdata Zulip Bot - Development Instructions
2
3This repository implements a Zulip bot that receives incoming webhook notifications from Netdata Cloud and posts the resulting notifications to a Zulip topic.
4
5## Core Requirements
6
7### Technology Stack
8- **Language**: Python with `uv` package manager
9- **Framework**: Python `zulip_bots` PyPI package for Zulip integration
10- **Web Server**: FastAPI for webhook endpoint
11- **Deployment**: Standalone service
12
13### Netdata Integration
14- **Webhook Format**: Follow the Netdata Cloud webhook notification format from:
15 - URL: `https://raw.githubusercontent.com/netdata/netdata/refs/heads/master/integrations/cloud-notifications/metadata.yaml`
16 - Section: `id: notify-cloud-webhook`
17- **Notification Types**: Handle both alert notifications and reachability notifications
18
19### Zulip Configuration
20- **Configuration Source**: The `.zuliprc` file should contain:
21 - Zulip site URL
22 - Bot email and API key
23 - Target stream/channel for posting messages
24- **Topic Organization**: Messages should be posted to topics based on severity:
25 - `critical`, `warning`, `clear` for alerts
26 - `reachability` for host status changes
27- **Message Format**: Rich markdown with:
28 - Alert details and timestamps
29 - Markdown-formatted alert URLs for easy access to Netdata Cloud
30
31### Security Requirements
32- **TLS/HTTPS**: The service must listen on HTTPS (not HTTP)
33- **Let's Encrypt**: Use Let's Encrypt to automatically issue SSL certificates for the public hostname
34- **Mutual TLS**: Netdata uses mutual TLS for authentication
35 - The server must validate Netdata's client certificate
36 - Support configuration of client CA certificate path
37
38### Service Architecture
39- **Standalone Service**: Run as an independent service
40- **Webhook Endpoint**: Expose `/webhook/netdata` for receiving notifications
41- **Health Check**: Provide `/health` endpoint for monitoring
42- **Structured Logging**: Use JSON-structured logs for production monitoring
43
44## Implementation Notes
45
46### Configuration Management
47- Support both `.zuliprc` file and environment variables
48- Provide sample configuration files with `--create-config` flag
49- Server configuration via environment variables:
50 - `SERVER_DOMAIN`: Public domain for Let's Encrypt
51 - `SERVER_PORT`: HTTPS port (default: 8443)
52 - `SERVER_ENABLE_MTLS`: Enable mutual TLS
53
54### Message Processing
551. Receive Netdata webhook POST request
562. Validate and parse JSON payload
573. Determine notification type (alert vs reachability)
584. Format message with appropriate emoji and markdown
595. Send to configured Zulip stream/topic
60
61### Error Handling
62- Validate all incoming payloads
63- Log errors without exposing internal details
64- Return appropriate HTTP status codes
65- Implement retry logic for Zulip API failures
66
67## Testing
68
69Run tests with:
70```bash
71uv run python -m pytest tests/ -v
72```
73
74## Deployment
75
76The service should be deployable via:
77- Systemd service (see `examples/netdata-zulip-bot.service`)
78- Docker container (see `Dockerfile` and `docker-compose.yml`)
79- Automated setup script (`scripts/setup.sh`)
80
81## Development Commands
82
83- **Install dependencies**: `uv sync`
84- **Create config samples**: `uv run netdata-zulip-bot --create-config`
85- **Run tests**: `uv run python -m pytest tests/`
86- **Start service**: `uv run netdata-zulip-bot`
87
88## Important Reminders
89
90- Always validate Netdata webhook payloads before processing
91- Ensure SSL certificates are properly configured before production deployment
92- Test mutual TLS authentication with actual Netdata Cloud webhooks
93- Monitor service logs for webhook processing errors
94- Keep Zulip API credentials secure and never commit them to the repository