This document lists everything operators and integrators must prepare for when upgrading to BillRun 6.0.0. Items marked [ACTION REQUIRED] need a deliberate step during upgrade; items marked [HEADS UP] may affect custom code or configuration.
Docker deployments handle most of these steps automatically (see each item). Manual / bare-metal deployments must perform them explicitly.
composer install [ACTION REQUIRED]The vendor/ directory is no longer tracked in the repository (it is now gitignored). Previously BillRun shipped its PHP dependencies inside the repo.
What you must do:
composer install to fetch dependencies before starting the application.composer install during build/startup. No manual action needed.The composer installation setup require some internet access to the following domains in order to be deployed correctly :
pecl.php.net
*github.com
*packagist.org
getcomposer.org
objects.githubusercontent.com
For outgoing connections with 443 (HTTPS), 22 (git SSH) and 80 (HTTP) ports.
(This is only while running the composer install. It is not required for runtime)
BillRun 6.0.0 supports and is tested on PHP 8.1 through 8.5. Official Docker images are provided for php 8.5. Using PHP 7.4 is deprecated but still supported.
What you are advised to do:
billrun-php85).BillRun 6.0.0 targets MongoDB Server 8.0 (compose files now use mongo:8.0). Sharding is configured automatically at initialization. MongoDB 7.0 is supported for backward compatibility.
What you must do:
BillRun 6.0.0 ships against the latest mongodb PECL extension (e.g. mongodb-2.3.x), together with the mongodb/mongodb library. The legacy mongo extension has not been used since BillRun 5.0, so no driver migration is required for 5.x-era operators.
What you should do:
mongodb PECL extension is installed and reasonably up to date on your PHP runtime.Database initialization and migration are now driven by a PHP-native migration framework that is idempotent and tracks applied tasks.
JavaScript Mongo-shell scripts should be executed one last time if you’re upgrading from the non-last 5.x version to 6.0.0.
What you must do:
mongo/*.js scripts manually:$ php public/index.php --env <env> --dbmigrate # will run the core migration scripts$ php public/index.php --env <env> --dbmigrate --path=/path/to/plugin/application/migrations/ # will run the plugin migration scriptsThe legacy single billrun document is split into two new sharded collections - billrun_subs (subscriber-level data) and billrun_grouping (per-cycle aggregations) - declared in container.ini with dedicated indexes. A migration script ships with the release but is not executed automatically. Backward-compatible reads remain for any legacy billrun objects that still embed subs.
What you must do / know:
billrun.subs.* / billrun.grouping.* directly in MongoDB should switch to the new billrun_subs / billrun_grouping collections, or use the Billrun model API which transparently resolves both layouts.billrun.save_to_file_subs_limit configuration is no longer supported.BillRun 6.0.0 introduces a customer hierarchy model: accounts can have a parent account, with up to 4 levels in phase 1. Migration application/migrations/20260527_001_BRCD-785.php adds three system fields to accounts (in the subscribers collection, type=account) and an index on parent_aid:
| Field | Type | Default | Meaning |
|---|---|---|---|
parent_aid |
int/null | null |
Parent account id (null = root / no parent). |
issues_invoice |
bool | true |
If false, charges roll up to nearest invoicing ancestor. |
is_payer |
bool | true |
If false, payment resolves to nearest is_payer=true ancestor. |
Rules:
issues_invoice=false implies is_payer=false.parent_aid=null) are always issues_invoice=true and is_payer=true.aid and persist there even if issues_invoice later flips - there is no subtree summing.What you must do / know:
parent_aid set. Flat tenants behave exactly as in 5.x with no change.Billrun_Bill_Payment::makePayment - it walks up to the nearest is_payer=true ancestor. Custom payment-pipeline plugins should be aware.aid and works automatically.gethierarchy (BillAPI) returns the hierarchy with issues_invoice / is_payer for an account subtree.phpoffice/phpspreadsheet: 1.15.0 -> ^1.16. Relevant if you have custom invoice/report/export code that calls PhpSpreadsheet directly.^2.0 (module-rest, module-mongodb, module-db, module-phpbrowser 1.0.3). If you maintain custom acceptance tests, update them accordingly.Acknowledging of events sent by the events manager is done by returning 200 as the HTTP response code. Previously, the “status” field of the JSON response had to be equal to 1.
The admin/customer UI is upgraded to React 19, with legacy Bootstrap 3 patterns removed and asset bundles regenerated (new hashed filenames). The compiled frontend assets ship inside the repository, so no client-side build step is required during upgrade.
What you should do:
cache.* namespace and now ships with a dedicated clearCache script/action that also resets OPcache. Update your config if you previously set this flag.BR_MDB_* environment overrides: if you are upgrading from a version earlier than 5.25.0, note the 5.25.0 breaking change where BR_MDB_* environment variables override MongoDB connection config.billrun_roles path and any custom scopes after upgrade.docker pull billrun/billrun:6.0.0 (published automatically per tagged version as billrun/billrun:<version>, from 5.25.0+).-p 8074:8074).APPLICATION_MULTITENANT (default 0) controls single- vs. multi-tenant nginx routing; set to 1 for multi-tenant.mongodb PECL extension installed.composer install.billrun_subs / billrun_grouping split - §5a - and the customer-hierarchy field migration - §5b).billrun_subs / billrun_grouping. If you adopt the customer hierarchy, validate invoice consolidation and payment-gateway resolution on a non-production tenant first.If your environment blocks or restricts outbound internet traffic, allow access to the domains listed below so that the Docker installation and deployment can complete successfully. No additional network configuration is required in environments with unrestricted outbound internet access.
This access is required only during installation and deployment, not during runtime.
hub.docker.com
git.bill.run
archive.debian.org
pecl.php.net
*github.com
repo1.maven.org
*packagist.org
getcomposer.org
objects.githubusercontent.com
For out going connections with 443 (HTTPS) , 22 (git SSH) and 80 (HTTP) ports.