Next Previous Contents

3. Installing e-Bills

This install guide has been used successfully by many individuals, we've also tested the process many times on our servers here where we run several instances of e-Bills. Importantly, it now also describes how to upgrade from previous versions and documents the use of the Billing Engine

I've considered making all of the commands below part of an installation script or a Makefile. However there are many areas that need configuration and in the end I thought it better to explain the steps needed and have the system manager understand what was going on instead of automating (and messing up) the process.

The '#' character is used to denote the shell command prompt throughout and should not be typed.

If you spot any problems or have any feedback for this installation please help me by sending an email to support@asplen.co.uk

3.1 Prerequisites

You need to have PHP and MySQL installed on your server.  Please read the relevant documentation listed in section 8.  The Apache web server (www.apache.org) also needs to be running.

You need to have LaTeX installed if you want to use PDF format letters and bills. However e-Bills now supports HTML format bills and this may prove easier for many installations (albeit lacking a great output format).

All of the paths in the following dialogues assume a RedHat installation. If its something different then you may need to change paths.

3.2 Required directory structure

Create the relevant directories:

# cd /home/httpd	// Or whereever your Apache web folders are stored - could be /var/www
# mkdir e-bills		// This is where the .php files are stored
# mkdir e-bills/pdfs	// This is where the PDF files are stored

# chown ebills:webgroup e-bills		// Replace webgroup with whatever group you use for web access
# chown ebills:webgroup e-bills/*
# chmod 775 ebills
# chmod 775 ebills/*

# mkdir /home/ebills	// This is the e-Bills home directory

Now create a login for ebills in group webgroup with a home directory of /home/ebills. Alternatively you might create a new group for ebills and make sure ebills is also a member of webgroup.

Note on earlier versions of e-Bills we created a seperate folder e-bills.pdfs. Whilst this keeps PDF files at a higher level to manage in makes life difficult when running multiple instances of e-Bills.

3.3 Downloading the latest version

The latest version of e-Bills can be downloaded from www.asplen.co.uk/billing.

Updates are made on a regular basis (this update was done alongside V1.4). Most of these will be with the PHP code only, and there are several changes to the database - for which there are appropriate patch scripts

Store the .tar.gz file in /home/ebills

3.4 Upgrading from previous versions

Upgrading from previous versions is quite straightforward and requires:

3.5 New installation

Login as ebills, store the downloaded .tar.gz file in /home/ebills and then type

# tar -xzf ebills_1.4_pc_linux.tar.gz

This will copy the files into the relevant sub-directories for you.

The following folders are created:

Sub-directory Contents
web_server The PHP code
bill_templates Billing templates in .tex format
bin binaries and executable scripts
HOWTO Howto html documentation
etc Configuration files
db_init Scripts to setup the database

The following are some of the key files:

File Purpose
COPYING Contains the licence and warranty info
README Read before doing anything else
INSTALL Latest release & installtion information
etc/_configure.inc.default Contains configuration data for the PHP code
billing_templates/Standard.tex Standard billing template. Copy and change this to customise the bill format
billing_templates/Standard_EURO.tex As above but prints EURs instead of pounds

Now create your own _configure.inc:

If you don't feel you have sufficient information at this stage, do what you can and make the other changes later.

All files need to be copied to the folder used by apache:

Allow the webgroup to overwrite the bill template file:

Note: there have been several reports of problems selecting the billing template from within e-Bills. If you have such a problem please check the permissions and ownership of the above directory and files.

If you change any of the default paths, including in LaTeX (below), you should edit the file /home/ebills/bin/ebills_make_pdf to math the directories used in your system.

3.6 Configuring Apache

You need to add e-Bills as a virtual domain to your Apache configuration. You'll need to be root.

To do this edit httpd.conf. In my system this is:

/usr/local/apache/conf/httpd.conf

Add the following lines to the end of this file, replacing the domain name with your own:

<VirtualHost 192.168.1.1>
	ServerName e-bills.yourdomain
	DocumentRoot /home/httpd/e-bills
	ErrorLog /var/log/httpd/e-bills_error_log
</VirtualHost>

Then add this virtual domain to your DNS lookup (/var/named/yourdomain):

e-bills	IN A 192.168.1.1

Previous versions also included the following, which are now unnecessary.

<VirtualHost 192.168.1.1>
	ServerName e-bills.pdfs.yourdomain
	DocumentRoot /home/httpd/e-bills.pdfs
	ErrorLog /var/log/httpd/e-bills_error_log
</VirtualHost>
e-bills.pdfs IN A 192.168.1.1

