Local Development Setup

Relevant source files

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

• README.md
• package.json
• AGENTS.md
• src/services/central-alerts/v1/db/init.sql
• src/services/versions/v1/index.ts

The FOSSBilling API Worker is a lightweight service built on the Hono framework, designed to handle versioning, system-wide alerts, and statistics for FOSSBilling instances. While deployed to Cloudflare Workers, the architecture remains platform-agnostic by separating core application logic from the platform layer.

This setup guide details the requirements and procedures for establishing a local development environment. It covers dependency management, storage initialization for Cloudflare D1 and KV namespaces, and the configuration of environment variables necessary for GitHub API integration.

Sources: README.md:3-12, AGENTS.md:6-10

Prerequisites and Installation

The project uses npm for dependency management. Before starting, developers must install the necessary packages defined in package.json.

npm install

Sources: README.md:73-77, package.json:5-18

Core Development Commands

Command	Description
npm run dev	Starts the local Cloudflare Workers development server (Wrangler).
npm run init:db	Initializes the local D1 database for central alerts.
npm run typecheck	Runs TypeScript compiler to verify types without emitting files.
npm run lint	Checks the codebase for style and programmatic errors.
npm run format	Automatically formats the code using Prettier.

Sources: package.json:5-18, AGENTS.md:14-25

Environment Configuration

Local development requires specific secrets and environment variables to interact with the GitHub API and secure the update endpoints. These are managed through a .dev.vars file and local KV storage.

Secrets and Tokens

Developers must create a .dev.vars file in the root directory to store the GITHUB_TOKEN. This should be a GitHub Personal Access Token (classic) with read access to public repositories.

Sources: README.md:81-85, AGENTS.md:39-43

Storage Initialization

The API relies on three primary storage components that must be initialized locally:

1. D1 Database (DB_CENTRAL_ALERTS): Stores the alert messages.
2. KV Namespace (CACHE_KV): Caches GitHub API responses.
3. KV Namespace (AUTH_KV): Stores the UPDATE_TOKEN used for the /versions/v1/update endpoint.

Sources: README.md:58-66, src/services/versions/v1/index.ts:133-140

Initializing the Database

To set up the schema for central alerts, run the initialization script. This creates the central_alerts table and indexes.

npm run init:db

The following diagram illustrates the local initialization flow:

Database Schema (D1)

The local D1 instance replicates the production schema for the central_alerts table.

Field	Type	Description
id	TEXT	Primary Key
title	TEXT	Alert title
type	TEXT	One of: success, info, warning, danger
min_fossbilling_version	TEXT	Lower bound of version range
max_fossbilling_version	TEXT	Upper bound of version range
buttons	JSON	Action buttons (array of text/link objects)
datetime	TEXT	Alert timestamp

Sources: src/services/central-alerts/v1/db/init.sql:4-21

Development Workflow

Once the environment is configured, the local development server can be started using npm run dev. This utilizes Wrangler to simulate the Cloudflare Workers environment.

Local Authentication Setup

For testing the protected update routes, you must manually inject a token into your local KV store:

npx wrangler kv:key put --binding AUTH_KV UPDATE_TOKEN "dev-secret" --local

Request Flow

The following sequence diagram represents how a local request for version data is handled:

Testing

The project uses Vitest for testing. Developers are encouraged to run the full suite before submitting changes to ensure both the Worker and Node-compatible logic remain functional.

• npm run test: Runs the default Vitest suite in the Workers pool.
• npm run test:node: Runs Node adapter tests.
• npm run test:all: Executes both suites for full coverage.

Sources: package.json:14-16, AGENTS.md:32-34

The local development setup ensures that all critical API components—Versions, Central Alerts, and Stats—can be developed and verified in an environment that closely mimics production Cloudflare Workers while maintaining developer efficiency through local mocks and CLI tools.