Skip to content
Klutch.sh Docs

Deploying FOSSBilling

Introduction

FOSSBilling is a powerful, free, and open-source billing and client management system designed for hosting companies, web agencies, and service providers. As a fork of BoxBilling, FOSSBilling continues the legacy with active development, modern features, and a focus on extensibility.

FOSSBilling provides everything you need to run a professional billing operation:

  • Automated Billing - Recurring invoices, payment reminders, and subscription management
  • Client Portal - Self-service customer dashboard for managing services and invoices
  • Product Management - Flexible product catalog with custom pricing and billing cycles
  • Payment Gateway Integration - Supports PayPal, Stripe, and 40+ payment processors
  • Support Ticket System - Built-in helpdesk with email piping and canned responses
  • Domain Management - Integration with domain registrars for automated provisioning
  • Hosting Integration - cPanel, Plesk, DirectAdmin, and custom server integrations
  • Extensible Architecture - Plugin system for custom modules and integrations
  • Multi-Currency Support - Accept payments in multiple currencies
  • Invoice Generation - Professional PDF invoices with customizable templates

Why Deploy FOSSBilling on Klutch.sh?

Deploying FOSSBilling on Klutch.sh gives you several advantages:

  • Fast Setup - Deploy in minutes with automatic Dockerfile detection
  • Persistent Storage - Reliable volume management for billing data and uploads
  • Scalable Infrastructure - Handle growing client bases without infrastructure headaches
  • HTTPS by Default - Secure connections for payment processing and client data
  • Custom Domains - Professional branding with your own domain
  • GitHub Integration - Version control and automated deployments from your repository
  • Cost-Effective - Predictable pricing without hidden infrastructure costs

Prerequisites

Before starting, make sure you have:

Preparing Your FOSSBilling Repository

1. Create a Project Directory

Start by creating a new directory for your FOSSBilling deployment:

Terminal window
mkdir fossbilling-klutch
cd fossbilling-klutch
git init

2. Create the Dockerfile

Create a Dockerfile in your project root with the following comprehensive configuration:

# Multi-stage build for optimized FOSSBilling deployment
FROM php:8.2-apache as base


