# kogut edge

An external watchdog on Cloudflare Workers.

kogut edge is a Cloudflare Worker that alerts you when kogut stops sending heartbeats:
an outage message after two minutes of silence, and a recovery message when heartbeats
return. It runs on the free Workers plan. It does not run checks or serve a status page.

## Deploy the Worker

1. Generate a shared token:

   ```sh
   openssl rand -hex 32
   ```

2. Deploy the Worker:

   [![Deploy to Cloudflare](../../assets/deploy/cloudflare.svg)](https://deploy.workers.cloudflare.com/?url=https://github.com/piotrkowski/kogut/tree/main/packages/edge)

   Set `KOGUT_EDGE_TOKEN` to the shared token and `NOTIFY_URL` to an ntfy topic or
   webhook URL. The Worker sends plain-text `POST` messages, with `Priority: high` on
   outage alerts.

   Or deploy from a clone:

   ```sh
   cd packages/edge
   npx wrangler deploy
   npx wrangler secret put KOGUT_EDGE_TOKEN
   npx wrangler secret put NOTIFY_URL
   ```

3. Optional: set `SERVER_NAME` for messages and `TIMEZONE`, an IANA timezone such as
   `Europe/Warsaw`, for local times.

## Connect kogut

1. Open **Settings → Watching kogut** and click **Set up** beside **kogut edge**.
2. Enter the Worker's URL and the shared token. For a Worker under a path, include the
   path, such as `https://example.com/kogut-edge`.
3. Save and check the delivery status. Watching starts with the first heartbeat.

In `kogut.toml`:

```toml
[edge]
url = "https://kogut-edge.acme.workers.dev"
token = "${KOGUT_EDGE_TOKEN}"
```

File settings take precedence and make the panel fields read-only. A token saved in the
panel is not shown again. See the [edge configuration reference](https://docs.kogut.dev/reference/configuration/#edge).

## Verify alerts

Stop kogut for more than two minutes and wait for the outage message, then start it and
wait for recovery. Planned downtime alerts too.

kogut sends a heartbeat every 30 seconds. Failed sends retry with backoff.

## Fix delivery failures

**Settings → Watching kogut** shows the last successful heartbeat or the failure.

| Response | Action |
|---|---|
| `401` | Make `KOGUT_EDGE_TOKEN` match the token in kogut |
| `500`, missing or invalid `NOTIFY_URL` | Set a valid ntfy or webhook URL in the Worker |
| `500`, invalid `TIMEZONE` | Use an IANA timezone or leave it empty for UTC |
| `404` | Check the Worker's URL and route |

If messages do not arrive, read the Cloudflare logs. The Worker retries outage messages
every minute and recovery messages on the next heartbeat.

## Update the Worker

Copy the newer `packages/edge/` into the repository the deploy button created; Cloudflare
deploys every push. From a clone, run `git pull`, then `npx wrangler deploy` in
`packages/edge/`.

Without Cloudflare, use a [heartbeat URL](https://docs.kogut.dev/high-availability/heartbeat-url/).