Uptime - Website Monitoring with Cloudflare Workers

Uptime is a lightweight, serverless monitoring tool built on Cloudflare Workers to keep track of your websites' availability. It monitors a configurable list of websites and sends Telegram alerts when issues arise—keeping you informed of your services' status at all times.

Table of Contents

• Features
• How It Works
• Tech Stack
• Getting Started
  • Prerequisites
  • Environment Setup
  • Installation
  • Manual Deployment
  • Automatic Deployment from GitHub
  • Local Development
• Usage
  • Example Telegram message
• Contributing
• License

Features

• 🔍 Active Monitoring: Periodically checks the availability of configured websites.
• ⚡ Serverless: Runs on Cloudflare Workers with minimal latency and no infrastructure overhead.
• 🔔 Instant Alerts: Sends alerts via Telegram when a monitor fails or recovers.
• 🔐 Zero Trust Support: Works with sites behind Cloudflare Zero Trust via client credentials.

How It Works

1. Configure a list of websites to monitor in the project settings.
2. Uptime periodically checks the availability of each website.
3. If at least one website monitor fails, a notification is sent via Telegram.
4. No further failure notifications are sent for the same incident to avoid spam.
5. Once all monitors report a healthy status, a recovery message is sent via Telegram.

Tech Stack

• Cloudflare Workers
• Workers KV
• Wrangler for development and deployment
• TypeScript
• Telegram Bot API
• GitHub Actions (optional deployment)

Getting Started

Prerequisites

• A Cloudflare account
• A Telegram bot and a chat for notifications

Environment Setup

1. Create a KV namespace for storing monitor states:

   cd packages/uptime-worker/
   npx wrangler kv namespace uptime

   This will output a namespace ID, which you need to add to your wrangler.json file under the kv_namespaces section:

   {
     "kv_namespaces": [
       {
         "binding": "uptime",
         "id": "<your-namespace-id>"
       }
     ]
   }

2. Add the Telegram secrets to your Cloudflare Workers environment variables:

   cd packages/uptime-worker/
   npx wrangler secret put TELEGRAM_BOT_TOKEN
   npx wrangler secret put TELEGRAM_CHAT_ID

3. Optionally, set up Cloudflare Zero Trust if your websites are protected by it.

   cd packages/uptime-worker/
   npx wrangler secret put CF_ACCESS_CLIENT_ID
   npx wrangler secret put CF_ACCESS_CLIENT_SECRET

Installation

1. Clone or download the Uptime repository.
2. Install the required dependencies:

   npm install

3. Generate the Cloudflare type definitions:

   npm run cf-typegen

4. Configure your list of websites to monitor in the configuration file. Example:

   export default {
     monitors: [
       {
         name: "Example Site",
         target: "https://example.com",
         statusPageLink: "https://status.example.com", // Optional: Link to a status page, defaults to the target URL
         expectedCodes: [200], // Optional: Expected HTTP status codes, defaults to [200]
         timeout: 5000, // Optional: Request timeout in milliseconds, defaults to 5000 ms
         protectedByZeroTrust: false, // Optional: Set to true if the site is protected by Cloudflare Zero Trust
         headers: {}, // Optional: Additional headers to send with the request
         body: undefined, // Optional: Body to send with the request (for POST or PUT requests)
       },
       // Add more monitors as needed
     ],
   };

5. Deploy the project to Cloudflare Workers:

   npm run deploy

Manual Deployment

Deploy Uptime to Cloudflare Workers using the following command:

npm run deploy

Automatic Deployment from GitHub

To enable automatic deployments from GitHub Actions, you'll need to set up a Cloudflare API token:

1. Generate a Cloudflare API token by following the instructions at: https://developers.cloudflare.com/fundamentals/api/get-started/create-token/
2. Add the token as a GitHub repository secret:
   • Go to your GitHub repository
   • Navigate to Settings > Secrets and variables > Actions
   • Click New repository secret
   • Name: CLOUDFLARE_API_TOKEN
   • Value: Your generated Cloudflare API token
3. The GitHub Actions workflow will automatically deploy your changes when you push to the main branch.

Local Development

1. Install dependencies:

   npm install

2. Create a .dev.vars file in the packages/uptime-worker/ directory with the following content:

   CF_ACCESS_CLIENT_ID=<value>
   CF_ACCESS_CLIENT_SECRET=<value>
   TELEGRAM_BOT_TOKEN=<value>
   TELEGRAM_CHAT_ID=<value>
   

3. Start the development server:

   npm run dev

4. Test the worker locally by calling the scheduled endpoint. This simulates a scheduled CRON event locally using the __scheduled endpoint.

   curl "http://localhost:8787/__scheduled?cron=*+*+*+*+*"

Usage

Once deployed, Uptime will automatically start monitoring the configured websites and send notifications to Telegram based on the status of the monitors.

Example Telegram message

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests to improve Uptime. Before submitting a PR, please run:

npm run lint

License

This project is licensed under the MIT License. See the LICENSE file for details.

---