# Install system dependencies
RUN apt-get update && apt-get install -y \
    libfreetype6-dev \
    libjpeg62-turbo-dev \
    libpng-dev \
    libzip-dev \
    libicu-dev \
    libonig-dev \
    libxml2-dev \
    libcurl4-openssl-dev \
    git \
    unzip \
    wget \
    && rm -rf /var/lib/apt/lists/*


# Install PHP extensions required by FOSSBilling
RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) \
    gd \
    pdo \
    pdo_mysql \
    mysqli \
    zip \
    intl \
    mbstring \
    xml \
    curl \
    opcache


# Enable Apache modules
RUN a2enmod rewrite headers expires deflate


# Configure PHP for production
RUN { \
    echo 'opcache.enable=1'; \
    echo 'opcache.memory_consumption=128'; \
    echo 'opcache.interned_strings_buffer=8'; \
    echo 'opcache.max_accelerated_files=4000'; \
    echo 'opcache.revalidate_freq=60'; \
    echo 'opcache.fast_shutdown=1'; \
    echo 'upload_max_filesize=64M'; \
    echo 'post_max_size=64M'; \
    echo 'memory_limit=256M'; \
    echo 'max_execution_time=300'; \
    } > /usr/local/etc/php/conf.d/custom.ini


# Set working directory
WORKDIR /var/www/html


# Download and install FOSSBilling
RUN wget -O fossbilling.zip https://github.com/FOSSBilling/FOSSBilling/releases/latest/download/FOSSBilling.zip \
    && unzip fossbilling.zip \
    && rm fossbilling.zip \
    && chown -R www-data:www-data /var/www/html \
    && chmod -R 755 /var/www/html


# Configure Apache DocumentRoot
RUN sed -i 's!/var/www/html!/var/www/html!g' /etc/apache2/sites-available/000-default.conf \
    && sed -i 's!/var/www/html!/var/www/html!g' /etc/apache2/apache2.conf


# Create necessary directories with proper permissions
RUN mkdir -p /var/www/html/data \
    /var/www/html/logs \
    /var/www/html/uploads \
    && chown -R www-data:www-data /var/www/html/data \
    /var/www/html/logs \
    /var/www/html/uploads \
    && chmod -R 775 /var/www/html/data \
    /var/www/html/logs \
    /var/www/html/uploads


# Apache configuration for FOSSBilling
RUN echo '<Directory /var/www/html>\n\
    Options Indexes FollowSymLinks\n\
    AllowOverride All\n\
    Require all granted\n\
</Directory>' >> /etc/apache2/apache2.conf


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD curl -f http://localhost/ || exit 1


# Expose port 80
EXPOSE 80


# Start Apache
CMD ["apache2-foreground"]

3. Create an Apache Virtual Host Configuration (Optional)

For advanced Apache configuration, create an apache-vhost.conf file:

<VirtualHost *:80>
    ServerAdmin admin@example.com
    DocumentRoot /var/www/html


    <Directory /var/www/html>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>


    # Security headers
    Header set X-Content-Type-Options "nosniff"
    Header set X-Frame-Options "SAMEORIGIN"
    Header set X-XSS-Protection "1; mode=block"
    Header set Referrer-Policy "strict-origin-when-cross-origin"


    # Logging
    ErrorLog ${APACHE_LOG_DIR}/fossbilling-error.log
    CustomLog ${APACHE_LOG_DIR}/fossbilling-access.log combined


    # PHP security settings
    php_flag display_errors off
    php_flag log_errors on
    php_value error_log /var/log/apache2/php-error.log
</VirtualHost>

4. Create a .dockerignore File

Create a .dockerignore file to exclude unnecessary files from the Docker build:

.git
.gitignore
.env
.env.*
node_modules
npm-debug.log
*.md
.DS_Store
.vscode
.idea

5. Create a .gitignore File

Create a .gitignore to prevent sensitive files from being committed:

# Environment files
.env
.env.*


# FOSSBilling data directories
data/
logs/
uploads/


# Docker
.dockerignore


# OS files
.DS_Store
Thumbs.db


# IDE
.vscode/
.idea/
*.swp
*.swo

6. Initialize Git and Push to GitHub

Initialize your repository and push to GitHub:

Terminal window
git add .
git commit -m "Initial FOSSBilling deployment setup"
git branch -M main
git remote add origin https://github.com/yourusername/fossbilling-klutch.git
git push -u origin main

Deploying on Klutch.sh

Now that your repository is ready, deploy FOSSBilling on Klutch.sh:

  1. Navigate to the Klutch.sh Dashboard

    Go to klutch.sh/app and log into your account.

  2. Create a New Project

    Click “New Project” and give it a descriptive name like fossbilling-production.

  3. Create a New App

    Within your project, click “New App” and select your GitHub repository containing the FOSSBilling Dockerfile.

  4. Configure Deployment Settings

    • Branch: Select main (or your preferred deployment branch)
    • Traffic Type: Select HTTP (FOSSBilling is a web application)
    • Port: Set to 80 (the internal port Apache listens on)

  5. Configure Environment Variables

    While FOSSBilling uses a web-based installer, you can pre-configure database settings via environment variables. Add the following:

    DB_TYPE=mysql
    DB_HOST=your-mysql-app.klutch.sh
    DB_PORT=8000
    DB_NAME=fossbilling
    DB_USER=fossbilling_user
    DB_PASSWORD=your_secure_password

    Note: Replace the database connection details with your actual MySQL deployment. See our MySQL deployment guide for setting up a database.

  6. Attach Persistent Volumes

    FOSSBilling requires persistent storage for:

    • Application Data: /var/www/html/data (10GB recommended)
    • Log Files: /var/www/html/logs (5GB recommended)
    • Uploaded Files: /var/www/html/uploads (20GB recommended)

    Click “Add Volume” for each mount path:

    1. Mount Path: /var/www/html/data, Size: 10GB
    2. Mount Path: /var/www/html/logs, Size: 5GB
    3. Mount Path: /var/www/html/uploads, Size: 20GB

  7. Deploy the Application

    Click “Deploy” to start the deployment. Klutch.sh will automatically detect your Dockerfile, build the image, and deploy your container.

  8. Monitor the Deployment

    Watch the build logs in real-time to ensure everything deploys correctly. The initial build may take 5-10 minutes.

Initial FOSSBilling Setup

Once deployed, complete the FOSSBilling installation:

1. Access the Installer

Navigate to your deployed app URL (e.g., https://example-app.klutch.sh) in your browser. You’ll be redirected to the FOSSBilling installer.

2. System Requirements Check

The installer will check if all required PHP extensions are installed. If using the provided Dockerfile, all requirements should be met.

3. Database Configuration

Enter your database connection details:

  • Database Type: MySQL
  • Database Host: your-mysql-app.klutch.sh (or your MySQL service address)
  • Database Port: 8000 (for Klutch.sh MySQL deployments)
  • Database Name: fossbilling
  • Database Username: fossbilling_user
  • Database Password: Your secure password

4. Administrator Account

Create your admin account:

  • Email: Your administrator email
  • Password: Choose a strong password
  • Name: Your full name

5. Complete Installation

Click “Install” to complete the setup. FOSSBilling will create the necessary database tables and configure the application.

6. Remove Install Directory

For security, after installation completes, you should remove or rename the install directory. Since you’re using Docker, this is automatically handled on container restart.

Configuration

Database Configuration File

FOSSBilling stores its configuration in /var/www/html/config.php. Since this is inside your persistent volume, you can modify it after deployment if needed:

<?php
return [
    'db' => [
        'type' => 'mysql',
        'host' => 'your-mysql-app.klutch.sh',
        'port' => 8000,
        'name' => 'fossbilling',
        'user' => 'fossbilling_user',
        'password' => 'your_secure_password',
    ],
    'url' => 'https://example-app.klutch.sh',
    'admin_area_prefix' => '/admin',
    'security' => [
        'mode' => 'strict',
    ],
    'debug' => false,
    'log_to_db' => true,
    'path_logs' => '/var/www/html/logs/',
];

Environment Variables Reference

VariableDescriptionExample
DB_TYPEDatabase typemysql
DB_HOSTDatabase hostmysql-app.klutch.sh
DB_PORTDatabase port8000
DB_NAMEDatabase namefossbilling
DB_USERDatabase userfossbilling_user
DB_PASSWORDDatabase passwordSecureP@ssw0rd!
APP_URLApplication URLhttps://example-app.klutch.sh

Custom Domain Setup

To use your own domain with FOSSBilling:

  1. Go to your app settings in the Klutch.sh dashboard
  2. Navigate to the “Domains” section
  3. Add your custom domain (e.g., billing.yourdomain.com)
  4. Update your DNS records as shown
  5. Update the url parameter in FOSSBilling’s config.php

Learn more in our Custom Domains documentation.

Using FOSSBilling

Admin Panel Access

Access the FOSSBilling admin panel at:

https://example-app.klutch.sh/admin

Log in with the administrator credentials you created during installation.

Client Portal Access

Clients access their portal at:

https://example-app.klutch.sh

They can register, manage services, view invoices, and submit support tickets.

Creating Your First Product

  1. Log into the admin panel
  2. Navigate to **Products > New Product**
  3. Configure product details: 
    // Example shared hosting product configuration
    Product Name: Shared Hosting - Basic
    Product Type: Hosting
    Price: $9.99/month
    Setup Fee: $0.00
    Billing Cycle: Monthly
  4. Configure provisioning (if using cPanel/Plesk integration)
  5. Click **"Save"** to create the product

Setting Up Payment Gateways

FOSSBilling supports multiple payment gateways:

PayPal Configuration

  1. Navigate to **Configuration > Payment Gateways**
  2. Enable **PayPal**
  3. Configure settings: 
    Email: your-paypal-email@example.com
    API Username: your_api_username
    API Password: your_api_password
    API Signature: your_api_signature
    Sandbox Mode: No (for production)
  4. Save and test the gateway

Stripe Configuration

  1. Navigate to **Configuration > Payment Gateways**
  2. Enable **Stripe**
  3. Configure settings: 
    Publishable Key: pk_live_xxxxxxxxxxxxx
    Secret Key: sk_live_xxxxxxxxxxxxx
    Webhook Secret: whsec_xxxxxxxxxxxxx
  4. Set up webhooks in your Stripe dashboard pointing to: 
    https://example-app.klutch.sh/stripe-webhook

Email Configuration

Configure SMTP for transactional emails:

  1. Navigate to **Configuration > Email**
  2. Select **SMTP** as the mail transport
  3. Configure SMTP settings: 
    SMTP Host: smtp.gmail.com (or your SMTP provider)
    SMTP Port: 587
    SMTP Username: your-email@gmail.com
    SMTP Password: your-app-password
    Encryption: TLS
  4. Test email sending from the configuration page

Cron Jobs for Automation

FOSSBilling requires a cron job for automated tasks like invoice generation, payment reminders, and scheduled actions.

Since you’re using Docker on Klutch.sh, you have two options:

Option 1: External Cron Service

Use a service like cron-job.org to call:

https://example-app.klutch.sh/cron.php

Schedule it to run every 5 minutes.

Option 2: Add Cron to Dockerfile

Modify your Dockerfile to include cron:

# Install cron
RUN apt-get update && apt-get install -y cron


# Add cron job
RUN echo "*/5 * * * * www-data /usr/local/bin/php /var/www/html/cron.php > /dev/null 2>&1" >> /etc/crontab


