OpenSourceBilling is a Rails 6 invoicing app for small agencies

The scope is a small business billing desk, not a full accounting suite

OpenSourceBilling is a simple web application to create and send invoices, receive payments, manage clients and companies, and it generates reports of item sales, payments and collected revenues. It supports multiple languages and multiple currencies.

That summary is the whole product. It is invoicing with the surrounding records a small business needs: clients, companies, the products or items being billed for, and the money coming back in. The reports named in the feature list are Payments Collected, Aged Accounts Receivable, Revenue By Client and Items Sales.

One feature in that list matters for anyone with more than one business entity. It is possible to manage billing for multiple sister companies under one account, which is a common structure for consultancies and agencies that invoice different clients through different entities but want one dashboard.

The application is written in Ruby on Rails 6.0.2.2 on Ruby 2.7.1, and the README describes setup on Ubuntu 14.04 LTS and on Windows 10. The declared primary language in the repository is HTML, which tells you where the effort went: this is a server rendered Rails application with a JavaScript layer on top, not a single page application with a separate API.

The audience is therefore someone who runs a small business and wants to send a proper invoice this afternoon, and who is willing to run a Rails app on a server of their own.

Invoices, estimates and time tracking feed each other

The feature list is long but it clusters into a few flows, and the interesting part is how they connect.

The core flow is create and send invoices to clients, receive payments against sent invoices, and track partial payments, so an invoice can be paid in instalments and the application keeps a running balance. Estimates sit upstream of that: you send an estimate, the client accepts it, and you convert the estimate to an invoice. Both can be exported to PDF.

Recurring invoices cover the case where the same work is billed on a cycle, which is the feature that turns this from a document generator into a system.

Time tracking is where the connection to projects becomes visible. The application tracks time for running projects and can generate an invoice from the logged hours, so the billing figure is derived from work recorded rather than typed in twice. That is the design that makes the product worth its weight for an agency.

The rest of the interface is the usual furniture of a list based admin: filters for listing pages, a dashboard with graphs and key metrics, a customer portal so a client can see their own invoices, and a responsive, adaptive user interface.

Full text search is powered by elastic search, which is an unusual dependency for a Rails application of this vintage and is worth noting as a requirement before you install rather than after you need it.

Installation is an eleven step configuration chain before anything runs

The setup guide in the README is long and specific, and it is a manual chain rather than a single installer. The order matters, because the application will not start until the database, the key files and the secret are all in place.

Clone the code, then install the Ruby dependencies with bundler and the JavaScript ones with yarn:

git clone https://github.com/vteams/open-source-billing
cd open-source-billing
bundle install
yarn install

The configuration file is created from a template, and PayPal credentials are optional within it:

paypal:
  signature: YOUR_PAYPAL_SIGNATURE
  business: YOUR_PAYPAL_BUSINESS

The same file carries the application host and protocol, and the path to the wkhtmltopdf binary that renders PDFs, which the guide finds with which wkhtmltopdf and which you paste in as wkhtmltopdf_path.

A secret key has to be generated with rake secret and pasted into the encryption_key value in config.yml. The database has its own template, config/database.yml.copy, where you set the MySQL user and password, and then the schema is created and seeded with the Rails tasks:

rails db:create
rails db:migrate
rails db:seed

Note the order. db:create creates the database named in database.yml, db:migrate builds the schema, and db:seed loads the default values the application expects to find. Skipping the seed step is a common way to get an empty application that appears broken.

delayed_job is required for mail, not optional polish

The run section is short and it contains the step most self hosted deployments get wrong.

Before the web server starts, a background worker has to be running, because the application needs it for email delivery and for the other background tasks required for proper functionality of OSB. The command is:

RAILS_ENV=development  bin/delayed_job start

That is a foreground process, which means in development you run it in one terminal and the Rails server in another. In production, the guide does not say how to run it, only that you can put Apache, Nginx or any other web and application server of your choice in front of the application to run it in production mode. A supervisor or a service manager for the worker is left to you.

The SMTP configuration is also not in config.yml. To set smtp_settings you go into the application settings, open a company edit form by clicking on a company, and provide your details in the Mail Config section. That coupling of mail configuration to a per company record is easy to miss, and it means a multi company installation can send mail through different SMTP accounts.

Together these two facts define the operational shape of the product: a Rails server plus a separate long running worker, with mail settings living in the database rather than in a file.

Payments, imports and QuickBooks cover the edges of the invoice flow

Payment handling is listed as receiving payments through Paypal and credit card, and the Paypal block in config.yml is the first thing you are asked to fill in, which tells you how central it is to the product's story.

