alertmanager-ntfy/README.md

# 🚨 alertmanager-ntfy 🚨

This project is a lightweight bridge between [Prometheus Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) and [ntfy](https://ntfy.sh/). It sends push notifications to your devices.

## 📦 Features

- Configure via environment variables.
- Exports Prometheus metrics to monitor webhook activity.
- Built for Kubernetes, but works anywhere
- Has a `flake.nix`

## 🚀 Getting Started

To send your Alertmanager alerts to ntfy, configure the following environment variables:

| Variable          | Description                                  | Example           |
|-------------------|----------------------------------------------|-------------------|
| `HTTP_ADDRESS`    | Address to listen on                         | `localhost`       |
| `HTTP_PORT`       | Port to listen on                            | `8080`            |
| `NTFY_SERVER_URL` | ntfy server to send alerts to                | `https://ntfy.sh` |
| `NTFY_USER`       | Username for basic auth (optional)           | `myuser`          |
| `NTFY_PASS`       | Password for basic auth (optional)           | `supersecret`     |
| `LOG_LEVEL`       | Log level (`debug`, `info`, `warn`, `error`) | `info`            |

### Example

To expose the service on `localhost:8080` and send alerts to an ntfy topic `https://ntfy.sh/mytopic`:

```bash
export HTTP_ADDRESS="localhost"
export HTTP_PORT="8080"
export NTFY_SERVER_URL="https://ntfy.sh/mytopic"
export NTFY_USER="myuser"
export NTFY_PASS="supersecret"
export LOG_LEVEL="info"
```

## 🛠️ Nix Support

For Nix/NixOS users, a `flake.nix` is provided for build, run and test.

### Building with Nix

To build the container image: `nix build .#container`

If you are not on amd64 use `nix build .#packages.x86_64-linux.container`.

Push the built container to your preferred registry: `nix run .#push-container`

You can run the application directly from Nix with: `nix run`

To simulate alerts with test data: `nix run '.#mock-hook'`

## 🖥️ Nix Module

A Nix module is provided for easy setup and integration. A minimal configuration would look like this:

```nix
# Add to flake inputs
inputs.alertmanager-ntfy.url = "git+https://code.252.no/tommy/alertmanager-ntfy";

# Import the module in your configuration.nix
imports = [
  self.inputs.alertmanager-ntfy.nixosModules.default
];

# Enable the service and configure options
services.alertmanager-ntfy = {
  enable = true;
  httpAddress = "localhost";
  httpPort = "9999";
  ntfyTopic = "https://ntfy.sh/test";
  ntfyPriority = "high";
  envFile = "/var/src/secrets/alertmanager-ntfy/envfile";
};
```

## 🔍 Prometheus Metrics

The service exports Prometheus metrics for tracking webhook requests and errors. By default, these metrics are exposed at `/metrics`:

- **`http_requests_total`**: Total number of HTTP requests received.
- **`http_request_errors_total`**: Total number of errors encountered during request processing.


## 🤩 Gratitude

This project is based on the fantastic work by [pinpox/alertmanager-ntfy](https://github.com/pinpox/alertmanager-ntfy), with adaptations for Kubernetes deployments and enhanced logging/metrics support.