Install on Nginx

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.


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


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
  • 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.

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

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
  • 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/
  • 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' => ''
  • 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)