Deploying to Cloudflare

Relevant source files

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

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

StatusBeam is designed as an open-source, CDN-native status page generator that runs entirely on Cloudflare's edge platform. The deployment utilizes several Cloudflare primitives, including Workers, D1 (SQLite database), KV (Key-Value store), and Workers Cache. Unlike traditional fork-based status pages, StatusBeam is deployed as a package where the user's repository contains only configuration, and the application logic is a versioned dependency.

The system consists of two primary Workers: a check Worker that probes services via a cron trigger and writes results to D1 and KV, and a status page Worker built with Astro SSR that renders the snapshot at the edge.
Sources: DEPLOYMENT.md:7-14, ARCHITECTURE.md:10-18

Deployment Architecture

StatusBeam's deployment architecture is split into three independent layers that reside on Cloudflare to ensure the status page remains resilient even if the monitored services fail.

The diagram shows the interaction between Cloudflare Workers and storage primitives.
Sources: README.md:46-77, ARCHITECTURE.md:27-41

Provisioning and Setup

Deployment typically begins with the statusbeam setup command. This process is idempotent and handles the creation of necessary Cloudflare resources.

Automated Provisioning Steps

1. Authentication Check: Verifies Cloudflare credentials via wrangler login or CLOUDFLARE_API_TOKEN.
2. D1 Provisioning: Creates or identifies a D1 database (default name: statusbeam) to store time-series uptime data and incident history.
3. KV Provisioning: Creates or identifies a KV namespace (named STATUS_KV) used for storing the current status snapshot and configuration.
4. Configuration Injection: Prompts for a custom domain and cron schedule, then writes these resource IDs into wrangler.worker.jsonc and wrangler.web.jsonc.
   Sources: scripts/setup.sh:84-142, packages/cli/src/commands/setup.ts:36-82

Deployment Configuration Options

Option	Description	Source File
database_id	Unique UUID for the Cloudflare D1 database.	scripts/setup.sh:124
kv_namespaces.id	Unique ID for the Cloudflare KV store.	scripts/setup.sh:136
cron	Schedule for service probes (default: */5 * * * *).	scripts/setup.sh:146
custom_domain	Optional hostname for the status page.	DEPLOYMENT.md:65

Core Deployment Pipeline

Once provisioned, the statusbeam deploy command executes the sequence required to make the status page live.

Execution Sequence

1. D1 Schema Application: Executes wrangler d1 execute to apply schema.sql, defining tables for checks, incidents, and incident_updates.
2. Config Upload: Uploads the local status.config.yml file to the KV namespace under the config key.
3. Worker Deployment: Deploys the check Worker to handle cron-based probes.
4. Astro Build & Deploy: Builds the Astro frontend. The build process uses the STATUSBEAM_WRANGLER_CONFIG environment variable to fuse user-specific resource IDs into the deployment artifact.
   Sources: packages/cli/src/commands/deploy.ts:41-61, ARCHITECTURE.md:52-54

The sequence of operations performed during a standard deployment.
Sources: packages/cli/src/commands/deploy.ts:38-63

Continuous Integration (CI)

StatusBeam supports deployment via GitHub Actions. The scaffolded project includes a .github/workflows/deploy.yml that runs statusbeam deploy on every push to the main branch.

Required CI Secrets

• CLOUDFLARE_API_TOKEN: Requires "Edit Cloudflare Workers" permissions (Workers Scripts, D1, KV Edit).
• CLOUDFLARE_ACCOUNT_ID: The target Cloudflare account ID.
  Sources: DEPLOYMENT.md:43-58

Note: A User API token is required for D1 schema execution, as account-owned tokens lack the necessary User -> Memberships -> Read permission required by wrangler d1 execute --remote.
Sources: DEPLOYMENT.md:53-58

Cache Invalidation and Networking

To achieve near-instant status updates, StatusBeam uses Cloudflare's "Purge by Tag" feature.

Instant Cache Invalidation

When a status change is detected, the check Worker purges the edge cache by tag. This requires setting two specific secrets on the check Worker:

• CF_API_TOKEN: Token with "Cache Purge" permission.
• CF_ZONE_ID: The ID of the zone serving the status page.
  Sources: DEPLOYMENT.md:126-132, README.md:204-213

Custom Domains

If a custom domain is specified during setup, StatusBeam configures the routes in wrangler.web.jsonc. Cloudflare automatically provisions proxied DNS records and edge certificates if the zone is managed within the same account.
Sources: DEPLOYMENT.md:65-72

Conclusion

Deploying StatusBeam to Cloudflare provides a serverless, resilient infrastructure for monitoring. By leveraging D1 and KV for storage and Workers for both execution and rendering, the system eliminates external dependencies and client-side rate limits. The package-based deployment model ensures that updates are handled through the CLI, keeping the user's specific configuration separate from the core application logic.
Sources: README.md:23-41, ARCHITECTURE.md:139-141