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:
$ wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | sudo apt-key add -
Create the repo file /etc/apt/sources.list.d/mongodb-org-4.4.list.
For Ubuntu:
$ echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list
For Debian:
$ echo "deb http://repo.mongodb.org/apt/debian buster/mongodb-org/4.4 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.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
Create a /etc/yum.repos.d/mongodb-org-4.4.repo file:
[mongodb-org-4.4]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/4.4/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-4.4.ascInstall the package:
$ sudo yum install -y mongodb-org
Start MongoDB service:
$ sudo systemctl start 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/7.4/fpm/conf.d/40-yaf.ini /etc/php/7.4/cli/conf.d/40-yaf.ini
$ echo "extension=mongodb.so" | sudo tee /etc/php/7.4/fpm/conf.d/40-mongodb.ini /etc/php/7.4/cli/conf.d/40-mongodb.ini
$ echo "extension=yaf.so" | sudo tee /etc/php/7.3/fpm/conf.d/40-yaf.ini /etc/php/7.3/cli/conf.d/40-yaf.ini
$ echo "extension=mongodb.so" | sudo tee /etc/php/7.3/fpm/conf.d/40-mongodb.ini /etc/php/7.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/7.4/fpm/pool.d/www.conf (7.3 instead of 7.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
$ sudo yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
$ sudo yum -y install https://rpms.remirepo.net/enterprise/remi-release-7.rpm
$ sudo yum -y install yum-utils
$ sudo yum-config-manager --enable remi-php74
$ sudo yum -y install nginx git php-fpm php-common php-pear php-cli php-devel php-xml php-curl php-soap php-json fonts-roboto-fontface fonts-roboto-hinted fonts-roboto-unhinted
$ sudo pecl install yaf mongodb
$ echo "extension=yaf.so" | sudo tee /etc/php.d/40-yaf.ini
$ echo "extension=mongodb.so" | sudo tee /etc/php.d/40-mongodb.ini
$ sudo dnf module reset php
$ sudo dnf module enable php:7.4
$ sudo dnf -y install nginx git make php-fpm php-common php-pear php-cli php-devel php-xml php-curl php-soap php-json fonts-roboto-fontface fonts-roboto-hinted fonts-roboto-unhinted
$ sudo pecl install yaf mongodb
$ echo "extension=yaf.so" | sudo tee /etc/php.d/40-yaf.ini
$ echo "extension=mongodb.so" | sudo tee /etc/php.d/40-mongodb.ini
Update php-fpm to use local port instead of local socket. Edit /etc/php-fpm.d/www.conf 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-fpm.d/www.confAdd 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;
}
}Remove or comment-out the whole server {} section from /etc/nginx/nginx.conf to enable the billrun.conf that we just added.
Enable all services to load on boot:
$ sudo systemctl enable php-fpm # under Ubuntu this is php7.4-fpm; Under Debian php7.3-fpm
$ sudo systemctl enable nginx
$ sudo systemctl restart php-fpm # under Ubuntu php7.4-fpm; Under Debian php7.3-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
(NOTE : DO THIS ONLY ONCE PER DB PER BILLRUN INSTALLATION!)
Put the database password for the application user under shell variable for the next steps:
$ export MDB_PASSWORD={PASSWORD}
Do not forget to replace {PASSWORD} variable to the password you set on previous step.
Set the DB indexes :
$ mongo billing --authenticationDatabase=admin -ubillrun -p$MDB_PASSWORD < $BILLRUN_DIR/mongo/create.ini
Apply sharding [Optional; only if installing on MongoDB cluster]:
$ mongo billing --authenticationDatabase=admin -ubillrun -p$MDB_PASSWORD < $BILLRUN_DIR/mongo/sharding.ini
Import the initial configuration:
$ mongoimport --authenticationDatabase=admin -ubillrun -p$MDB_PASSWORD -d billing -c config < $BILLRUN_DIR/mongo/base/config.export
Import the default tax rate:
$ mongoimport --authenticationDatabase=admin -ubillrun -p$MDB_PASSWORD -d billing -c taxes < $BILLRUN_DIR/mongo/base/taxes.export
Import the initial users:
$ mongoimport --authenticationDatabase=admin -ubillrun -p$MDB_PASSWORD -d billing -c users < $BILLRUN_DIR/mongo/first_users.json
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.
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 from https://github.com/wkhtmltopdf/wkhtmltopdf/releases/0.12.5/ the correct deb file for your distro, for example for Ubuntu Bionic :
$ wget 'https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.5/wkhtmltox_0.12.5-1.bionic_amd64.deb' -P /tmp/
Install packages with apt:
$ sudo apt install -y /tmp/wkhtmltox_0.12.5-1.bionic_amd64.deb poppler-utils
$ sudo yum install -y https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.5/wkhtmltox-0.12.5-1.centos7.x86_64.rpm
$ sudo yum -y install fontconfig libXext urw-fonts poppler-utils
Add to application configuration $BILLRUN_DIR/conf/`hostname`.ini:
invoice_export.exec = "/usr/local/bin/wkhtmltopdf"
Add to application configuration $BILLRUN_DIR/conf/`hostname`.ini:
invoice_export.exec = "/opt/wkhtmltox/bin/wkhtmltopdf"If 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
v5.6.7
v5.6.8
v5.6.9
...
v5.8.5.6
v5.8.6
v5.8.6.1
v5.8.7
For example, the next command will checkout the 5.8.7 version (tag):
$ git checkout v5.8.7
After each version switch, please run migration script:
$ export MDB_PASSWORD={PASSWORD}
$ mongo billing --authenticationDatabase=admin -ubillrun -p$MDB_PASSWORD mongo/migration/script.js
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.