# Modified CMD to start both cron and Apache
CMD cron && apache2-foreground

Production Best Practices

Security Hardening

1. Change Admin URL

Modify the admin area prefix in config.php:

'admin_area_prefix' => '/my-secret-admin',

2. Enable HTTPS Only

In config.php, enforce HTTPS:

'security' => [
    'mode' => 'strict',
    'force_https' => true,
],

3. Implement Strong Passwords

Configure password requirements in Configuration > Security:

  • Minimum length: 12 characters
  • Require uppercase, lowercase, numbers, and symbols
  • Enable two-factor authentication for admin accounts

4. Regular Security Updates

Keep FOSSBilling updated:

Terminal window
# In your repository, update the Dockerfile to the latest release
RUN wget -O fossbilling.zip https://github.com/FOSSBilling/FOSSBilling/releases/download/vX.X.X/FOSSBilling.zip

Then redeploy through Klutch.sh.

5. Disable Debug Mode

Ensure debug mode is off in production:

'debug' => false,
'log_to_db' => true,

Database Optimization

1. Regular Backups

Set up automated database backups. If using our MySQL deployment, enable automatic backups in the Klutch.sh dashboard.

2. Database Indexing

FOSSBilling automatically creates necessary indexes, but monitor slow queries:

-- Check slow queries
SHOW PROCESSLIST;


