Skip to content

About

FOSSBilling extension directory

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

10 stars

Watchers

7 watching

Forks

FOSSBilling Extensions

The official extension directory for FOSSBilling.

Visit it at extensions.fossbilling.org.

About the Directory

Lists modules, themes, payment gateways, server managers, domain registrars, hooks, and translations that can be auto-installed from within FOSSBilling.

Only auto-installable extensions are listed. Other community extensions may be available via the FOSSBilling docs, GitHub, or individual maintainers.

Installing Extensions

From your FOSSBilling admin panel:

  1. Log in to the admin panel.
  2. Open the Extensions page.
  3. Find the extension and click Install.

Manual install is also possible: download the archive, extract it into the correct FOSSBilling extension folder, and enable it from the admin panel.

Submitting Extensions

Sign in (top-right of the site) and open /account. First-time publishers create a developer profile, then submit new extensions or edit ones they publish. Submissions go through moderator review before they appear in the directory.

Your account profile (display name, bio) is separate from your developer profile and is not shown publicly yet.

Badges

The FOSSBilling/api repo serves badges for use in READMEs and project pages:

https://api.fossbilling.net/extensions/v2/extensions/branding/badges/version
https://api.fossbilling.net/extensions/v2/extensions/branding/badges/fossbilling
https://api.fossbilling.net/extensions/v2/extensions/branding/badges/license

Replace branding with your extension ID. The fossbilling badge shows the full requirement, such as >=0.8.9 <1.0 || ^2.0. Use ?color=green to change the color. Legacy v1 badge URLs are supported until 5 February 2027 and now display the corresponding v2 badge, including the full version requirement.

Contributing

Issues and pull requests are welcome. Useful contributions include bug reports, accessibility improvements, UI fixes, documentation updates, and improvements to extension metadata handling.

For broader discussion, join the FOSSBilling community on Discord.

Local Development

Astro site on Cloudflare Workers. Extension data comes from the FOSSBilling/api repo's /extensions/v2 service via the generated client in src/lib/api/generated/extensions-v2. Sign-in is delegated to auth.fossbilling.net via OAuth2/OIDC.

Install dependencies:

npm install

Set up local secrets:

cp .dev.vars.example .dev.vars
Variable Notes
AUTH_CLIENT_ID / AUTH_CLIENT_SECRET Issued by an admin of FOSSBilling/auth. The production client uses https://extensions.fossbilling.org/auth/callback; use separate development and preview clients for localhost and staging (see below).
SESSION_SECRET Any random string, e.g. openssl rand -base64 32.
ASSERTION_SIGNING_SECRET Must match the api repo's value exactly.
EXTENSIONS_REVALIDATE_SECRET Shared with the api repo for POST /api/revalidate.
EXTENSIONS_API_BASE_URL Defaults to https://api.fossbilling.net. Point at a local api dev server when working on both.
EXTENSIONS_API_TRANSPORT http locally, binding in production.

Start the dev server:

npm run dev

Run the checks before pushing. CI runs the same suite on pushes to main and pull requests targeting main:

npm run api:check    # generated client matches openapi/extensions-v2.json
npm run format:check # prettier
npm test             # vitest suite
npm run check        # astro check
npm run build        # production build

Refresh the API contract and client with npm run api:update (also run weekly by the Update Extensions v2 OpenAPI workflow). To regenerate the client from the existing contract only, run npm run api:generate.

Production secrets:

npx wrangler secret put AUTH_CLIENT_ID
npx wrangler secret put AUTH_CLIENT_SECRET
npx wrangler secret put SESSION_SECRET
npx wrangler secret put ASSERTION_SIGNING_SECRET
npx wrangler secret put EXTENSIONS_REVALIDATE_SECRET

Branch Previews use HTTP transport to the shared staging API and display synthetic data. Use three separate OAuth clients:

Client Used by
Production https://extensions.fossbilling.org
Development http://localhost:4321
Previews Named staging Preview and same-repository branch Previews

Set the preview client's AUTH_CLIENT_ID and AUTH_CLIENT_SECRET, a preview-only SESSION_SECRET, and matching ASSERTION_SIGNING_SECRET / EXTENSIONS_REVALIDATE_SECRET values for the staging API in Cloudflare's Previews Base. Existing Previews need these secrets set individually.

Cloudflare Workers Builds builds main once with npm run build, then runs npm run cf-deploy to publish production and the named staging Preview using that build. Staging serves https://staging-extensions.fossbilling.workers.dev and uses https://staging-api.fossbilling.workers.dev; both use their existing Workers. API-side cache invalidation targets the named directory Preview. Other branch Previews use normal cache expiry and invalidate their own cache after directory edits.

The Preview Authentication workflow reconciles exact callbacks for live branch Previews and named staging after successful Cloudflare builds, branch deletion, and hourly. Make the organization's CLOUDFLARE_ACCOUNT_ID variable available to this repository and set its CLOUDFLARE_API_TOKEN Actions secret. For callback discovery, scope the token to extensions with Individual Workers Metadata Read-Only. The auth service must set EXTENSIONS_PREVIEW_CLIENT_ID to this client. It accepts updates only from the trusted workflow on main, authenticated through GitHub Actions OIDC.

License

The extension directory website is licensed under the GNU Affero General Public License Version 3. See LICENSE for details.

Individual extensions are licensed by their respective authors.

Manifest API contract

The generated v2 client follows the API's manifest v1 contract: module, string licenses, optional homepage_url, package authors, and full FOSSBilling/PHP/module requirements. Author/edit/moderator forms preserve these fields.

Package preparation is queued. The API returns a private job ID; the release editor shows queued/processing status and saves that reference in browser storage so it can resume after a reload. A completed release joins the local draft and still needs review. A pending release can receive a replacement ZIP. Once published, its validated ZIP stays locked and listing corrections leave the file unchanged.

Authors upload ready-to-install distribution ZIPs directly to private object storage using a short-lived URL issued by the API. The package bucket needs a PUT CORS rule for the directory’s origin. Icons use icon.svg, icon.png, icon.webp or icon.avif at the package root, without a manifest field. The API prepares display images in the public asset bucket during processing, including pending icons at unlisted UUID URLs. Existing HTTP(S) icon URLs remain supported for display. Package downloads and pending previews use permission-checked API routes.

Published icon URLs use https://extensions-assets.fossbilling.net/extensions/<extension UUID>/icons/<asset UUID>.<format>. The extension UUID is independent of its public identifier. SVG or AVIF/PNG variants share the processed icon's immutable asset UUID, so metadata-only edits retain the same icon URL.

API mutations and site mutations purge the extensions and developers cache tags. The developers tag is currently a no-op; developer pages are uncached. Deploy and smoke-test the configured, package-enabled API before deploying this site or enabling the modules publisher. The API’s Durable Object dispatcher runs the jobs through the configured packager.

Directory Identity

Extension and developer records use UUIDv7 internal IDs. Public routes, profile handles and publishing requests use the separate identifier fields. Keep UUIDs for record identity and audit-history links. A package manifest keeps its id field, whose value is the public extension identifier.

About

FOSSBilling extension directory

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

10 stars

Watchers

7 watching

Forks

Sponsor this project

Used by

Contributors

Languages