Not Cooking the Books...

Marcel Gagné

Issue #83, March 2001

Marcel gives HOWTOs on time tracking and bookkeeping with Linux for consultants.

Tu n'es pas sérieux, François! I admit you are a one in a million waiter, mon ami, but setting off to start your own consulting company is harder than you think. Since you are asking my advice, I will be happy to offer some help. But first, have you not noticed that our guests have arrived. Vite François! Show them to their tables.

Ah, bonjour, mes amis! Welcome once again to Chez Marcel. François. Vite. Du vin for our friends. The 1997 Vouvray Cuvee Constance should be wonderful. You see, mes amis, François was asking about what he would need in order to do a little consulting work on the side when he is not here at the restaurant. With his growing knowledge of Linux, he feels he might be ready to help others out and perhaps make a little argent, non?

Thank you, François! Please. Pour.

In many ways, Linux is the great friend of the computer consultant. Out of the box, your distribution contains a bevy of tools to get you connected in almost every way possible. Your Linux system is a mail server, a communications console, a Telnet client, an SSH client and so on. Programming tools of various stripes are there for you: C++ compilers, Perl, Python, Tcl/Tk and others. In fact, a typical Linux distribution has just about all the tools you need to become your own ISP or run a successful web site. What you don't necessarily have are the tools of business itself.

Oui, mes amis. It comes down to money. Bien sur, when you are out there working away, you are working because it will pay for your meals at home with the occasional night out at Chez Marcel, non? To get paid, you need to be able to tell your customers how much time you have spent working for them. Then, you must bill them, collect the money and keep track of the whole process. The life of the independent consultant is that of a self-contained, one-person business, and it should be treated as such.

Well, I am here to tell you that the same dedicated community of open-source programmers that have made Linux your most affordable, infinitely customizable workstation or server possible, have also been busy cooking up the tools for dealing with la Banque.

The first thing we will need to do is track our time. To do this, I am going to give you a couple of alternatives starting with a low-calorie command-line tool called tt:

tar -xzvf tt-1.0.tar.gz
cd tt-1.0
./configure
make
make install

To use tt, start by typing the command name on a line by itself. It will complain and tell you that it doesn't know what you want, but as part of that complaint, it will have generated a .tt directory under your home directory. Now, change to that directory and create a file called projects.conf. This is essentially a list of projects against which you wish to track time. Each project name is surrounded by square brackets. Here's a sample I was working on:

[cook] # Very important
[eat] # You can make money doing this?
[drink_wine] # If only it were possible
[write_recipes] # The real work, non?
You can, at any time, list all your current projects with the tt '*' -list command. To start tracking time against a project, I would type the command name with a -start flag. For instance, drinking wine, while pleasurable, is part of the job and something that I must regretfully charge for. (I joke, of course.) But if it could be so, I would start billing for it like this:
tt -start drink_wine
When I am done with my, ahem, work, I would issue the same command with the -stop flag.

For a simple program, tt is quite powerful. One interesting use of the program is as a time wrapper for tasks. Say you are working for Henri's Fine Wines. You are doing work on the company web server setting up his e-commerce site. The work is all done remotely, and you Telnet into the server to do your work. You could wrap the Telnet command with the tt command to track your time automatically. Like this:

#!/bin/bash
tt henri_wines -start
telnet henri_website.com
tt henri_wines -stop

C'est bon, non? When it comes time to report, you can generate a quick report of your time with this command:

tt drink_wine -export
project 'drink_wine' (closed):
  Tue Dec 19 2000 16:53:31-Tue Dec 19 2000 16:53:56: 00h00m25s
  Wed Dec 20 2000 12:10:39-Fri Dec 22 2000 16:52:59: 52h42m20s
  Fri Dec 22 2000 16:56:18-Fri Dec 22 2000 17:01:04: 00h04m46s
+ Tue Dec 19 2000 16:53:31-Fri Dec 22 2000 17:01:04: 52h47m31s
Even better, you can use the -format modifier to, export to and even create, an SQL database. tt knows about MySQL and PostgreSQL. For instance, I could create a database in PostgreSQL with this command:
createdb myconsultancy
Next, I export my tt data with this command:
tt drink_wine -export -format pgsql | psql myconsultancy
With that information in place, I could generate custom reports from my PostgreSQL database:
psql -c "select * from tt_timing;" my_consultancy
You may find that tt does everything you want it to, which would be wonderful, but if you are on the road a great deal and you need some way to file your time remotely, then this next item on the menu might be just what your taste buds demand. You may also have become highly successful in your consulting career and have hired many people to help you out. Again, this may be just what you are looking for.

One of the great things about browser-based applications is that they allow you to do your work from nearly anywhere. Start up your browser, set the URL for the appropriate link, allow a few seconds for the link to rise to the display window, and Voilà! You have a fresh, steaming application ready for use. In the world of time tracking and billing, I was fortunate enough to sample onShore Inc.'s “TimeSheet” program. This is a great application and worth checking out. It offers a clean, simple interface, a separate administrator's screen as well as profiles for both full-time employees and contract consultants. You can also generate reports based on the individual consultant or a specific client.