-- Analyze table performance
ANALYZE TABLE invoices;
ANALYZE TABLE orders;

3. Archive Old Data

Periodically archive old invoices and logs to keep the database performant.

Performance Optimization

1. Enable Caching

FOSSBilling supports file-based caching. Enable it in config.php:

'cache' => [
    'enabled' => true,
    'adapter' => 'file',
    'ttl' => 3600,
],

2. Optimize PHP Configuration

The provided Dockerfile already includes OPcache optimization, but you can tune it further:

opcache.memory_consumption=256
opcache.max_accelerated_files=10000
opcache.validate_timestamps=0  # Disable in production

3. Use a CDN

For static assets (CSS, JS, images), consider using a CDN to reduce server load.

4. Database Connection Pooling

For high-traffic sites, consider implementing connection pooling in your MySQL deployment.

Monitoring and Logging

1. Application Logs

Monitor FOSSBilling logs at /var/www/html/logs/:

Terminal window
# View recent errors
tail -f /var/www/html/logs/error.log


# View application logs
tail -f /var/www/html/logs/application.log

2. Apache Logs

Monitor Apache access and error logs:

Terminal window
# Access logs
tail -f /var/log/apache2/access.log


# Error logs
tail -f /var/log/apache2/error.log

3. Health Monitoring

Set up external monitoring to check:

  • Website uptime and response time
  • Payment gateway connectivity
  • Email delivery success
  • Cron job execution

