Docs / Installation

Installing KBilling

KBilling runs on any server with PHP 8.2+ and MySQL. No Docker, no Node, no special extensions beyond the basics. Most installs take under ten minutes.

Requirements

• PHP 8.2 or newer with PDO MySQL, cURL, OpenSSL, JSON, mbstring, and sessions enabled
• MySQL 8.0+ (or MariaDB 10.5+), using InnoDB and utf8mb4
• HTTPS — KBilling enforces secure cookies, so set up a TLS certificate first (Let's Encrypt works fine)
• Enough disk space for invoices, backups, and downloads (a few GB is plenty to start)

Shared hosting is fine for small setups. For anything busier, a cheap VPS will feel snappier.

1. Upload the files

Download the release ZIP from your client area and upload it to your web root — or grab it with wget and unzip it:

cd /var/www/html
unzip kbilling-v<current-version>.zip
chown -R www-data:www-data /var/www/html

The web root should point at the folder containing index.php. Nothing outside that folder needs to be reachable.

2. Create a database

Create an empty database and a user with full rights to it:

CREATE DATABASE kbilling CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'kbilling'@'localhost' IDENTIFIED BY 'a-strong-password';
GRANT ALL PRIVILEGES ON kbilling.* TO 'kbilling'@'localhost';
FLUSH PRIVILEGES;

3. Run the installer

Open https://yourdomain.com/install/ in a browser and follow the steps:

1. The installer checks your PHP version and extensions
2. Enter the database name, user, and password from step 2
3. Create your admin account (use a strong password — you'll add 2FA next)
4. Confirm, and the installer writes configuration.php for you

When it finishes, delete the /install/ directory from the server. KBilling will remind you until you do.

4. Set up the cron job

The cron runs invoicing, provisioning, mail delivery, licensing synchronization, late fees, and lifecycle actions. Run the launcher every five minutes; each task decides when it is due:

crontab -e
# add this line:
*/5 * * * * /usr/bin/php /var/www/html/crons/cron.php >/dev/null 2>&1

Don't expose crons/ through the web server. The default .htaccess blocks it, but on nginx you should add a deny rule too.

5. First login

Sign in at https://yourdomain.com/admin/. You'll be asked to set up two-factor authentication with Google Authenticator or any TOTP app — scan the QR code and you're done.

Common problems

Blank page after install

Check that configuration.php exists and is readable by the web server user. Check the PHP error log.

"HTTPS required"

KBilling won't run over plain HTTP. Add a TLS certificate, or test locally with a self-signed cert.

Cron doesn't run

Run php crons/cron.php by hand and check for errors. Make sure the cron user can read the KBilling files.

Emails not sending

Set up SMTP in System Settings → Email. PHP mail() works but often lands in spam.