Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:
The FOSSBilling API Worker is a lightweight, platform-agnostic service built on the Hono framework. While designed to be portable, its primary deployment target is Cloudflare Workers, leveraging Cloudflare's edge computing resources like D1 databases and KV (Key-Value) storage.
Sources: README.md:3-8
Prerequisites and Infrastructure
Before deployment, several infrastructure components must be provisioned. The application relies on Cloudflare-specific bindings for database persistence and high-performance caching.
Storage Components
The system requires three distinct storage bindings to function correctly:
- D1 Database (
DB_CENTRAL_ALERTS): Used for storing persistent alert messages for the Central Alerts service. - KV Namespace (
CACHE_KV): Used for caching GitHub API responses and statistics to prevent rate limiting and improve performance. - KV Namespace (
AUTH_KV): Used to store sensitive authentication tokens, specifically theUPDATE_TOKENrequired for administrative cache refreshes.
Sources: README.md:33-40, AGENTS.md:58-60
Environment Variables
The application requires a GITHUB_TOKEN (Personal Access Token) with public repository read access to fetch release metadata from GitHub.
Sources: README.md:44-46
Deployment Workflow
The deployment process involves building the application, initializing the database schema, and pushing the worker to the Cloudflare network using Wrangler.
The flow above illustrates the transition from local development to a live edge environment. Sources: package.json:6-19, AGENTS.md:15-25
Deployment Commands
| Command | Description |
|---|---|
npm install | Installs necessary dependencies including Hono, Octokit, and Wrangler. |
npm run init:db | Executes the D1 initialization script to set up the alerts table. |
npm run deploy | Minifies the source code and deploys the worker via wrangler deploy. |
wrangler secret put | Used to securely upload the GITHUB_TOKEN to the production environment. |
Sources: package.json:7-10, AGENTS.md:15-20, README.md:44-65
Authentication Configuration
Administrative endpoints, specifically /versions/v1/update, require Bearer Token authentication. This token must be manually provisioned in the AUTH_KV namespace of the deployment environment.
The sequence above shows the internal validation logic for secure administrative tasks. Sources: src/services/versions/v1/index.ts:133-145, src/services/versions/v1/README.md:10-12
Post-Deployment Validation
Once deployed, the service provides several endpoints to verify health and connectivity.
- Version Check: Access
GET /versions/v1to ensure the GitHub integration andCACHE_KVare working. - Alerts List: Access
GET /central-alerts/v1/listto verify D1 database connectivity. - Stats Verification: Access
GET /stats/v1/datato ensure release statistics are being aggregated and cached properly.
Sources: README.md:14-25, AGENTS.md:65-75
Troubleshooting Common Errors
| Error Code | Meaning | Probable Cause |
|---|---|---|
500 | Internal Server Error | UPDATE_TOKEN or GITHUB_TOKEN is missing from environment bindings. |
503 | Service Unavailable | GitHub API is down/rate-limited and no cache is available in CACHE_KV. |
401 | Unauthorized | Bearer token missing or incorrect for /update endpoint. |
Sources: src/services/versions/v1/index.ts:101-115, src/services/versions/v1/README.md:73-85
Summary
Deploying the FOSSBilling API requires a Cloudflare environment with D1 and KV bindings properly configured. The process is streamlined via Wrangler, and security is maintained through secret management and Bearer authentication for sensitive operations. Following successful deployment, the API acts as a high-performance, cached gateway between FOSSBilling instances and the central GitHub repository.