tar -xzvf onshore-timesheet-current.tar.gz
cd onshore-timesheet-2.2

Before you go running off excitedly typing “make”, I must tell you that your humble chef failed to take the first rule into consideration when trying this application. That rule is “Thou shalt read any and all INSTALL and README files”. After spending some time with a delightful little Merlot, I once again visited OnShore's TimeSheet and discovered that a little editing of the Makefile was all I needed to do to make things work. The changes required are few and everything is near the top of the Makefile, but I will highlight a few:

PERLINC         := /usr/lib/perl5/site_perl/5.005
APPROOT         := /usr/local/apache/htdocs/timesheet
TIMESHEET_URL   := /timesheet
CONFFILE        := timesheet.conf
GUEST_ACCOUNT   := no
WWWUSER         := www
APPOWNER        := www
Since onShore TimeSheet comes with a couple of necessary Perl modules, you should modify the PERLINC parameter to reflect your site_perl install directory. The one above is mine. The APPROOT represents the path to the application on your web server. The default is Red Hat's installation default of /home/httpd/html. Change it to reflect your own setup. My web servers are all rebuilt Apache servers with a /usr/local/apache/htdocs document root.

The next change is the default URL for the application. If you choose an APPROOT with “timesheet” as the eventual directory (the default), you will want this to be /timesheet. Next, decide on a name for the configuration file. I chose timesheet.conf. The install will create a default “guest” account if you so wish. I decided that I would create all my users as needed. The last two parameters are both set to WWW for me. The WWWUSER is the default user id your web server runs as. On many systems, this is set to the user “nobody” by default. You should decide accordingly. Finally, you want to set the APPOWNER. This sets the ownership for the whole application.

Now, your patience will have paid off. If you are running on a Debian system, type make install-debian at this point. Otherwise, type make install. You will see some exciting information scroll by on your screen as a default PostgreSQL database is created for you along with your administrator user ID. You are almost there. To run this, you need to make sure that your web server understands .cgi extensions and executes them appropriately. This is done by adding the lines below to your httpd.conf file. Note: Depending on the vintage of your web server installation, the appropriate configuration file might actually be access.conf. The two most likely configuration directories are /usr/local/apache/conf and /etc/httpd/conf.

AddHandler cgi-script .cgi
<directory /usr/local/apache/htdocs/timesheet>
Options +ExecCGI
AddHandler cgi-script .cgi
</directory>

The <directory> paragraph is there so you can execute cgi files wherever you decided the installation is going to be. Remember that cgi scripts are normally executed from cgi-bin rather than html or htdocs.

The last thing you need to do is make sure that PostgreSQL is started with the -i option. For instance, in my /etc/rc.d/init.d/postgresql startup file, (Debian users should check /etc/init.d/postgresql instead) I have the following line:

su -l postgres -c '/usr/bin/postmaster -S
-D/var/lib/pgsql'

I simply changed the default start so that there was a -i option included after the word “postmaster”. After restarting PostgreSQL and your web server, you are ready to roll. Simply point your web browser to the TimeSheet URL: http://my_webserver/timesheet/.

You'll need to give your admin login name and password, which is “admin” for the login and “admin” for the password. Obviously the first order of business should be to change this to something more secure. This is also the time when you want to start creating your users, be they permanent employees, consultants or other administrators. Check out Figure 1 for a look at the onShore TimeSheet program in action.

Figure 1. Timesheet Screenshot

Magnifique! You can now keep track of your time. From your detailed timesheets, you can invoice customers and reap the fruits of your labours, non? Collect the money and let your accountant worry about the rest. Une minute! The accountant will want some kind of financial records. This brings us to the great dreaded beast of any business enterprise: keeping a set of books. Fortunately for the Linux user, there are answers here as well. Come, mes amis, and experience a little sample of accounting packages for Linux.

Accounting applications in the Linux world represent some of the most requested of tools. Luckily, these are starting to appear in greater numbers. These may be commercial applications, GPL'ed, or free software. Since we are discussing open-source applications, we will concentrate our menu items in this area. If your application is not too complex, you may want to start by having a look at BANAL, which stands for BANAL's Absolutely Not A Ledger. Written by Matthew Rice, BANAL is a fairly simple application with big dreams. I say that because BANAL can do quite a number of things, even if it does them simply. With BANAL, you can track your time, maintain clients and suppliers, invoice, track expenses, write cheques and more. Et oui, BANAL will cost you nothing but some time.

The software is available as a free download with a BSD-style license and is fairly easily installed. I should point out that while the source code is freely available—actually, it is all source since this is a Perl application—and that you can get it as a tarball, your chef humbly recommends getting the RPMs instead. There are two RPMs: a client and a server. The source tarball contains a couple of extras such as some evolving PHP scripts. That may be worth the extra work to some. The RPM install is quick and easy:

rpm -ivh banal-*

Quite a bit happens here. Among other things BANAL creates a user in your /etc/passwd file and starts the server. BANAL is really quite simple to use, but I still recommend that you read the quickstart file that comes with the install. You'll find it in /usr/doc/banal-client-0.10/quickstart.txt.

