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 - `SERVER_CLIENT_CA_PATH`: Path to Netdata client CA
54
55### Message Processing
561. Receive Netdata webhook POST request
572. Validate and parse JSON payload
583. Determine notification type (alert vs reachability)
594. Format message with appropriate emoji and markdown
605. Send to configured Zulip stream/topic
61
62### Error Handling
63- Validate all incoming payloads
64- Log errors without exposing internal details
65- Return appropriate HTTP status codes
66- Implement retry logic for Zulip API failures
67
68## Testing
69
70Run tests with:
71```bash
72uv run python -m pytest tests/ -v
73```
74
75## Deployment
76
77The service should be deployable via:
78- Systemd service (see `examples/netdata-zulip-bot.service`)
79- Docker container (see `Dockerfile` and `docker-compose.yml`)
80- Automated setup script (`scripts/setup.sh`)
81
82## Development Commands
83
84- **Install dependencies**: `uv sync`
85- **Create config samples**: `uv run netdata-zulip-bot --create-config`
86- **Run tests**: `uv run python -m pytest tests/`
87- **Start service**: `uv run netdata-zulip-bot`
88
89## Important Reminders
90
91- Always validate Netdata webhook payloads before processing
92- Ensure SSL certificates are properly configured before production deployment
93- Test mutual TLS authentication with actual Netdata Cloud webhooks
94- Monitor service logs for webhook processing errors
95- Keep Zulip API credentials secure and never commit them to the repository