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, MySQL and LaTeX 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.

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:

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

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.

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

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 limited functionality version of the Billing Engine is now included with the distribution. It is provided for evaluation purposes and isn't essential for the successful generation of bills. The Billing Engine does, however, run fast (it will produce over 1,000 bills per hour on a small server) and it does support more complex billing scenarios.

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.

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

Next Previous Contents