124 lines
4.1 KiB
Markdown
124 lines
4.1 KiB
Markdown
# Slack to ntfy Middleware
|
|
|
|
A lightweight Go service that acts as a middleware between Slack webhooks and ntfy servers, with Bearer token authentication and basic authentication support.
|
|
|
|
## Features
|
|
|
|
- ✅ Parses Slack webhook format
|
|
- ✅ Forwards alerts to self-hosted ntfy servers
|
|
- ✅ Bearer token authentication support
|
|
- ✅ Health check endpoint
|
|
- ✅ Lightweight Docker container (~8.4MB)
|
|
- ✅ High performance and low resource usage
|
|
|
|
## Quick Start
|
|
|
|
1. **Configure the service**:
|
|
```bash
|
|
# Edit docker-compose.yml and set:
|
|
# - NTFY_BASE_URL=https://your-ntfy-server.com
|
|
# - NTFY_TOKEN=tk_your_bearer_token
|
|
# OR
|
|
# - NTFY_USERNAME=your_username
|
|
# - NTFY_PASSWORD=your_password
|
|
```
|
|
|
|
2. **Run the service**:
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
3. **Configure Slack**:
|
|
- Go to Slack Integrations → Incoming Webhooks
|
|
- Add new webhook
|
|
- Webhook URL: `https://your-server-ip:8080/your-topic-name`
|
|
|
|
4. **Test the service**:
|
|
```bash
|
|
# Test webhook with HTTP (if TLS is disabled)
|
|
curl -X POST https://localhost:8080/test-topic \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"text": "Test alert from Slack to ntfy"}'
|
|
|
|
# Test webhook with HTTPS (if TLS is enabled, and if using self-signed certs, add -k or --insecure)
|
|
curl -k -X POST https://localhost:8080/test-topic -k \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"text": "Test alert from Slack to ntfy (TLS)"}'
|
|
|
|
# Check health with HTTP (if TLS is disabled)
|
|
curl http://localhost:8080/health
|
|
|
|
# Check health with HTTPS (if TLS is enabled, and if using self-signed certs, add -k or --insecure)
|
|
curl https://localhost:8080/health -k
|
|
```
|
|
|
|
## Configuration
|
|
|
|
| Environment Variable | Default | Description |
|
|
|---------------------|---------|-------------|
|
|
| `NTFY_BASE_URL` | `https://ntfy.sh` | Your ntfy server URL (without topic) |
|
|
| `NTFY_TOKEN` | `""` | Bearer token for ntfy authentication |
|
|
| `NTFY_USERNAME` | `""` | Username for ntfy basic authentication |
|
|
| `NTFY_PASSWORD` | `""` | Password for ntfy basic authentication |
|
|
| `BIND_ADDRESS` | `0.0.0.0` | Interface to bind to |
|
|
| `BIND_PORT` | `8080` | Port to listen on |
|
|
| `TLS_CERT_FILE` | `""` | Path to TLS certificate file (e.g., `/app/certs/server.crt`) |
|
|
| `TLS_KEY_FILE` | `""` | Path to TLS private key file (e.g., `/app/certs/server.key`) |
|
|
|
|
### Enabling TLS
|
|
|
|
TLS is enabled by default. If `TLS_CERT_FILE` and `TLS_KEY_FILE` environment variables are not set, a self-signed certificate and key will be automatically generated on startup.
|
|
|
|
**To provide your own certificate and key files (optional)**:
|
|
|
|
1. **Create a `certs` directory** in the root of your project:
|
|
```bash
|
|
mkdir certs
|
|
# Copy your server.crt and server.key into the certs/ directory
|
|
```
|
|
2. **Uncomment and set `TLS_CERT_FILE` and `TLS_KEY_FILE`** in your `docker-compose.yml` (e.g., pointing to `/app/certs/server.crt` and `/app/certs/server.key`):
|
|
```yaml
|
|
environment:
|
|
# ... existing environment variables ...
|
|
- TLS_CERT_FILE=/app/certs/server.crt
|
|
- TLS_KEY_FILE=/app/certs/server.key
|
|
```
|
|
3. Ensure the `volumes` section is uncommented and correctly mounts the `certs` directory:
|
|
```yaml
|
|
volumes:
|
|
- ./certs:/app/certs
|
|
```
|
|
|
|
**Important:** Regardless of whether you use generated or custom certificates:
|
|
|
|
* **Update your Slack webhook URL** to use `https`.
|
|
* **Restart your Docker service**:
|
|
```bash
|
|
docker compose down
|
|
docker compose up -d
|
|
```
|
|
* When testing with `curl` against a self-signed certificate, you may need to add the `-k` or `--insecure` flag to bypass certificate validation.
|
|
* **Exposing on standard HTTPS port (443) in production**: While the service runs on port 8080 internally, it's common to map it to port 443 externally (e.g., `- "443:8080"` in `docker-compose.yml`) or use a reverse proxy to handle TLS termination on port 443 and forward traffic to the container's port 8080.
|
|
|
|
## Development
|
|
|
|
### Build locally
|
|
```bash
|
|
make build
|
|
make run
|
|
```
|
|
|
|
### Build Docker image
|
|
```bash
|
|
make docker-build
|
|
```
|
|
|
|
### Run tests
|
|
```bash
|
|
make test
|
|
```
|
|
|
|
## License
|
|
|
|
MIT License
|