Cloudflare R2 Integration
Relevant source files
The following files were used as context for generating this wiki page:
Cloudflare R2 Integration provides the storage and delivery layer for the FOSSBilling branding assets. The system automatically publishes generated icons, logos, and favicons to an R2 bucket during the CI/CD process. This ensures that the latest branding materials are publicly accessible at branding.fossbilling.org for documentation, websites, and community use.
The integration triggers upon pushes to the main branch or manual workflow runs. It takes the output of the asset generation script—including optimized SVGs, PNGs, and a manifest.json file—and synchronizes them to the R2 storage backend.
Sources: README.md:16-24, README.md:104-108
Workflow Architecture
The publishing process follows a structured pipeline from source SVG modification to remote storage synchronization.
The diagram shows the transition of assets from local generation to public availability via Cloudflare R2.
Sources: README.md:92-108, scripts/generate-assets.ts:133-145
Asset Preparation and Optimization
Before assets are uploaded to Cloudflare R2, the system optimizes and bundles them. The generate-assets.ts script performs the following actions:
- SVG Optimization: Strips metadata and editor-specific data from source SVGs while preserving paths and viewBox settings.
- Rasterization: Generates PNG files at specific widths defined in
export.config.json. - Manifest Generation: Creates a
manifest.jsonfile containing the export timestamp and a full list of asset metadata. - Bundling: Combines assets and the manifest into a single ZIP archive for distribution.
Sources: scripts/generate-assets.ts:100-140, README.md:104-108, export.config.json:1-20
Configuration and Metadata
The integration relies on specific configuration files to determine which assets are processed and how they are described in the final R2 bucket.
Export Configuration
The export.config.json file defines the variants and sizes intended for the public bucket.
| Key | Description | Example Value |
|---|---|---|
assetsOutput | Destination for optimized SVGs | "assets/" |
output | Destination for PNGs and manifest | "dist/" |
iconSizes | Array of pixel sizes for icons | [128, 256, 512] |
logoWidths | Array of pixel widths for logos | [600, 1200] |
Sources: export.config.json:1-12, scripts/generate-assets.ts:80-90
Asset Manifest
The manifest.json file acts as the directory for the R2 bucket, allowing external tools to discover available assets programmatically.
The manifest structure records the exact state of assets published to R2.
Sources: scripts/types.ts:8-23
Deployment Logic
The deployment to Cloudflare R2 is controlled by the .github/workflows/build-and-publish-assets.yml workflow.
- Triggering: The workflow runs on pull requests, pushes to
main, and manual executions. - Asset Generation: The workflow executes
npm run generateusing Node.js 24+. - Publishing Condition: Assets are only uploaded to R2 if the push is to the
mainbranch or if thepublishflag is set totrueduring a manual run. - Distribution: The files, including
fossbilling-branding.zip, are made available at the root of the R2 bucket.
Sources: README.md:104-108, package.json:4-11
Conclusion
Cloudflare R2 Integration serves as the automated distribution mechanism for FOSSBilling's visual identity. By combining TypeScript-based asset generation with Cloudflare's storage, the project maintains a consistent and highly available repository of branding materials for all stakeholders.