Skip to main content

⚙️ Install 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.

info

This guide will install the latest preview 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). 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)
  • The following PHP extensions (the guide above also has a section that covers installing PHP extensions): pdo_mysql, curl, zlib, gettext, openssl
  • MariaDB 10.3 or later, or MySQL 8 or later (guide to install MariaDB)

Instructions​

info

If you need help writing your nginx config file, or just want to check what you have, then you can use the Configuration file generator

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 or copy the example config from GitHub
  • 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 systemctl restart nginx

Installing FOSSBilling​

  • Download the latest FOSSBilling release 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
  • Setup the database under the database tab
  • 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