Quick Start Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• DEPLOYMENT.md
• ARCHITECTURE.md
• packages/create-statusbeam/src/index.ts
• packages/cli/src/commands/deploy.ts
• scripts/setup.sh

StatusBeam is an open-source, CDN-native status page generator designed to run entirely on Cloudflare's edge platform. It serves as a modern successor to projects like Upptime by utilizing Cloudflare Workers, D1 (SQL database), and KV (key-value store) to ensure high reliability, no client-side rate limits, and accurate scheduling.

This guide outlines the process of scaffolding a new StatusBeam project, provisioning the necessary Cloudflare infrastructure, and deploying the status page. StatusBeam is deployed as a versioned package rather than a fork, meaning users manage only their configuration while the core logic remains an external dependency.

Sources: README.md:1-25, ARCHITECTURE.md:10-25, DEPLOYMENT.md:5-15

Initial Project Scaffolding

The first step in using StatusBeam is to create a thin project repository that holds your specific configuration files (status.config.yml and wrangler configs).

1. Scaffold the Directory: Run the initializer to create the project structure.

   bunx create-statusbeam my-status
   cd my-status
   

2. Install Dependencies: Use bun to install the @statusbeam/cli and other requirements.

   mise trust && mise install && bun install
   

3. Cloudflare Authentication: Ensure you are logged into your Cloudflare account.

   bunx wrangler login
   

The create-statusbeam command generates a package.json pinned to a compatible CLI release, a default status.config.yml, and template wrangler.*.jsonc files.

Sources: DEPLOYMENT.md:18-35, packages/create-statusbeam/src/index.ts:110-135

Infrastructure Provisioning and Setup

The statusbeam setup command is an idempotent tool that automates the creation of Cloudflare resources. It performs the following actions:

• Provisions D1 & KV: Creates a D1 database named statusbeam for time-series history and a KV namespace STATUS_KV for configuration and status snapshots.
• Wrangler Configuration: Prompts the user for a custom domain and cron schedule, then writes these resource IDs and settings into wrangler.worker.jsonc and wrangler.web.jsonc.
• Schema Application: Executes the SQL schema against the D1 database to prepare tables for checks, incidents, and incident_updates.
• Initial Upload: Uploads the initial status.config.yml to the KV store.

Setup Workflow

The following sequence diagram illustrates the interactions between the CLI, the local environment, and Cloudflare during the setup phase.

The diagram shows the automated flow of resource provisioning and configuration application handled by the setup command.

Sources: scripts/setup.sh:84-160, DEPLOYMENT.md:37-45, packages/cli/src/commands/deploy.ts:38-55

Core Architecture and Data Flow

StatusBeam operates through three independent layers. Understanding these layers is critical for configuring the system correctly.

1. Check Layer (Worker): A Cloudflare Cron Worker (defaulting to every 5 minutes) that probes configured services, writes results to D1, and updates the KV snapshot.
2. Store Layer (D1/KV): D1 stores durable time-series history; KV stores the "current-status" snapshot and user configuration.
3. Display Layer (Web): An Astro site running at the edge that renders the status page using data from KV and D1. It emits Cache-Tag headers to allow instant invalidation.

System Data Flow

The flow of data from service monitoring to page rendering is visualized below.

The diagram illustrates how the Check Worker acts as the producer of data, while the Astro Web App acts as the consumer, both utilizing shared Cloudflare edge storage.

Sources: ARCHITECTURE.md:15-40, README.md:45-80

Configuration and Deployment

Configuration is centralized in status.config.yml. This file defines the sites to monitor and notification channels.

Feature	Description	File/Key
Monitored Sites	List of URLs, check types (http, statuspage, sentry), and thresholds.	sites
Notifications	Slack webhooks or generic webhooks for status changes.	notifications
Theme	Logo URL, dark mode preference, and fallback locale.	theme
Cron Schedule	How often the Check Worker probes services.	wrangler.worker.jsonc

Deployment Command

Once the configuration is updated locally, the deploy command synchronizes changes with Cloudflare:

bunx statusbeam deploy

This command performs a schema check, uploads the latest config to KV, and redeploys both the Worker and the Astro site.

Sources: README.md:165-200, DEPLOYMENT.md:52-65, packages/cli/src/commands/deploy.ts:50-70

CLI Command Reference

The statusbeam CLI provides several essential commands for managing the lifecycle of the status page.

Command	Purpose
setup	Provisions D1/KV, configures wrangler files, applies schema, and deploys.
deploy	Updates configuration in KV and redeploys the Worker and Web application.
update	Bumps the @statusbeam/* packages to the latest versions.

Sources: DEPLOYMENT.md:47-51, packages/create-statusbeam/src/index.ts:125-130

Conclusion

StatusBeam provides a resilient, edge-native infrastructure for monitoring services without the overhead of traditional servers or the rate-limiting risks of client-side status pages. By following the setup and deploy workflow, users can establish a production-ready status page on Cloudflare in minutes, while maintaining a clean separation between application logic and user configuration.

Sources: README.md:1-15, ARCHITECTURE.md:130-145