How to Install BoxBilling on Debian 12

BoxBilling on Debian 12 (Apache + MariaDB + PHP + SSL)

BoxBilling is a free, open-source billing and client management solution built for web hosting providers, digital businesses, and freelancers. It includes invoicing, product management, order automation, domain integration, and support ticketing — everything needed to manage clients and services in one place. With a plugin and theme system, BoxBilling can be customized and extended to fit business needs.

Running BoxBilling on Debian 12 (Bookworm) provides a stable, secure, and long-supported foundation for financial and client data management. Debian is well-known for its reliability in production environments and ships with systemd 252, OpenSSL 3, and modern PHP/MariaDB packages, making it an excellent choice for hosting BoxBilling.

Architecture Overview

Layer	Component	Role
OS	Debian 12 (Bookworm)	Stable, secure base with long-term support
Web Server	Apache HTTPD	Hosts the PHP-based BoxBilling frontend and backend
Database	MariaDB/MySQL	Stores users, clients, invoices, orders, and transaction data
Runtime	PHP 8.x + Extensions	Runs BoxBilling core application logic
Reverse Proxy	Nginx (optional)	TLS termination, caching, load balancing
TLS	Let’s Encrypt / PKI	Secures client and admin access with HTTPS

Why Use BoxBilling?

All-in-one billing system – invoices, taxes, recurring payments, and multiple currencies.
Client management – keep track of users, orders, and support requests.
Hosting-ready – integrate with control panels, domain registrars, and provisioning tools.
Free & open-source – no licensing fees compared to WHMCS or Blesta.
Global support – multilingual and multi-currency capabilities.

BoxBilling vs Other Billing Platforms

Feature/Capability	BoxBilling (Free)	WHMCS (Paid)	Blesta (Paid)	ClientExec (Paid)
License cost	Free, open-source	Commercial license	Commercial license	Commercial license
Core features	Billing, support, hosting	Full suite + large ecosystem	Billing + support	Billing + support
Extensibility	Plugins + themes	Wide marketplace	Limited	Limited
Best for	Freelancers, SMBs	Hosting providers	SMBs	SMBs

BoxBilling is ideal for freelancers and small to medium providers who want automation without recurring licensing costs.

Security & Best Practices

Use HTTPS everywhere with Let’s Encrypt or corporate PKI.
Secure MariaDB with strong credentials, user permissions, and backups.
Harden PHP (disable dangerous functions, configure php.ini securely).
Protect the admin panel with IP restrictions or firewall rules.
Regularly update Debian, Apache, PHP, and BoxBilling to the latest versions.
Enable Fail2Ban or rate-limiting on login endpoints.

Typical Use Cases

Web hosting companies – manage domains, hosting, and client billing.
Freelancers/digital agencies – automate invoicing and client support.
SaaS startups – manage subscriptions and recurring billing.
Testing environments – evaluate billing automation without licensing fees.

1. Create a Shape.Host VPS Instance

Click “Create” → “Instance”.

Select your preferred server location.

Shape.host instance form with the data center location selector highlighted.

Choose Debian 12 (64-bit) as the operating system.

Pick a plan with at least 2 CPUs, 4 GB RAM, and 20 GB SSD.

Shape.host instance form with the operating system image selector highlighted.

Click Create Instance.

Shape.host instance form with the Create Instance button highlighted.

Copy the IP address from the Resources section.

Shape.host Resources dashboard with the server IP address highlighted.

2. Connect to Your VPS

On Linux/macOS

ssh root@your-server-ip

On Windows

On Windows 10/11 PowerShell: ssh root@your-server-ip
On older versions, use PuTTY and log in with root credentials.

3. Update the System and Install Dependencies

Update and upgrade packages:

apt update
apt upgrade

Terminal showing APT package management commands and output.

Install Apache web server:

apt install apache2

Install MariaDB:

apt install mariadb-server mariadb-client

Terminal showing PM2 application process management output.

