BillRun appllication is used MongoDB as its data store to allow data growth as well as flexibility for digesting billing lines of any structure or volume.
Following the official instructions in the MongoDB official documentation (CentOS or Ubuntu) or follow the short instructions in the next sections.
For full scaleout architecture which required 10s of millions of billing lines and more, please follow the official MongoDB cluster installation guide, instead of single instance as described in this guide. In addition, we recommend to follow the linux production notes of MongoDB and configure advanced settings for big cluster environment.
In case you're using MongoDB cluster, BillRun application server will be on the same server as the MongoDB Router service (mongos) to maximize availability of the application.
Import the public key used by the package management system:
$ curl -fsSL https://pgp.mongodb.com/server-8.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg --dearmor
Create the repo file /etc/apt/sources.list.d/mongodb-org-4.4.list.
For Ubuntu:
$ echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu noble/mongodb-org/8.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list
For Debian:
$ echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/debian bookworm/mongodb-org/8.0 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list
Next, for Ubuntu and Debian, reload local package database and install the MongoDB package:
$ sudo apt-get update
$ sudo apt-get install -y mongodb-org
Start MongoDB service and configure it to load on boot:
$ sudo systemctl start mongod
$ sudo systemctl enable mongod
First without authentication create db admin role that can manage databases. Login to MongoDB admin db:
$ mongo admin
Create the user in the MongoDB console:
db.createUser({"user" : "root", "pwd" : passwordPrompt(), "roles":["userAdminAnyDatabase", "readWriteAnyDatabase", "dbAdminAnyDatabase", "clusterAdmin"]});You'll requested to fill the password of the root user.
Next let's configure MongoDB to authorize users. Add the next configuration to /etc/mongod.conf:
security:
authorization: enabledRestart the mongodb service.
$ sudo systemctl restart mongod
From now on, you should login to MongoDB shell with the root user you setup the next step (Application user).
BillRun application use separated user for security purpose.
Let's create the application user. You'll need the password you setup in the previous step when login to MongoDB console admin db:
$ mongo admin -u root -p
Create the application user:
db.createUser({"user" : "billrun", "pwd" : passwordPrompt(), "roles" : [ { "role": "readWrite", "db": "billing" }, { "role": "dbAdmin", "db": "billing" }, { "role": "userAdmin", "db": "billing" } ]});You'll requested to fill the password. Remember it for the application db settings step (Marked as {Password}).
Installing the basic packages for the web service and the application:
$ sudo apt -y install nginx git php-fpm php-cli php-json php-common php-zip php-gd php-mbstring php-curl php-xml php-pear php-bcmath php-pear php-dev fonts-roboto-fontface fonts-roboto-hinted fonts-roboto-unhinted
$ sudo pecl install yaf mongodb
Next, run the commands according to your distribution.
$ echo "extension=yaf.so" | sudo tee /etc/php/8.5/fpm/conf.d/40-yaf.ini /etc/php/8.5/cli/conf.d/40-yaf.ini
$ echo "extension=mongodb.so" | sudo tee /etc/php/8.5/fpm/conf.d/40-mongodb.ini /etc/php/8.5/cli/conf.d/40-mongodb.ini
$ echo "extension=yaf.so" | sudo tee /etc/php/8.3/fpm/conf.d/40-yaf.ini /etc/php/8.3/cli/conf.d/40-yaf.ini
$ echo "extension=mongodb.so" | sudo tee /etc/php/8.3/fpm/conf.d/40-mongodb.ini /etc/php/8.3/cli/conf.d/40-mongodb.ini
Next, for Ubuntu and Debian, update php-fpm to use local port instead of local socket. Edit /etc/php/8.5/fpm/pool.d/www.conf (8.4 instead of 8.4 on Debian) and update the listen variable as follow:
listen = 127.0.0.1:9000or use the next command:
sudo sed -i 's/^listen.*/listen = 127.0.0.1:9000/' /etc/php/7.*/fpm/pool.d/www.confRemove the default vhost:
$ sudo rm /etc/nginx/sites-enabled/default
Add to /etc/nginx/conf.d/billrun.conf the next configuration:
server {
listen 80;
server_name _;
access_log /var/log/nginx/billrun.access.log;
root /var/www/billrun/public;
if (!-e $request_filename) {
rewrite ^/(.*) /index.php last;
}
location ~ .*.php$ {
root /var/www/billrun/public;
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
fastcgi_param APPLICATION_ENV prod;
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_read_timeout 1000;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
location ~* \.(js|css|png|jpg|jpeg|gif|swf|xml|txt|woff|woff2)$ {
access_log off;
expires 30d;
add_header Pragma public;
add_header Cache-Control public;
}
}Enable all services to load on boot:
$ sudo systemctl enable php8.5-fpm # Under Debian php8.4-fpm
$ sudo systemctl enable nginx
$ sudo systemctl restart php8.5-fpm # Under Debian php8.4-fpm
$ sudo systemctl restart nginx
$ export BILLRUN_DIR=/var/www/billrun/
$ sudo git clone https://git.bill.run/sdoc/billrun.git $BILLRUN_DIR
$ sudo mkdir $BILLRUN_DIR/logs/ $BILLRUN_DIR/cache/
$ sudo chmod 775 $BILLRUN_DIR
$ sudo chmod 777 $BILLRUN_DIR/logs/ $BILLRUN_DIR/cache/
$ sudo chown -R www-data:www-data $BILLRUN_DIR
$ sudo chown -R apache:apache $BILLRUN_DIR
You'll to setup the next file $BILLRUN_DIR/conf/`hostname`.ini and add the next content:
db.host=localhost
db.port=27017
db.user=billrun
db.password={PASSWORD}
db.name=billingDon't forget to replace the {PASSWORD} with the password you set in the previous step (under database user for the application).
After this step you can access billing application admin panel (http://<HOST or IP>/). You'll requested to enter the default user and password.
Please notice: default user & password for the application are admin & 12345678 accordingly. Please change it after first login.
Run the next php command to init the db:
cd $BILLRUN_DIR && php public/index.php --env prod --dbinit
BillRun application is using wkhtmltopdf and pdftops tools for generating invoices. This step is optional and required only if you want to generate invoices.
Download and install:
$ wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.bookworm_amd64.deb' -P /tmp/ \
&& sudo apt install -y ./wkhtmltox_0.12.6.1-3.bookworm_amd64.deb
Install packages with apt:
$ sudo apt install -y ./wkhtmltox_0.12.6.1-3.bookworm_amd64.deb
If you need to sign invoices with your own ssl key, you'll need jsignpdf.
Download and install:
$ sudo apt install openjdk-21-jre-headless unzip
$ wget -O /tmp/jsignpdf.zip \
'https://repo1.maven.org/maven2/com/github/kwart/jsign/jsignpdf-distribution/3.2.1/jsignpdf-distribution-3.2.1-minimal.zip' \
&& unzip /tmp/jsignpdf.zip -d /opt \
&& rm -f /tmp/jsignpdf.zip
After installation set the signature settings according to your preferences. Here is a sample that need to be added to $BILLRUN_DIR/conf/`hostname`.ini:
signer.jsignpdf.exec_path=/opt/jsignpdf-3.2.1/bin/jsignpdf.sh
signer.jsignpdf.keystore_file=/billrun/certs/mycert.cer
signer.jsignpdf.keystore_password=
signer.jsignpdf.image.bg_path=/billrun/conf/PdfSign/logo.png
signer.jsignpdf.image.bg_scale=0.4
signer.jsignpdf.image.urx=360
signer.jsignpdf.image.ury=760
signer.jsignpdf.image.llx=240
signer.jsignpdf.image.lly=640If file permissions issues raised this is because CentOS comes with SELINUX Enabled by default. Recommend to turn SELINUX off.
Probably SELINUX issue. You can fix it by running the next commands:
$ sudo -P setsebool httpd_can_network_connect 1
$ sudo -P setsebool httpd_can_network_connect_db 1
The debug.log file or the log directory might not be configured on the billrun user
$ sudo chmod 777 $BILLRUN__DIR/logs -R
When a new version is created we need to move to that version in git (for example moving to alpha_4):
$ sudo su <billrun_user>
$ export BILLRUN_DIR=/var/www/billrun/
$ cd $BILLRUN_DIR
$ export GIT_SSL_NO_VERIFY=1 #this will tell git that the identity of the ssh sig. doesn’t have to be verified
$ git fetch --tags # to fetch all the update information from the remote git repository
$ git tag # this will display all the available tags
5.6.7
5.6.8
5.6.9
...
5.8.5.6
5.8.6
5.8.6.1
5.8.7
For example, the next command will checkout the 6.0.0 version (tag):
$ git checkout 6.0.0
After each deployment of tag, need to run migration:
cd $BILLRUN_DIR && php public/index.php --env prod --dbmigrate
Congratulations! You've installed BillRun Billing - the best open source billing in the world.
Now you can move on, and configure the schedule tasks of the system.