BillRun supports multitenancy within a single instance, allowing multiple independent billing implementations to share the same codebase. Each tenant is isolated through its own configuration, database, and file system directories.
This guide assumes multitenancy is managed under the billrun.localhost domain, with subdomains handled by NGINX.
To enable multitenancy for the web interface, add the following FastCGI parameter to your NGINX configuration:
fastcgi_param APPLICATION_MULTITENANT 1;
After applying this change, you must also:
server_name: *.billrun.localhost;For more details on NGINX configuration, see the BillRun installation guide.
Once enabled, the application identifies the active tenant from the subdomain. For example, given the base domain billrun.localhost, a tenant is accessed at:
<TENANTNAME>.billrun.localhost
To enable multitenancy for CLI operations, set the following environment variable:
export APPLICATION_MULTITENANT=1
To avoid setting this on every session, add the export line to /etc/profile so it persists across logins.
Once multitenancy is enabled, every CLI command requires the --tenant flag. For example, to run the charge command for a specific tenant:
php public/index.php --env prod --tenant <TENANTNAME> --charge --size 20000
Each tenant has its own set of isolated resources. The following paths are created and used per tenant:
| Location | Description |
|---|---|
<BILLRUN_ROOT>/conf/tenant/<TENANTNAME>.ini |
Tenant-specific configuration, including the required separate database settings |
<BILLRUN_ROOT>/shared/<TENANTNAME>/ |
Tenant-specific storage for invoices, payment files, workspace files, etc. |
<BILLRUN_ROOT>/logs/<TENANTNAME>/ |
Tenant-specific log directory |
<BILLRUN_ROOT>/application/views/invoices/tenants/<TENANTNAME>/ |
Custom invoice template directory |
<BILLRUN_ROOT>/conf/translations/tenants/<TENANTNAME>/ |
Invoice translation overrides |
<BILLRUN_ROOT>/cache/<TENANTNAME>_ |
Tenant-specific cache prefix (only applicable if caching is enabled) |
Note: A separate database per tenant is required and must be defined in the tenant's
.iniconfiguration file.
To retrieve the current tenant programmatically, use the following:
$currentTenant = Billrun_Factory::config()->getTenant();