I was trying to look for some open-source invoicing apps and found two candidates on Freshmeat, one of them Laurux, the other L-invoice. Since Laurux turned out to not work on the Mac (its dependency, Gambas, did not compile, or rather did not configure), L-invoice was left as the only candidate.

L-invoice’s documentation is sparse, and ambiguous enough that you feel you have to go through hoops to set it up. So here is a record of what I did to get it into a semi-working state:

Where to put it

First you have to figure out where to put L-invoice. The documentation talks about the “/application” directory, but that is not really the system’s /Application folder. You can just put it under the default document root for MacOS X’s Apache server, at /Library/WebServer/Documents.

cd /Library/WebServer/Documents
unzip linvoice_mcb_1.0.0.zip

# Remove the unused resource fork
rm -fr __MACOSX

# Make a symlink so the application can be accessed more easily later
ln -s linvoice_mcb_1.0.0 linvoice

Note that you symlink to the top level of the package, and not to the “application” subdirectory.

Setting up the database

The documentation then tells you to import system/sql/linvoice-setup.sql. If you did that you will get an error. You have to choose a database.

If you looked into the SQL file you will find that the author used the name “myclientbase”, but if you tried using that your app still wouldn’t work, so it turns out (after much frustration) that what name to use actually doesn’t matter. So for the purpose of demonstration let’s assume you chose the name “linvoice” (as opposed to, say, “myclientbase”):

mysql -p

Then, while inside mysql,

create database linvoice;
select password('the password you want to use');
create user 'linvoice'@'localhost' identified by password '*the hash you got back from the select statement';
grant all on linvoice.* to 'linvoice'@'localhost';

Back to the shell,

mysql -p linvoice < linvoice/system/sql/linvoice-setup.sql 

Configuring for your site

The documentation next states that “Other settings are at: application/config/config.php, and database.php”. This is wrong, and if you actually tried, you will be frustrated because your changes will not have any effect.

The real general configuration file is at linvoice/application/config/config.live.php (note the “live”), and the real database configuration file is at linvoice/application/config/database.live.php.

Unlike larger, more polished packages, these .php files are just configuration files. You don’t run them from your browser. So use your regular text editor to edit these files, and make sure to at least change

• $config['base_url'],
• $db['default']['username'],
• $db['default']['password'], and
• $db['default']['database']

to correspond to what you actually chose to use at your site. Then you should be able to log in.

How to log in

If you try to access your newly installed app, you will be presented with a login screen, but there is no explanation anywhere that tells you what username and password to use.

After looking through the database tables, I found that

• the username is “admin”, and
• the password is also “admin”.

Changing the admin password

Obviously you will want to change the password after you have successfully logged in the first time. But how do you do that? It’s not explained anywhere.

So after digging into the system for a while, the answer was found:

1. Go into System > User Accounts.
2. Click the pen icon associated with the user (in this case “admin”).
3. Click the “Change Password” link.

Voilà! The password is changed :)

Setting up your tax rate

The system defaults to a GST rate of 7%. While this would be correct for a large part of Canada, this is not correct for Ontario. So if this is not correct you will want to change this.

Go to System > Tax Rates and enter your correct tax rate (if you need to charge tax and it is not a 7% GST). Then go to System > System settings > Invoices and change the Default Invoice Tax Rate there.

Unresolved problems

If you try to create a test invoice at this point, you will get an error 1364, “Field 'contact_id' doesn't have a default value” and the error message will mention you have not customized your T&C. However, this error actually has nothing to do with T&C, so this is still unresolved.