This guide will help you install BoxBilling on your server.

System requirements

Environment on which you are going to install BoxBilling should meet these prerequisites:

  • Linux OS

  • PHP >=5.3.3 or later with extensions

    • PDO MySQL
    • curl
    • mbstring
    • zlib
    • ftp
    • gettext
    • mcrypt
  • MySQL Version 4.1.* or later

  • Apache mod_rewrite module enabled, for SEO urls only

It is recommended to install BoxBilling on VPS server with APC cache enabled for best performance and security reasons.

Installation guide

To start BoxBilling installation download latest version from download page

After download is complete extract all files on your computer and upload them via FTP to your server.

Using web installer

Web installer is a convenient way to install BoxBilling and it should be used in most cases. This guide is based assuming that you have uploaded all files to subfolder billing

Access installation setup via the browser, by opening

  1. You will need to tick “I agree to the license” to continue the installation.
  2. In the next screen a “Pre-Installation check” will recheck if the system (hosting account) does meet the minimum requirements for installation. Most often you will need to login to your account via a file manager (or FTP manager) and set the required permissions (chmod 777) on these files and folders.
  3. In the next step you will need to setup access to the MySQL database. Enter an existing database and user (with all permissions granted). If you have any trouble setting up a MySQL database and user, please consult your hosting provider. For example, if you are hosting on cPanel powered hosting, you can setup database and users via the cPanel > MySQL area.
  4. Enter the e-mail and credentials for the administrator account. A greeting letter will be sent to the administrator e-mail account upon successful installation of BoxBilling.
  5. Even though BoxBilling is free it requires to obtain license key in order to work.
  6. Finish installation with confirming that all the information is correct.

After installation is complete

  1. Remove directory completely
  2. Change billing/bb-config.php file permissions to 644 if necessary
  3. Setup cron job to run every five minutes.
*/5 * * * * php install/path/bb-cron.php

Installation is complete and you can visit admin area at

Changing application timezone

By default BoxBilling installs with “America/New_York” timezone. To change this open bb-config.php file and edit line with preferred timezone.

'timezone'    =>  'UTC',

All available timezones are listed at

Enabling search engine friendly URL’s

When SEO urls are not enabled all BoxBilling urls will have index.php prefix. To enable search engine friendly urls follows these steps:

  • Rename htaccess.txt (file which comes with installation) to .htaccess
  • Open bb-config.php file and set BB_SEF_URLS to true
'sef_urls'  => true,


SEO urls will also be enabled for admin area. Old links will stop working.

Debugging and error logging

Enable BoxBilling debug mode in bb-config.php file:

'debug'     => true,

This will show errors on your site and provides more debugging information. If you set BB_DEBUG to FALSE it will still log all errors log file. It can be accessed at bb-data/log/php_error.log

nginx host configuration

location ~ bb-admin\.php {
        if (!-e $request_filename) {
                rewrite ^(.+)$ /bb-admin.php?$1 last;

location / {
        if (!-e $request_filename) {
                rewrite ^(.+)$ /index.php?$1 last;

Directory structure explanation

Directory where BoxBilling cache, logs and uploaded data is stored
Directory for system files and payment/registrar adapters
Directory for interface translations
Directory for modules/extensions
Directory for client and admin area themes
BoxBilling web installer. Can be safely removed after installation
Main BoxBilling file where all requests are gathered