Introduction

FOSSBilling is an open-source billing solution that is perfect for managing your subscriptions, invoices, and payments. In this guide, we’ll walk you through setting up FOSSBilling on your VPS using Docker, making the process easier and more efficient. Docker will help you deploy FOSSBilling in isolated containers, ensuring a smooth installation and simplified management.

Let’s get started with a step-by-step guide to install FOSSBilling on your server using Docker, Docker Compose, and MariaDB for the database.

Prerequisites

Before you begin, make sure you have the following:

  • A VPS running Ubuntu 24 (or similar version).
  • A non-root user with sudo privileges (for security purposes).
  • Docker and Docker Compose installed.
  • A domain (optional, for production use) pointing to your VPS.
  • Basic knowledge of the command line interface (CLI).

Step 1: Update Your System

Before we begin, it’s essential to update your system to ensure all packages are up to date. This will help avoid conflicts during the installation process.

sudo apt update && sudo apt upgrade -y


This will update all system packages.

Step 2: Install Docker and Docker Compose

FOSSBilling will run in Docker containers, so you’ll need to install Docker and Docker Compose.

  1. Install Docker:

    sudo apt install docker.io -y


  2. Install Docker Compose:

    sudo apt install docker-compose -y


  3. Allow Docker to run without sudo:

    sudo usermod -aG docker $USER

    newgrp docker


    This allows you to run Docker commands without needing sudo.

  4. Verify the Installation:

    Check the Docker and Docker Compose versions to ensure they were installed correctly:

    docker --version

    docker-compose –version


Step 3: Set Up FOSSBilling with Docker Compose

Now that Docker and Docker Compose are installed, let’s set up FOSSBilling.

  1. Create a directory for FOSSBilling:

    mkdir ~/fossbilling && cd ~/fossbilling


  2. Create the Docker Compose file:

    You’ll need to create a docker-compose.yml file to define the services for FOSSBilling and MariaDB.

    nano docker-compose.yml


    Add the following content to the file:

    version: '3.8'

    services:

    fossbilling:

    image: fossbilling/fossbilling:latest

    container_name: fossbilling

    ports:

    – “8080:80”

    volumes:

    – fossbilling_data:/var/www/html

    environment:

    FOSSBILLING_DB_HOST: db

    FOSSBILLING_DB_USER: fossbilling

    FOSSBILLING_DB_PASSWORD: fossbillingpass

    FOSSBILLING_DB_NAME: fossbilling

    restart: unless-stopped

    depends_on:

    – db

    db:

    image: mariadb:latest

    container_name: fossbilling_db

    environment:

    MYSQL_ROOT_PASSWORD: rootpass

    MYSQL_DATABASE: fossbilling

    MYSQL_USER: fossbilling

    MYSQL_PASSWORD: fossbillingpass

    volumes:

    – db_data:/var/lib/mysql

    restart: unless-stopped

    volumes:

    fossbilling_data:

    db_data:


    • This configuration sets up two containers: one for FOSSBilling (fossbilling) and one for the MariaDB database (db).
    • Make sure to replace the database password and other credentials if necessary.

  3. Start the Containers:

    Run the following command to start FOSSBilling and its database container:

    docker-compose up -d


  4. Verify the Containers Are Running:

    You can check if the containers are running by using the following command:

    docker ps


    You should see both the FOSSBilling container and the MariaDB container listed.

Step 4: Access FOSSBilling Setup Wizard

FOSSBilling is now running in Docker. To complete the setup, open your browser and navigate to:

http://your-server-ip:8080


Follow the installation wizard:

  1. Database Configuration:

    • Database Host: db
    • Database Name: fossbilling
    • Database User: fossbilling
    • Database Password: fossbillingpass

  2. Admin User:

    • Create your admin account by providing an email and password.

Once completed, you will see a success message confirming that FOSSBilling has been successfully installed.

Step 5: Final Configuration

  1. Remove the Installer Folder:

    After installation, you should delete the installer folder for security reasons:

    rm -rfv /var/www/html/install


  2. Change Config File Permissions:

    Set the config.php file to read-only to enhance security:

    chmod 644 /var/www/html/config.php


  3. Set Up Cron Jobs:

    Add the following cron job to run the FOSSBilling cron script every 5 minutes:

    crontab -e


    Add this line to the crontab file:

    */5 * * * * php /var/www/html/cron.php


Step 6: Secure FOSSBilling with SSL (Optional but Recommended)

If you are using a domain (e.g., billing.gethostpro.com), it’s a good idea to secure your FOSSBilling installation with SSL.

  1. Install Nginx Proxy Manager: If you haven’t already, install Nginx Proxy Manager to handle reverse proxies and SSL certificates for your domain.

  2. Configure Nginx Proxy Manager:

    • Add a Proxy Host for billing.gethostpro.com to forward traffic to your Docker container (running FOSSBilling on port 8080).
    • Enable SSL with Let’s Encrypt and configure automatic redirection from HTTP to HTTPS.

Step 7: Set Up Backups for FOSSBilling

It’s essential to set up automated backups for your FOSSBilling files and MariaDB database to prevent data loss.

  1. Create a Backup Script:

    sudo nano /usr/local/bin/backup_fossbilling.sh


    Add the following content to the script:

    #!/bin/bash

    DB_NAME=fossbilling

    DB_USER=fossbilling

    DB_PASSWORD=fossbillingpass

    BACKUP_DIR=/home/youruser/backups

    DATE=$(date +\%Y-\%m-\%d_\%H\%M)

    mysqldump -u$DB_USER -p$DB_PASSWORD $DB_NAME > $BACKUP_DIR/db_backup_$DATE.sql

    tar -czf $BACKUP_DIR/fossbilling_files_$DATE.tar.gz /var/www/html

    find $BACKUP_DIR -type f -mtime +7 -exec rm -f {} \;


  2. Make the Script Executable:

    sudo chmod +x /usr/local/bin/backup_fossbilling.sh


  3. Set Up Cron Job for Backups:

    Schedule the backup to run daily at 2 AM:

    crontab -e


    Add the following line:

    0 2 * * * /usr/local/bin/backup_fossbilling.sh


Conclusion

Congratulations! You’ve successfully set up FOSSBilling on your VPS using Docker. Your FOSSBilling instance is now up and running, and you’ve implemented essential features like SSL, cron jobs, and automated backups.

If you want to explore more advanced configurations, such as custom billing features, performance optimizations, or advanced security measures, feel free to dive deeper into the official FOSSBilling documentation.