Installing on an Nginx Server

nginx is a popular pretty popular web server that can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache. In this guide, we'll guide you through installing FOSSBilling on an nginx server.

This guide will install the latest release. If you're planning to contribute to the development of FOSSBilling, it's strongly advised to build FOSSBilling from the main branch instead.

Prerequisites

You will need to have the following installed. Please take a moment now to make sure you are ready:

nginx (Install guide (opens in a new tab)). Please skip the "Setting Up Server Blocks" part, we'll cover that in this guide)
PHP 8.0 or later (Guide to install 8.1 on Ubuntu 22.04 (opens in a new tab))
The following PHP extensions (the guide above also has a section that covers installing PHP extensions): pdo_mysql, curl, zlib, openssl
MariaDB 10.3 or later, or MySQL 8 or later (guide to install MariaDB (opens in a new tab))

Instructions

If you need help writing your nginx config file, or just want to check what you have, you can use the Configuration file generator (opens in a new tab)

Create a server block (virtual host) for your website

Locate the following directory: /etc/nginx/sites-available
Create an empty config file (i.e fossbilling.conf)
Generate a configuration file for yourself using our new configuration generator (opens in a new tab) or copy the example config from GitHub (opens in a new tab)
Edit the config to match your needs (Replace server name, add the PHP Fast CGI Pass, replace fastcgi_pass php; with fastcgi_pass unix:/run/php/phpx.x-fpm.sock; or any of the examples shown below)
fastcgi_pass unix:/var/run/phpx.x-fpm.sock; , fastcgi_pass unix:/var/run/php/phpx.x-fpm.sock;
Change anything else you may need (SSL certificates, changing ports, etc)
Change servername to your domain (i.e fossbilling.example.com)
Run sudo ln -s /etc/nginx/sites-available/fossbilling.conf /etc/nginx/sites-enabled/
Run sudo systemctl restart nginx

Setup Database

Please note that 'RANDOM_STRONG_PASSWORD' should be replaced with an actual random and strong password. We want to clarify that it is not mandatory to use the username 'fossbillinguser' for the database. However, it is highly recommended to avoid using the root user, so instead please create and use a separate user with limited privileges for security reasons.

bash

  mysql -u root -p
  CREATE DATABASE fossbilling;
  CREATE USER 'fossbillinguser'@'localhost' IDENTIFIED BY 'RANDOM_STRONG_PASSWORD';
  GRANT ALL PRIVILEGES ON fossbilling.* TO 'fossbillinguser'@'localhost';
  FLUSH PRIVILEGES;

Installing FOSSBilling

Download the latest FOSSBilling release (opens in a new tab) and then upload the files in the archive to the public directory of the site on your server, keeping the file structure as it is inside the archive.
Navigate to to the install page on your domain (i.e fossbilling.example.com/install)
Ensure the following have public write access, /var/www/.../src/config.php, /var/www/.../src/data/cache, /var/www/.../src/data/log, /var/www/.../src/data/uploads
Run chown -R www-data 644 /var/www/fossbilling.org/src/
Setup the database under the database tab with fossbillinguser
Continue with Installation and setup
Make /var/www/.../src/config.php read only
Setup the admin username and password
Click Finish and you are done!

Common Problems

FOSSBilling Displays Strangely / Mixed Content Warning

Locate /var/www/.../src/config.php
Locate 'url' => 'http://example.com/'
Replace 'http' with 'https'
Restart nginx sudo systemctl restart nginx

502 Bad Gateway after installinmg

Make sure that you have installed phpx.x-fpm. If not:

Run sudo apt-get install phpx.x-fpm (Replace x.x with your current PHP version php -v)

Install on Apache Install using Docker