Before we move on, I should give you a little bit of a warning. On my system (and perhaps on yours), the bk program tried to open /usr/bin/vi by default, whereas on my system the path to vi was /bin/vi. You may want to create a symbolic link to rectify that problem or simply assign the EDITOR environment variable, which will override BANAL's built-in path to the editor. This also gives you the opportunity to choose the editor you prefer:

export EDITOR=pico

Once this is all done, you need to start creating your accounts, profiles, suppliers, expense accounts and so on. This is done using the one command bk.

BANAL-FTL bookkeeping system
 bk is BANAL's client tool for the command line. Try:
 bk help commands       for a list of commands
 bk help command        for help on a specific command
 bk help usage          for generic command-line arguments
Getting started requires that you create one initial client (your company) using the command bk client your_co_name. Make sure you fill in all the appropriate or required fields, then save your work. Next, you need to change the company information settings to show that this client profile is actually your company:
$ bk setting /UserInfo/CompanyID
You'll find yourself in editor mode with something resembling the following. (Remember to change the “Value” field to something other than “ChezMarcel”, non?)
# A BANAL Setting Specification.
#
# Setting:     Unique Setting ID
# Value:       Value                  @@ REQUIRED
# Description: Item description
Setting:     /UserInfo/CompanyID
Value:       ChezMarcel
Ah, it is all so easy, non? As with the timesheet part of your consulting business, there is a graphical alternative here as well that goes by the name of GnuCash [look for an article on GnuCash in LJ's April 2001 issue]. This is a wonderful open source, GPL'ed and completely free accounting package.

I decided to build GnuCash from scratch. To start, I downloaded the source for the latest package version from the GnuCash web site. For those who are a little more impatient, you will find some precompiled binaries at the site.

The core of this application uses the GNOME libraries, so you will need to have these loaded regardless of whether you choose to build from scratch or use the binaries. Obviously, those of you who are already using GNOME as your desktop will find that gnome-libs is already there. For those who might be using another desktop, you will need to load the gnome-libs and the supporting libraries, specifically, GTK. You'll find that GnuCash is worth the work, but it does require a bit of hunting and gathering. In addition to the GNOME framework, you also need guile, swig, slib and g-wrap. The final package, g-wrap, is actually on the GnuCash FTP site's download area. There are a few other requirements, most notably libjpeg and libpng, but these will likely already be on your system. The slib package may already be there as well in the guise of the umb-scheme package. Check the Resources section for pointers to all these sites.

The first step, after obtaining the software bien sur, is to extract the archive. This is followed by some very familiar steps:

tar -xzvf gnucash-1.4.9.tar.gz
cd gnucash-1.4.9
./configure
make
make install

At this point, you should probably check out a couple of fairly important links. When your humble chef first tried this recipe, things did not go altogether smoothly, specifically as related to slib. The guile libraries make some assumptions as to where the slib information will wind up located. This is apparently not a problem on all systems, but it was on my Red Hat system. I changed directory to /usr/share/guile and created the following symbolic links:

ln -s /usr/lib/umb-scheme/slib slib
ln -s /usr/lib/umb-scheme/slibcat slibcat
ln -s /usr/lib/umb-scheme/slib/mklibcat.scm mklibcat
The umb-scheme package is my Red Hat installed-scheme libraries (remember slib earlier). With these links in place, things went a lot smoother. Once this is done, start GnuCash by typing gnucash at the command prompt.

If you have ever used Intuit's Quickbooks package, you will find GnuCash invaluable. With its easy-to-use interface, you can create your chart of accounts for banking, credit card transactions and so on (see Figure 2). The package has a nice reconciliation feature, and numerous reports including a profit and loss statement so you can see just how much money you have made at any given time. It even handles multiple currencies for you globe-trotting consultant types. The only downside that I can think of for a small business is that there is no invoicing function. That, you will have to do manually.

Figure 2. GnuCash Screenshots

Mon Dieu, François! It is late and there is still much to do. Pour our friends another glass. What is it, François? You have decided to abandon the idea of doing extra work as a consultant? A cause de moi? Mais non, I do not give you too much to do. You have plenty of time! We will discuss this later, François. For now, please tend to our guests. More wine.

Mes amis, if you do decide to go it alone, always remember that, truly, you are not alone. Having chosen Linux, you have at your disposal all the tools needed to begin and operate your high-tech consultancy. With a little help from some great open-source chefs, you may even find that your own ideas will join theirs, and someday your own recipes may be featured here at Chez Marcel. Until next time, your table will be waiting.

À votre santé! Bon appétit!

Resources

Marcel Gagné lives in Mississauga, Ontario. In real life, he is president of Salmar Consulting Inc, a systems integration and network consulting firm. He is also a pilot, writes science fiction and fantasy, and edits TransVersions, a science fiction, fantasy and horror anthology. He loves Linux and all flavors of UNIX and will even admit it in public. In fact, he is currently working on Linux System Administration: A User's Guide, coming soon from Addison Wesley Longman. He can be reached via e-mail at mggagne@salmar.com. You can discover lots of other things from his web site at http://www.salmar.com/marcel/.