The QuickBooks configuration is separate and uses OAuth application credentials, an oauth_consumer_key and an oauth_consumer_secret, edited in the same config.yml file. So does the migration path from other tools, with data import from Freshbooks and QuickBooks named in the feature list, which is the practical answer to the question every switcher asks: how do I get my existing clients and invoices in.

The reporting layer closes the loop. Payments Collected and Aged Accounts Receivable are the two reports a business actually runs, and the second one is the report that chases money, showing what is overdue and by how much.

The customer portal is the part that reduces your own workload. A client who can look up their own invoices does not email you asking what they owe, and the partial payment tracking gives the portal something meaningful to display.

What the feature list does not mention is an API for third party access, a multi currency payment story, or a dunning or subscription management workflow. The description says it supports multiple currencies, but the payment integrations named are PayPal and credit card, so multi currency appears to be a display and pricing feature rather than a multi currency settlement one.

The Docker compose file is a three service stack with an unusual port map

A compose file is included in the repository, and it describes a three service development stack rather than a production deployment.

services:
  db:
    image: mysql/mysql-server:latest
    ports:
      - "3308:3308"
  web:
    ports:
      - "8080:80"
  app:
    ports:
      - "3000:3000"

The database is a mysql/mysql-server:latest image with its credentials and database name set through environment variables, and the port mapping is 3308 on the host, not the default 3306, which avoids clashing with a MySQL already running on the machine. The web service builds from docker/web/Dockerfile and mounts an nginx configuration from docker/web/etc/nginx/conf.d/default.conf, publishing 8080 on the host. The app service builds from docker/app/Dockerfile, mounts the project directory at /myapp plus a named bundle volume, publishes 3000, and depends on the database. The web service depends on the app.

Two things about that arrangement deserve a note. The database name in the environment block is photo_app, which is a Rails generator default rather than a billing related name, so the image is configured for a generic app and the real database name comes from config/database.yml. And the whole stack is pinned to a latest tag for MySQL with the credentials written into the compose file, which is a development convenience and not something to copy into a deployment unchanged.

There is also a compose-dev.yaml file at the top level, so there are two compose variants to choose between.

Rails 6, Ruby 2.7 and webpack 4 date the codebase precisely

The stack is stated in the README and confirmed by the manifest. The application is developed in Ruby on Rails v6.0.2.2 and Ruby v2.7.1, MySQL is the database, and the JavaScript layer runs on Rails 6 with webpacker 5.3.0 and webpack 4.46.0, with jQuery 3.5.1, bootstrap 4.5, chart.js 2.9.3, fullcalendar, i18n-js, moment, intro.js and a set of loaders for CoffeeScript.

Those versions place the application in a specific moment. Rails 6.0 with Ruby 2.7 is a 2019 to 2020 stack, and webpack 4 with webpacker 5 is the pre webpack 5 era of the Rails asset pipeline. A Ruby 2.7.1 install is straightforward with RVM as the guide shows, but the version is long out of security support, and Rails 6.0 as a series is not the current one.

The repository itself has moved on from the guide. There is a Capfile and a Rakefile for deployment, a spec/ and a test/ directory, an entrypoint.sh, a docker/ directory with separate web and app images, a .browserslistrc, babel.config.js and postcss.config.js, a Gemfile.lock, and a package-lock.json next to a yarn.lock with a yarn-error.log committed alongside it. So the modernised Rails application files are present even though the documentation still describes Ruby 2.7.1 on Ubuntu 14.04 and a webpack 4 asset pipeline.

The licence is GPL-3.0, with the terms in LICENSE.md. For a self hosted business application that is a workable choice, and it is worth confirming the position on modification and redistribution before you change anything.

On maintenance, the last push was on 2026-05-06 and the repository is not archived, so work continues. The release tags are old though: v2.2-release in August 2020, v2.1-release in November 2018 and a 2.0 pre-release in July 2018. The README's own caveat calls the documented state the 2.0 release, which is behind even the 2.2 tag, and a demo instance is offered at demo.opensourcebilling.org.

Editorial conclusion

OpenSourceBilling fits a small agency or freelancer who wants invoices, estimates and time tracking in one place, and who can work with a MySQL backed Rails application that they host themselves. It does not fit a team that needs a modern stack, a supported release line or a rich API, since the newest tag is 2.2 from 2020 and the application runs on Rails 6.0.2.2 with Ruby 2.7.1 and a webpack 4 frontend. Before you deploy it, install Ruby 2.7.1 with RVM, run bundle install and yarn install, copy config/config.yml.copy and config/database.yml.copy, generate the encryption key with rake secret, and decide whether you will run delayed_job in the foreground, because the README states the background service is required for email delivery to work at all.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. vteams/open-source-billing on GitHub