From b9f1fca5e80fbe2d4b14a42522508ad067efd855 Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Sat, 30 May 2026 19:50:56 +0100 Subject: [PATCH 1/4] Docs: proxy detection, updater & product updates --- src/content/docs/admin-guide/config.mdoc | 6 ++++ .../product-types/downloadable.mdoc | 10 ++++++- .../admin-guide/product-types/hosting.mdoc | 19 ++++++++++++ .../docs/getting-started/installation.mdoc | 6 ++-- .../docs/maintenance/Updating/index.mdoc | 20 +++++++++---- src/content/docs/maintenance/changelog.mdoc | 30 +++++++++---------- .../docs/security/securing-fossbilling.mdoc | 11 +++++++ src/content/docs/support/features.mdoc | 3 +- 8 files changed, 80 insertions(+), 25 deletions(-) diff --git a/src/content/docs/admin-guide/config.mdoc b/src/content/docs/admin-guide/config.mdoc index e15c013..d8728e4 100644 --- a/src/content/docs/admin-guide/config.mdoc +++ b/src/content/docs/admin-guide/config.mdoc @@ -46,6 +46,12 @@ Configure reverse-proxy support so FOSSBilling correctly detects the visitor's I | `trusted_proxies.proxies` | `[]` | List of trusted proxy IPs or CIDR ranges | | `trusted_proxies.headers` | `x_forwarded` | Header type: `x_forwarded` (standard) or `forwarded` (RFC 7239) | +{% aside type="tip" %} +The installer and admin panel can detect reverse proxies automatically. When forwarded headers are detected, the installer shows a proxy configuration step with the detected proxy address and a suggested public URL. You can also review and configure proxy settings from **System** → **Settings** in the admin panel. +{% /aside %} + +If you are running behind a reverse proxy, configure the `trusted_proxies` setting in your config (see above) so request metadata is interpreted correctly. + ### Encryption Key - `salt` — Used for reversible encryption. **Keep this secret and don't change it** after installation. diff --git a/src/content/docs/admin-guide/product-types/downloadable.mdoc b/src/content/docs/admin-guide/product-types/downloadable.mdoc index 2135988..b1d97fc 100644 --- a/src/content/docs/admin-guide/product-types/downloadable.mdoc +++ b/src/content/docs/admin-guide/product-types/downloadable.mdoc @@ -32,5 +32,13 @@ The product will appear in your store like any other. After purchase, customers - View download statistics per order - See which customers have downloaded files -- Update files for existing products +- Update files for existing products — when you replace a file, the old stored file is automatically cleaned up if no other products or orders reference it - Track popular downloads + +### File Storage + +Uploaded files are stored with a generated `stored_filename` (a unique 64-character hex identifier) separate from the display filename. This keeps the original file name visible to customers while preventing unauthorized file access through guessing or path traversal. + +When you upload a replacement file for a product: +- Existing orders can optionally be updated with the new file +- The previous file is removed automatically if it is no longer referenced by any product or order diff --git a/src/content/docs/admin-guide/product-types/hosting.mdoc b/src/content/docs/admin-guide/product-types/hosting.mdoc index af353fc..14d9f94 100644 --- a/src/content/docs/admin-guide/product-types/hosting.mdoc +++ b/src/content/docs/admin-guide/product-types/hosting.mdoc @@ -46,3 +46,22 @@ Anything not listed above likely won't work. Check our [server managers document 4. Link them to your hosting plans See [server manager guides](/admin-guide/server-managers/) for specific setup instructions. + +## Domain Options + +When configuring a hosting product, you choose which domain options customers can use during checkout: + +| Option | Default | Description | +|--------|---------|-------------| +| Allow domain registration | Yes | Customers can register a new domain | +| Allow domain transfer | Yes | Customers can transfer an existing domain | +| Allow using own domain | Yes | Customers can point an existing domain they manage elsewhere | +| Offer free subdomains | No | Customers get a free subdomain on a base domain you provide | + +### Free Subdomains + +Enable **Offer Free Subdomains** and enter a **Free Subdomain Base Domain** (e.g., `example.com`) to let customers choose a subdomain like `username.example.com` without registering or transferring a domain. + +- Duplicate subdomains are blocked — once a subdomain is assigned to an active order, it cannot be reused. +- The base domain is configured per product and cannot be overridden by clients. +- Free subdomains do not trigger domain registration or transfer charges. diff --git a/src/content/docs/getting-started/installation.mdoc b/src/content/docs/getting-started/installation.mdoc index c5c3212..70d7919 100644 --- a/src/content/docs/getting-started/installation.mdoc +++ b/src/content/docs/getting-started/installation.mdoc @@ -147,8 +147,10 @@ server { If you see the FOSSBilling installer welcome page below, you're ready to proceed. ![The FOSSBilling Installer Landing Page](../../../assets/guides/install/installer-landing.png) 4. **Complete the setup wizard**: Follow the on-screen steps to accept the license, enter your database credentials, and create your administrator account. -5. **Configure the default currency**: Select your currency code (e.g., `USD`, `EUR`). The price format is auto-generated; place your currency symbol before or after the `{{price}}` placeholder, for example `{{price}} USD` or `$ {{price}}`. -6. **Install**: Click install and wait for the success page to appear. +5. **Confirm the public URL**: The installer shows a suggested FOSSBilling URL based on how you accessed it. Verify this is the correct public address for your installation (e.g., `https://billing.example.com/`). +6. **Configure reverse proxy (if detected)**: If the installer detects forwarded headers from a reverse proxy, it shows a proxy configuration step where you can enable trusted proxy support and review the detected settings. Only enable this if the detected proxy is one you control and trust. +7. **Configure the default currency**: Select your currency code (e.g., `USD`, `EUR`). The price format is auto-generated; place your currency symbol before or after the `{{price}}` placeholder, for example `{{price}} USD` or `$ {{price}}`. +8. **Install**: Click install and wait for the success page to appear. {% aside type="tip" %} If installation fails, you may need to manually empty the database before retrying. diff --git a/src/content/docs/maintenance/Updating/index.mdoc b/src/content/docs/maintenance/Updating/index.mdoc index 024e367..8e997db 100644 --- a/src/content/docs/maintenance/Updating/index.mdoc +++ b/src/content/docs/maintenance/Updating/index.mdoc @@ -20,9 +20,20 @@ For most installations, the built-in updater is the easiest option: 1. Log in to your admin panel 2. Go to **System** → **Update** -3. Click to apply the update +3. Click to install the update -FOSSBilling downloads and applies the update automatically. It follows the configured update branch, usually `release` or `preview`, which you can change in your [configuration file](/admin-guide/config/). +FOSSBilling downloads and installs the new files, enables maintenance mode, clears the cache, and logs you out. After logging back in, you will be prompted to finalize the update. + +### Update Finalization + +Starting with 0.8.1, updates follow a two-phase process: + +1. **Install** — New files are downloaded and deployed. Maintenance mode is enabled and you are logged out. +2. **Finalize** — After logging back in, FOSSBilling shows a finalization page where you apply any pending database patches. Once patches are complete, maintenance mode is restored to its previous state and you return to the dashboard. + +This prevents older versions from automatically applying database patches before the new code is in place. + +The updater follows the configured update branch, usually `release` or `preview`, which you can change in your [configuration file](/admin-guide/config/). ## Manual Updates @@ -32,10 +43,9 @@ If you prefer to manage files yourself: 2. [Download the latest release](https://fossbilling.org/downloads/stable) 3. Extract the files over your existing installation (overwrite existing files) 4. Delete the `install` folder that came with the new files -5. Log in to the admin panel and go to **System** → **Update** -6. Click **Apply Patches & Update Configuration** +5. Log in to the admin panel and follow the finalization prompt to apply pending patches -Always run the patches after copying in new files so the database schema and configuration stay in sync with the codebase. +FOSSBilling will detect the new files and direct you to the finalization page. If you navigated away, go to **System** → **Update** and use **Apply Patches & Update Configuration**. If an update fails or FOSSBilling errors after updating, see [Troubleshooting FOSSBilling Issues](/maintenance/troubleshooting/#errors-after-updating). diff --git a/src/content/docs/maintenance/changelog.mdoc b/src/content/docs/maintenance/changelog.mdoc index ae99013..c636a03 100644 --- a/src/content/docs/maintenance/changelog.mdoc +++ b/src/content/docs/maintenance/changelog.mdoc @@ -14,28 +14,26 @@ FOSSBilling publishes release notes and tagged versions on GitHub. Use the links {% /card %} {% /cardgrid %} -## Recent Highlights +## Latest Release For the latest changes, start with the [most recent release](https://github.com/FOSSBilling/FOSSBilling/releases/latest). -### Version 0.8.0 +### Version 0.8.1 | Area | Summary | |------|---------| -| **PHP** | Minimum version raised to 8.3 | -| **Database** | Charset migrated to `utf8mb4`; DB config key renamed from `db.type` to `db.driver` | -| **Configuration** | New `rate_limiter` block replaces old `api.rate_*` keys; new `trusted_proxies` and `auto_detect_locale` settings | -| **Modules** | `Antispam` replaces `Spamchecker`; `Servicemembership`, `Paidsupport`, `Wysiwyg` removed; new `Widgets` module | -| **Templates** | All module templates moved from `html_*` to `templates/{admin,client,email}/` | -| **Build** | Front-end asset build migrated from Webpack Encore to esbuild; jQuery removed; shared frontend source now lives in `/frontend`; assets built into `/src/public/assets` | -| **Routing** | Custom HTTP layer replaced with Symfony HttpKernel, HttpFoundation, and Routing components | -| **Themes** | Asset loading (`encore_entry_*` → direct tags), Twig filter removals (`alink`, `link`, `gravatar`, `library_url`, `markdown`, `size`, legacy `money*` filters), `DebugBar_renderHead()` → `debug_bar_render_head()`, new `public_asset_url` filter, new `url` filter with `area` parameter | -| **API** | Guest API hardened: `system_version` endpoint removed, public company data can be restricted with `hide_company_public`, rate limiting on guest ticket creation | -| **Library** | New Doctrine ORM layer alongside RedBean; Symfony Rate Limiter, Uid, Sanitizer, Serializer, PropertyAccess components added; `Box_Mod`, `Box_Paginator`, `Box_TwigExtensions` removed; Gravatar replaced with DiceBear | -| **Patcher** | Extended through patch 64 (was 43) | -| **Uploads & Public Assets** | Uploads moved from `/uploads` to `/data/uploads`; gateway and default branding assets moved to `/public` | - -[View the full 0.8.0 release notes](https://github.com/FOSSBilling/FOSSBilling/releases/tag/0.8.0) for the complete list of changes. +| **Security** | Sanitized admin ticket replies, validated downloadable stored filenames, hardened license doc links, prevented subdomain override, refreshed OPcache after config preservation, hardened UpdatePatcher SQL safety | +| **Hosting** | Free subdomain option with duplicate protection | +| **Anti-spam** | reCAPTCHA v3 score-based bot detection on public forms | +| **Client signup** | Auto-login after registration; separate last name field | +| **Updates** | Two-phase update finalization process (install then finalize patches); maintenance mode enabled during updates | +| **Proxy** | Pre-config proxy detection and admin proxy candidate settings UI for reverse proxy setups | +| **Downloadable** | `stored_filename` attribute for safer file tracking and orphan cleanup | +| **Admin** | Active menu highlighting, Massmailer autocomplete test client selector, tab-targeted redirects | + +[View the full 0.8.1 release notes](https://github.com/FOSSBilling/FOSSBilling/releases/tag/0.8.1) for the complete list of changes. + +For older releases, browse the [full release history on GitHub](https://github.com/FOSSBilling/FOSSBilling/releases). ## Breaking Changes diff --git a/src/content/docs/security/securing-fossbilling.mdoc b/src/content/docs/security/securing-fossbilling.mdoc index d924a29..a2dc11d 100644 --- a/src/content/docs/security/securing-fossbilling.mdoc +++ b/src/content/docs/security/securing-fossbilling.mdoc @@ -97,6 +97,17 @@ If you're using Cloudflare, enable **IP Geolocation** under your site's **Networ ## Reverse Proxies +### Auto-Detection + +FOSSBilling can detect when it is running behind a reverse proxy. If forwarded headers (such as `X-Forwarded-For` or `Forwarded`) are present during installation, the installer shows a proxy configuration step with: + +- The detected proxy IP address +- Whether the address is private/local +- The detected header format +- A suggested public URL derived from the forwarded headers + +You can enable trust directly in the installer or configure it later in `config.php` using the `trusted_proxies` setting. + ### HTTPS Detection Reverse proxies often make FOSSBilling think it is being accessed over HTTP even when the visitor is using HTTPS. To avoid that, make sure your proxy forwards `X-Forwarded-Proto: https`. diff --git a/src/content/docs/support/features.mdoc b/src/content/docs/support/features.mdoc index 323a643..ed58472 100644 --- a/src/content/docs/support/features.mdoc +++ b/src/content/docs/support/features.mdoc @@ -23,7 +23,7 @@ The `Antispam` module (replaces the old `Spamchecker` module in 0.8.0) provides | Feature | Status | Notes | |---------|--------|-------| | IP blocking | ✅ | Block problematic IPs | -| CAPTCHA | ✅ | reCaptcha v2, Cloudflare Turnstile and hCaptcha supported. | +| CAPTCHA | ✅ | reCaptcha v2, reCaptcha v3 (score-based), Cloudflare Turnstile and hCaptcha supported. | | Stop Forum Spam | ✅ | Community-driven spam prevention | | Disposable email blocking | ✅ | Uses [FakeFilter](https://fakefilter.net) | | MFA/2FA | 🚧 | Planned before 1.0 release | @@ -44,6 +44,7 @@ The `Antispam` module (replaces the old `Spamchecker` module in 0.8.0) provides | 1-click client login | ✅ | Depends on server manager support | | Custom domains | ✅ | Via nameserver updates | | Domain + hosting orders | ✅ | Register domains alongside hosting | +| Free subdomains | ✅ | Offer subdomains on a base domain you control, with duplicate protection | ## Domains From febbeb1623b73285fd794f5a9ac479b8031e1667 Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Sat, 30 May 2026 19:54:46 +0100 Subject: [PATCH 2/4] Update docs banner to 0.8.1 --- src/content/docs/index.mdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/index.mdoc b/src/content/docs/index.mdoc index 6b317ad..aa4cfb5 100644 --- a/src/content/docs/index.mdoc +++ b/src/content/docs/index.mdoc @@ -4,7 +4,7 @@ description: Learn what FOSSBilling is, where to start, and how to get involved tableOfContents: false banner: content: | - 0.8.0 is here! Check out the + 0.8.1 is here! Check out the release notes and upgrade guide for details. --- From 74967fe70298036bdfe8911edce545c811ac6e9c Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Sat, 30 May 2026 20:05:24 +0100 Subject: [PATCH 3/4] Update release notes link to 0.8.1 --- src/content/docs/index.mdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/index.mdoc b/src/content/docs/index.mdoc index aa4cfb5..0c25009 100644 --- a/src/content/docs/index.mdoc +++ b/src/content/docs/index.mdoc @@ -5,7 +5,7 @@ tableOfContents: false banner: content: | 0.8.1 is here! Check out the - release notes + release notes and upgrade guide for details. --- From 7f62829c0d7f7b4792e4daec194d5f1cc3a6b74d Mon Sep 17 00:00:00 2001 From: Adam Daley Date: Sat, 30 May 2026 20:10:18 +0100 Subject: [PATCH 4/4] Fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/content/docs/index.mdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/index.mdoc b/src/content/docs/index.mdoc index 0c25009..7877154 100644 --- a/src/content/docs/index.mdoc +++ b/src/content/docs/index.mdoc @@ -6,7 +6,7 @@ banner: content: | 0.8.1 is here! Check out the release notes - and upgrade guide for details. + and the 0.7 → 0.8 upgrade guide for details. --- FOSSBilling (*FOSS*: Free and Open Source Software) is a billing and client management solution for hosting providers and digital service businesses.