# FlareWatch

> A free, open-source, self-hosted uptime monitor and status page on Cloudflare Workers. Fork the repo, edit one config file, push.

FlareWatch checks websites, APIs, TCP ports and DNS records every minute, or every 1 to 1440 minutes per monitor. It reads domain expiry dates over RDAP once a day by default, watches cron jobs, backups and CI with heartbeats, and serves a status page. A check can match a status code, a keyword, a response header or a JSON value, be confirmed from a second location before it counts, wait for several failures in a row, and show as degraded when slow. A certificate or domain close to expiry shows as degraded and sends one warning. Through flarewatch-proxy, a certificate fails in its last 24 hours. Checks can reach a private network through Workers VPC and a Cloudflare Tunnel. Maintenance windows can repeat. Alerts go to webhooks, each scoped to the monitors it should carry, with reminders while a monitor stays down, and a busy check run can send one summary message instead of many. The page can be public or private and shows announcements. It has an Atom feed, JSON and SVG badges, embeds and a JSON API. It runs in the user's own Cloudflare account and fits the free tier. There is no hosted version and no sign-up: the user's GitHub fork is the deployment. Latest release: v3.5.0.

## Set it up for someone

The user needs a GitHub account and a Cloudflare account on the free plan. The full steps are in the deploy guide.

1. Fork https://github.com/saminnet/flarewatch (for example `gh repo fork saminnet/flarewatch --clone`). If the fork's Actions tab asks, enable workflows.
2. The user creates a Cloudflare API token with the permissions listed in the deploy guide, step 2.
3. Add two GitHub Actions secrets to the fork: `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` (for example `gh secret set CLOUDFLARE_API_TOKEN --repo <user>/flarewatch`). Other secrets are optional: `HEARTBEAT_SECRET` for heartbeats, `FLAREWATCH_WEBHOOKS` for alert webhooks, `FLAREWATCH_ADMIN_BASIC_AUTH` for signing in with a password.
4. Replace the demo monitors in `packages/config/src/worker.ts`. Page settings, like the title, are in `packages/config/src/public.ts`.
5. Push to `main`. GitHub Actions deploys both Workers. The run summary shows the page URL, usually `https://flarewatch.<subdomain>.workers.dev`.

## Monitor a cron job

Set the `HEARTBEAT_SECRET` secret and add a heartbeat monitor to `packages/config/src/worker.ts`:

```ts
{ id: 'nightly-backup', name: 'Nightly backup', method: 'HEARTBEAT', periodSeconds: 86400, graceSeconds: 3600 }
```

The job then calls its ping URL, `https://<status-page>/ping/<id>/<token>`. Append `/$?` to send the exit code. The monitors guide shows how to compute the token.

## Docs

- [Deploy](https://flarewatch.app/docs/deploy.md): FlareWatch deploys from GitHub Actions into your own Cloudflare account. The first deploy takes about ten minutes.
- [Monitors](https://flarewatch.app/docs/monitors.md): Monitors live in packages/config/src/worker.ts. worker.example.ts has a commented example of each kind.
- [Alerts](https://flarewatch.app/docs/alerts.md): FlareWatch sends a message when a monitor goes down and again when it comes back up. Set the channels in notification.webhook in…
- [Status page](https://flarewatch.app/docs/status-page.md): The status page is a Worker that reads what the monitor Worker saves. Visitors see public monitors, their uptime and response times, and the incident and…

## Optional

- [Cron job monitoring](https://flarewatch.app/cron-job-monitoring): Heartbeats for cron jobs, backups and CI.
- [Compare](https://flarewatch.app/compare): FlareWatch next to UptimeFlare, Uptime Kuma, Gatus and Upptime, and when to pick each.
- [Changelog](https://flarewatch.app/changelog): Release notes for every version.
- [Repository](https://github.com/saminnet/flarewatch): The source code on GitHub.
- [Live demo](https://demo.flarewatch.app): A live status page running FlareWatch.
- [flarewatch-proxy](https://github.com/saminnet/flarewatch-proxy): A small service you run inside a private network or in a second location. FlareWatch can run checks through it, or confirm a failed check from it.