⭐️ We have just released an extension for Mollie. Check it out →
Documentation
Getting Started
Install Normally

Installing FOSSBilling

This article needs visual improvements. If you can provide screenshots or other helpful visuals, please help us improve it using the "Edit this page" button in the sidebar. Thanks!

Prerequisites

  • A domain or sub-domain dedicated to FOSSBilling (sub-folders are not applicable at the moment).
  • Your server must meet or exceed the system requirements (opens in a new tab).
  • A webserver running a configuration created for FOSSBilling (See examples below).

Webserver configurations

Except for Apache, the following configurations should be used as examples and treated as starting points for when installing FOSSBilling. They may have placeholders that need to be replaced or be incomplete in some way.

If you're using a server you didn't setup yourself / a control panel and you're unsure what type of webserver you are using, it's most likely Apache which will be the easiest to setup.

If you're unsure how to perform the basic setup for your chosen webserver (such as configuring virtual hosts), we recommend Googling what you are having issues with. There are some high quality guides by companies like Digital Ocean which can do a better job of describing the basic process than we can.

Good news! FOSSBilling includes the correct .htaccess file out-of-the box . Setup the domain as you normally would and then proceed with the installation steps.

If you are using OpenLiteSpeed, be sure to reload the associated service after installing so the new .htaccess file is loaded by the server.

Pre-installation steps

  1. Download the latest FOSSBilling release (opens in a new tab) from our downloads page. Be sure to not download a preview build unless that's specifically what you're after.
  2. Create a new MySQL database and database user for your FOSSBilling installation.
  3. If you intend to use SSL on your installation (which you should!), ensure it's setup and functioning before performing the installation process.
  4. When using products such as Cloudflare, ensure options like auto-minification for JS and CSS files is disabled.
  5. If you are using a reverse proxy, ensure your proxy is configured to send the X-Forwarded-Host and X-Forwarded-Proto headers to FOSSBilling.

Installation Steps

  1. Access the document root for your domain and ensure any placeholder files created by your control panel are deleted so they don't cause issues (placeholder pages, .htaccess files, etc).
  2. Upload the FOSSBilling release you previously downloaded and extract the contents into the document root. Your document root should now look similar to this:
├── data
├── install
├── library
├── locale
├── modules
├── themes
├── vendor
├── config-sample.php
├── cron.php
├── di.php
├── index.php
...
  1. Access the domain you've setup for FOSSBilling. If you are going to use SSL, ensure you access the domain via HTTPS so the application can automatically configure itself for HTTPS. You should automatically be redirected to domain.com/install/install.php.

If you see a page similar to this, you're in the right place! The FOSSBilling installer landing page

  1. Follow the on-screen steps to agree to the FOSSBilling license, enter your database credentials, and setup the login information for your administrator account.
  2. Ensure you correctly configure your default currency. The price format must contain {{price}} in order for it to work correctly as this is used as a placeholder value. Simply enter the currency symbol on either side of {{price}}.
  3. Click install. After a few moments, you should be presented with a success page.

Ran into an error after clicking install? You may need to manually empty the database you've created for FOSSBilling before trying again.

Post-installation Steps

After completing the steps inside of the FOSSBilling installer, you just need to configure the cronjob and then you're ready to get started within the software itself.

Configuring the cronjob

FOSSBilling relies on the cronjob to perform important actions such as handling renewals, expired orders, sending emails, and more. Because of this, it's critical that cron is configured correctly, is running reliably, and that it's setup to run frequently enough.

We recommend configuring cron to run once every 5 minutes. If 15 minutes goes past without cron executing, FOSSBilling will display a notification in the administrator panel. If you see this message, you need to resolve the issue as soon as possible. FOSSBilling warning about cron execution

Utilizing a local cronjob

The cronjob also needs to be run on a PHP version that FOSSBilling supports. If you are running into errors, you may be experiencing a common issue where your cronjob isn't being run on the same PHP version as your domain is configured for. For troubleshooting steps, please check this forum post (opens in a new tab) for some pointers.

FOSSBilling will display the correct cron command to utilize to run it's cronjob both on the installation complete page as well as in the administrator panel. If you ever need to find it again, navigate to Settings -> Scheduled Tasks (/admin/extension/settings/cron).

Cron settings - correct cron command

Utilizing a remote service to activate cron

If you find that you are unable to use a local cronjob to run cron, you may instead use a remote service to call a given URL to execute cron, but first you must enable the functionality. To do this navigate to Settings -> Scheduled Tasks (/admin/extension/settings/cron) and then enable the cron API endpoint and click on "update"

You will then be able to use the URL displayed on the page with an external service to automatically execute the cronjob.

Cron settings - remote URL

System RequirementsInstall using Docker