Use services like:

Backup Strategy

1. Database Backups

Implement daily automated backups:

Terminal window
# Example backup script (run on MySQL server)
mysqldump -h mysql-app.klutch.sh -P 8000 -u fossbilling_user -p fossbilling > backup_$(date +%Y%m%d).sql

2. Application Files Backup

Backup the following directories (stored in persistent volumes):

  • /var/www/html/data - Application data
  • /var/www/html/uploads - Client uploads
  • /var/www/html/config.php - Configuration file

3. Backup Retention

Implement a retention policy:

  • Daily backups: Keep for 7 days
  • Weekly backups: Keep for 4 weeks
  • Monthly backups: Keep for 12 months

Scaling Considerations

1. Vertical Scaling

For increased traffic, upgrade your Klutch.sh plan to get:

  • More CPU cores
  • Additional RAM
  • Faster storage I/O

2. Database Optimization

  • Optimize slow queries
  • Add indexes to frequently queried columns
  • Consider read replicas for reporting

3. Caching Layer

Implement Redis or Memcached for session storage and caching:

'cache' => [
    'enabled' => true,
    'adapter' => 'redis',
    'host' => 'redis-app.klutch.sh',
    'port' => 8000,
],

Troubleshooting

Installation Issues

Problem: “Cannot connect to database”

Solution:

  • Verify database credentials in environment variables
  • Ensure MySQL deployment is running and accessible
  • Check that the database exists and user has proper permissions
  • For Klutch.sh MySQL deployments, ensure you’re using port 8000
Terminal window
# Test database connection
mysql -h your-mysql-app.klutch.sh -P 8000 -u fossbilling_user -p fossbilling

Problem: “Permission denied” errors

Solution:

  • Ensure persistent volumes are properly mounted
  • Check directory permissions in the container:
Terminal window
# Exec into container (if needed for debugging)
docker exec -it container_id /bin/bash
chown -R www-data:www-data /var/www/html/data
chmod -R 775 /var/www/html/data

Performance Issues

Problem: Slow page load times

Solution:

  • Enable OPcache (included in our Dockerfile)
  • Check database query performance
  • Enable FOSSBilling’s built-in caching
  • Optimize database indexes
  • Consider upgrading your Klutch.sh plan

Problem: High memory usage

Solution:

  • Reduce PHP memory limit if too high
  • Optimize Apache configuration
  • Implement external caching (Redis/Memcached)

Payment Gateway Issues

Problem: PayPal payments not processing

Solution:

  • Verify API credentials are correct
  • Check that IPN (Instant Payment Notification) is enabled
  • Ensure webhook URL is accessible: https://example-app.klutch.sh/ipn/paypal
  • Test in sandbox mode first

Problem: Stripe webhooks failing

Solution:

  • Verify webhook secret in configuration
  • Check webhook logs in Stripe dashboard
  • Ensure webhook endpoint is: https://example-app.klutch.sh/stripe-webhook
  • Verify HTTPS is properly configured

Email Issues

Problem: Emails not sending

Solution:

  • Verify SMTP credentials and settings
  • Check if port 587 (TLS) or 465 (SSL) is accessible
  • Test with a simple SMTP testing tool
  • Review error logs at /var/www/html/logs/error.log
  • For Gmail, ensure “Less secure app access” is enabled or use App Passwords

Cron Job Issues

Problem: Automated tasks not running

Solution:

  • Verify cron is configured and running
  • Check cron execution logs
  • Test cron.php manually: php /var/www/html/cron.php
  • Ensure the cron URL is accessible externally (if using external cron service)

Update Issues

Problem: Update breaks the application

Solution:

  • Always backup before updating
  • Test updates in a staging environment first
  • Review FOSSBilling release notes for breaking changes
  • Restore from backup if needed

Additional Resources

Official Documentation

Extensions and Plugins

Payment Gateway Documentation

Community and Support

Ready to start billing? Deploy FOSSBilling on Klutch.sh today and start managing your clients, invoices, and payments with a professional open-source billing system. Need help with database setup? Check out our MySQL deployment guide to get your database running first.