kogutdocs

    Type to search page titles, headings and text.

    When kogut itself is down

    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:

      openssl rand -hex 32

    2. Deploy the Worker:

      Deploy to Cloudflare

      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:

      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:

    [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.

    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.

    ResponseAction
    401Make KOGUT_EDGE_TOKEN match the token in kogut
    500, missing or invalid NOTIFY_URLSet a valid ntfy or webhook URL in the Worker
    500, invalid TIMEZONEUse an IANA timezone or leave it empty for UTC
    404Check 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.