Uptime - Scheduled Uptime Monitoring on Cloudflare Workers

Uptime is a lightweight, serverless monitoring service built on Cloudflare Workers. It runs on a cron schedule, performs a configurable list of health checks, stores the latest state in Workers KV, and sends Telegram alerts on downtime and recovery. Optionally, it can sync component status to Statuspage.io.

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 targets.
• Serverless: Runs on Cloudflare Workers with minimal infrastructure overhead.
• Telegram Alerts: Sends notifications that dynamically update to accurately reflect the current state of all checks.
• Statuspage Sync (Optional): Maps each check to a Statuspage component and updates its status.
• Zero Trust Support: Works with sites behind Cloudflare Zero Trust via client credentials.

How It Works

1. Configure a list of checks in uptime.config.ts.
2. A scheduled Cloudflare Worker runs on a cron defined in packages/uptime-worker/wrangler.jsonc.
3. Each check is performed; results are stored in Workers KV (state + last-checked timestamp).
4. If any check fails, a Telegram alert is sent and subsequently updated to accurately reflect the state of all checks until full recovery.
5. If Statuspage.io credentials are configured, each check is synced to a Statuspage component.

Tech Stack

• Cloudflare Workers
• Workers KV
• Wrangler for development and deployment
• TypeScript
• Telegram Bot API (via grammy)
• LiquidJS for template parsing
• Statuspage API (optional)
• GitHub Actions (optional deployment)

Getting Started

Quick Start

1. Clone the repository:

   git clone https://github.com/hobroker/uptime.git
   cd uptime

2. Run the interactive setup:

   npm install
   npm run setup

   This script will help you:

   • Login to Cloudflare.
   • Create the required KV namespace and update your configuration.
   • Set up your Telegram and optional Statuspage secrets.
   • Prepare your local environment.

3. Configure your monitors: Edit packages/uptime-worker/uptime.config.ts. Here's a basic example:

   export const uptimeWorkerConfig: UptimeWorkerConfig = {
     checks: [
       {
         name: "My Website",
         target: "https://example.com",
         retryCount: 2,
       },
       {
         name: "API Health",
         target: "https://api.example.com/health",
         method: "GET",
         expectedCodes: [200],
       },
     ],
   };

4. Deploy:

   npm run deploy

Prerequisites

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

Manual Setup (Optional)

If you prefer to set up everything manually, follow these steps:

1. KV Namespace: Create a KV namespace named uptime and add its ID to packages/uptime-worker/wrangler.jsonc.
2. Secrets: Use npx wrangler secret put for TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID, and other optional credentials.
3. Local Vars: Copy packages/uptime-worker/.dev.vars.example to packages/uptime-worker/.dev.vars and fill in the values.

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. Setup environment: Run the interactive setup to automatically create your .dev.vars file and generate types:

   npm run setup

3. Start development server:

   npm run dev

4. Test the worker locally: Uptime uses Cloudflare Cron Triggers. You can simulate a cron event locally by calling the /__scheduled endpoint:

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

Usage

Once deployed, Uptime will automatically run on the configured cron schedule, perform the checks in uptime.config.ts, and send Telegram notifications based on state changes.

Example Telegram message

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Development Workflow

1. Check types: npm run ts-check
2. Lint: npm run lint
3. Format: npm run format
4. Test: npm run test

Before submitting a PR, please ensure all the above checks pass. We use Turbo to manage the monorepo, so these commands will run across all packages.

License

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

---