Replace the 192.168.1.1 with the IP address of your own server in all cases above.

Apache will also use a default directory where all web sub-directories are held. In our system this is /home/httpd.

The restart httpd and then bind with:

killall S85httpd
/etc/rc.d/init.d/httpd start
/etc/rc.d/init.d/named restart

From a browser on your LAN (or using lynx) you should be able to see the e-Bills start screen at the relevant url (say, http://e-bills.yourdomain/).

3.7 Configuring PHP

No configuration is needed once PHP is up and running and working with your Apache server and your MySQL database. Note that this means that PHP must be built with the "--with-mysql" option set at compile time.

Apache and PHP configuration parameters

Note that PHP V4.2.0 onwards has register_globals switched off by default. You need it switch on with the following line in php.ini:

3.8 Configuring the database

You need to configure the database before you can get going with e-Bills. This achieves the following:

To configure the database you must login into MySQL with the super-user username / password that you used when you installed MySQL. For now assume these are 'eroot' and 'epass'. 

The commands required are:

mysql -u eroot -pepass mysql
mysql>create database ebills;
mysql>show databases;
mysql>quit

The command shows you've actually created the database. Please note that there should be no space between the '-p' and your password.

cp db_init/ebdb-add-users.default db_init/ebdb-add-users

Now edit ebdb-add-users (if you want) and replace 'password' with something of you choice - write it down! Now type:

mysql -u eroot -pepass mysql < db_init/ebdb-add-users

Please also note that this creates two accounts: one is a MySQL account that has all privileges to change the database (i.e. add and remove tables). The other (ebguest) can only make read or write changes. This is the account used by the PHP applications and any other applications that access the ebills database.

Importantly the above step creates a user account within e-Bills. The username is "su" and the password is "password". Be sure to change this password and add other accounts when you first access e-Bills from your browser.

You've add user access, now you need to create the tables:

mysql -u ebills -pyour-new-password ebills < db_init/ebdb-create-tables

Importantly the above step creates a user account within e-Bills. The username is "su" and the password is "password". Be sure to change this password and add other accounts when you first access e-Bills from your browser.

3.9 Configuring LaTeX

LaTeX is essential to e-Bills as it is used to create PDF files for printing and archiving. We find the download and install process to be quite straightforward.

If you don't want PDF files you don't need LaTeX and you can make a simple change in the ebills configuration file to use HTML format instead (see below).

The following is extracted and modified from Thomas Esser's INSTALL file, found in the distribution. If required download INSTALL first (see the ftp commands below) for a more detailed description.

If its not already installed, then please ensure that ghostscript is installed. Check using:

# locate ps2pdf

A link to GNU Ghostscript is given in the references of this HOWTO.

We've found on some installations that LaTeX uses the wrong directory structure. This can be tested by:

# cd /home/httpd/ebills/pdfs
# cp /home/ebills/bill_templates/billformat.tex .
# pslatex billformat.tex

If the above runs without errors then fine. If you see errors, such as 'cannot find fancyhdr.sty', then the installation is using the incorrect directories. The LaTeX INSTALL file provides some instructions. If you are really stuck send us an email!

3.10 Configuring the Billing Engine

A full functionality Billing Engine is now included with the distribution. Its presence is detecteed by the PHP software and it is run automatically. It can also be run as a backgroun cron job to automatically create bills overnight: particularly useful in service industries. The billing engine supports the full range of billign scenariios (whereas the PHP code takes a simple approach) and hence sshould be use for any serious application. It also runs very fast and is more than capable of creating many thousand bills per hour. From a development perspective it is the billing engine that will be developed going forward to support more complicated billing and provide a greater range of billing and bill features.

We suggest if you are evaluating e-Bills then get it going without the Billing Engine, test out its functionality and then visit section 7.6 Using the Billing Engine.

3.11 Configuring for HTML format bills and letters

Use HTML format bills if you don't need the quality and format of PDF invoices and letters or you want to get going with e-Bills without worrying about configuring LaTeX.

The change is simply made by changing the value of BILL_FORMAT in /home/ebills/etc/_configure.inc. Once changed e-Bills will produce bills in that format.

e-Bills will display both HTML format and PDF format bills and letters, so that older invoices and letters will always be displayed correctly.

Note: at Version 1.14 the PHP billing code generates HTML or PDF format bills, but not the Billing Engine (which only produces PDF format). So disable the billing engine if you want HTML format bills. Letters are always generated in the HTML or PDF format as selected.

That's it sorted. Let's get on and use it.

Next Previous Contents