Install PHP with required extensions:

apt install php php-cli php-mysql php-curl php-mbstring php-xml php-gd php-zip php-imagick unzip wget

4. Configure MariaDB

Secure MariaDB:

mysql_secure_installation

Terminal showing mysql commands or output during Configure MariaDB.

Log into MariaDB:

mysql -u root -p

Run the following SQL commands:

CREATE DATABASE boxbilling_db;
CREATE USER 'boxbilling_user'@'localhost' IDENTIFIED BY 'StrongPassword123!';
GRANT ALL PRIVILEGES ON boxbilling_db.* TO 'boxbilling_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Terminal showing SQL database and user configuration commands.

5. Install BoxBilling

Navigate to the web root:

cd /var/www/html

Download BoxBilling:

wget https://github.com/boxbilling/boxbilling/releases/latest/download/boxbilling.zip -O boxbilling.zip

Terminal showing file download commands and transfer output.

Unzip the archive:

unzip boxbilling.zip -d boxbilling

Set proper permissions:

chown -R www-data:www-data /var/www/html/boxbilling
chmod -R 755 /var/www/html/boxbilling

Terminal showing file ownership or permission commands.

6. Configure Apache Virtual Host

Create a virtual host file:

nano /etc/apache2/sites-available/boxbilling.conf

Paste:

<VirtualHost *:80>
    ServerName yourdomain.com
    DocumentRoot /var/www/html/boxbilling

    <Directory /var/www/html/boxbilling>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/boxbilling_error.log
    CustomLog ${APACHE_LOG_DIR}/boxbilling_access.log combined
</VirtualHost>

Terminal showing web server configuration text.

Enable the site and rewrite module:

a2ensite boxbilling.conf
a2enmod rewrite
systemctl restart apache2

Terminal showing systemd service management commands or output.

7. Adjust PHP Settings

Edit PHP configuration (adjusting path for installed PHP version):

nano /etc/php/*/apache2/php.ini

Set:

memory_limit = 256M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300

Restart Apache:

systemctl restart apache2

8. Configure Data Directories

Create cache and upload directories:

mkdir -p /var/www/html/boxbilling/bb-data/cache
mkdir -p /var/www/html/boxbilling/bb-data/uploads

Assign ownership and permissions:

chown -R www-data:www-data /var/www/html/boxbilling/bb-data
chmod -R 775 /var/www/html/boxbilling/bb-data

9. Enable SSL

Install Certbot:

apt install certbot python3-certbot-apache

Generate SSL certificate:

certbot --apache -d debian-tutorials.shape.host

Terminal showing Certbot certificate commands and messages.

10. Final Steps

Remove the installer for security:

rm -rf /var/www/html/boxbilling/install

Now, open your browser and go to:

https://debian-tutorials.shape.host

Follow the web-based installer to finish setup.

Once you’ve copied the BoxBilling files to your Debian 12 web server, open http://your-domain/install/install.php in your browser. The setup wizard will take you through four steps:

Preparation – The installer checks your Debian 12 PHP environment and required extensions. Accept the license terms and click Next.

Database Configuration – Provide the database host, name, user and password you created on Debian 12. Click Next to initialize the tables.

BoxBilling database connection settings.

Administrator Account – Create your BoxBilling admin user by entering a username, email address and a strong password. Click Next.

Finish – When the success screen appears, delete the install directory, change bb-config.php to read-only (chmod 644), and set up the recommended cron job.

After these steps you can log in at http://your-domain/bb-admin with the admin credentials you just created.

BoxBilling dashboard with statistics and activity charts.

This tutorial was created and tested on a Shape.Host Linux SSD VPS.

With Shape.Host you get:

High-performance Cloud VPS across global locations
Support for Debian, Ubuntu, Rocky Linux, AlmaLinux
One-click scaling for CPU, RAM, and storage
Features like snapshots, backups, and monitoring

Deploy your own BoxBilling server today at https://shape.host.