Software development techniques behind the magic user interface

Multi-Touch Developer Journal

Subscribe to Multi-Touch Developer Journal: eMailAlertsEmail Alerts newslettersWeekly Newsletters
Get Multi-Touch Developer Journal: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn


Multi-Touch Authors: Ben Bradley, Qamar Qrsh, Suresh Sambandam, Jayaram Krishnaswamy, Kevin Benedict

Related Topics: Apache Web Server Journal, MySQL Journal

Apache Web Server: Article

How to upgrade Nola, the free accounting package for Linux

In Part 16 of our Linux for Peanuts series, we bring Nola up to date

(LinuxWorld) -- The GPL'd business accounting package Nola that we have been working with is a project under development. In Part 15 of our series, we set up a Nola Web server using Red Hat 7.2, and Nola stable release 1.1.1 and if you followed along, and set up your own, perhaps you've been exploring the empty halls of your new online accounting department.

If you did, you probably also know that Nola is now at stable release 1.1.2 and you may even be wondering why we didn't use that newer version to set up the system. After all, most articles and tutorials advise you to download the latest version of everything.

Well, not here. Nola is still somewhat beta although some companies may find it satisfactory today. (You'll note that I am taking the coward's path in not declaring that Nola is, or is not ready for production deployment. Every company has unique needs and capabilities, and will have to make that decision on their own.) In any case, being a GPL'd offering, we can expect development to continue and updates provided as they become ready -- on a more or less continual basis -- and not on a market-driven upgrade cycle.

When you take on a business accounting system, you're in it for the long haul. If we are going to trust our data to the application, we want to be certain that it is easily kept up-to-date. Yep, it's a contrived exercise! We will be upgrading from 1.1.1 to 1.1.2 in this installment because we want to know now whether it is difficult and dangerous to update Nola, or a simple and reliable process. Be honest, if you hadn't installed the outdated version, you wouldn't get the opportunity to upgrade until a newer version is available, now would you? Then you'd be tempted not to upgrade for fear of breaking it, wouldn't you? Don't curl your lip and snarl at me, I did this for your own good! (Sort of like heaping your plate with cabbage and refusing to indulge you in your preference for a diet of nothing but beer and chocolate bars.)

In a perfect world, updating a LAMP (Linux+Apache+MySQL+PHP) application should be as easy as replacing a light bulb. This isn't a perfect world (if it was perfect, you wouldn't have been subjected to that bad play on words), but I think you will find that upgrading Nola comes pretty close to the ideal.

Oh, and by the way...

We will also discuss some (how can I put this without revealing myself as an idiot?), shall we say, "Nola Administrator Worst Practices," that will hose everything. Yes, you guessed it. I wanted to learn some of the things an administrator can do wrong that will cause major problems. I actually didn't find many. I did find one that I suggest you never do. We will get to that later in this article.

First, I will try to redeem myself by showing you how to update Nola to the latest release.

Step 1. Download the latest stable release...

Once again, at the time of this writing, Nola is at stable release 1.1.2. You can download it at http://nola.noguska.com/download.php. Select nola-current.tar.gz, a 4.86-megabyte download. You will also find links at the site to "nightly builds," as well as to both a CVS repository and earlier versions available via ftp. I recommend you avoid these if your intent is to determine whether Nola is ready for production use in your business. Stable is stable. Anything that isn't stable...well, you get the picture. If you decide Nola doesn't quite meet your needs just yet, then certainly -- check out the nightly builds and see if Nola's developers are addressing your concerns.

In my case, I don't download the file directly to my Nola server. My network's application server has an exportable directory that I use for downloads, and I use NFS (Network File System) to transfer the file to my Nola server when I'm ready to upgrade. This way, I have a local repository of all the files needed to set up a Nola accounting server, and as I experiment, if I choose to wipe out everything and start over with a fresh Linux install (perhaps another distribution), I don't have to go through the bother of downloading all the files again.

(If you just joined us, and are a bit hazy as to how to quickly set up another Linux machine as rudimentary NFS server, you might want to review the earlier installments in this series. There are links to them at the end of this article. I provide some tips, and in the process, you'll drive up my page views! Okay, okay, I'm devious and self-serving. What else is new?)

Some time back, I decided to create a directory called /home/nola-files on my application server for this purpose, and that's where I save nola-current.tar.gz

Step 2. Mount the NFS directory...

First, login as the root user on the machine you set up with Nola. Assuming you followed the conventions for IP addresses we established in this series, and assuming that your application/NFS server's IP is 192.168.1.10, and further assuming that you just downloaded nola-current.tar.gz to an exportable directory named /home/nola-files (that's a lot of assumptions on my part, isn't it?), you mount the remote directory like this:

mount -t nfs 192.168.1.10:/home/nola-files /mnt [ENTER]

This command will mount the remote directory, located on a hard drive physically installed in your application and NFS server, on the Nola server you are now seated at, under the mount point /mnt. You can now change to that directory:

cd /mnt [ENTER]

Peruse the file contents with:

ls -l [ENTER]

Step 3. Copy the newer version to the Nola server...

Assuming (again with the assumptions!) that ls -l revealed the presence of nola-1.1.2.tar.gz under the /mnt directory, copy the newer version to Apache's "ServerRoot" directory as determined by the /usr/local/apache/conf/httpd.conf file. In Part 15 of our series, we didn't touch the default value for "Server Root," so on our example system, it remains /usr/local/apache and the default "DocumentRoot" directory specified in httpd.conf was changed to /usr/local/apache/nola. You say you decided to assert your individuality and put things somewhere else? Fine. Go your own way, ungrateful, non-conformist wretch that you are. You'll have to adjust the procedure to reflect the "ServerRoot" and "DocumentRoot" locations you specified. The rest of us will content ourselves with /usr/local/apache and we copy the file like this:

cp /mnt/nola-.tar.gz /usr/local/apache/ [ENTER]

If we change to /usr/local/apache and pipe ls -l through less, we should be able to scroll up and down to verify that our file is copied over. We may as well unmount the NFS directory as well, after copying the file over:

cd  /usr/local/apache [ENTER]
ls -l  | less [ENTER]

Is it there? If nola-1.1.2.tar.gz is now safely parked in /usr/local/apache, you can unmount the remote directory:

umount /mnt [ENTER]

Step 4. Unpack the newer version of Nola...

We use the tar utility to unpack nola-1.1.2.tar.gz (See man tar for more info). Don't worry that this will overwrite your existing /usr/local/apache/nola directory because this is what we intend for it to do. Any data you may have entered into your Nola accounting system is stored in the MySQL database under /usr/local/mysql/var/noguska. That data isn't overwritten, just the Web-based front-end to MySQL under /usr/local/apache.

(A Faulkneresque parenthetical digression: This is not to suggest that you shouldn't perform regular backups of the data consigned to MySQL, nor that you shouldn't perform a backup immediately before upgrading Nola. It is simply that at this stage of our exploration, we are as concerned with uncovering the ways we might break the system by accident, and through our negligence, as we are with learning the functionality and features of Nola. Consequently, it is in our interest to press our luck and try to uncover the dangers before we commit to a production deployment. As you will see shortly, the upgrade process will occasionally involve some changes to the database. In discussion with Nola's developers, it is intended that these changes can be made without loss of data, but then, as they say, "the best laid plans of mice and men...")

Make certain you are in /usr/local/apache and uncompress the tar file:

tar xzvf nola-1.1.2.tar.gz [ENTER]

After a short burst of text whipping by on the monitor as all the files and subdirectories overwrite your old nola directory, you are returned to the command prompt. The tar command not only creates a new nola directory, it leaves the original tar file intact. We no longer need nola-1.1.2.tar.gz cluttering up our "ServerRoot" directory, because we can always get another copy via NFS from our other server, so we may as well get rid of the local copy now:

rm nola-1.1.2.tar.gz [ENTER]

Step 5. Transfer ownership of the directory...

If you recall our original installation of Nola, one of the steps was to change ownership of the nola directory from root to user apache. The user, apache is also a member of the group apache and we avoid the need for two separate commands (chown and chgrp) to do this by invoking chown as follows: (By now, you should be able to guess that man pages, as in man chown, man chgrp, etc., are the first places to look for additional information!)

chown -R apache:apache /usr/local/apache/nola [ENTER]

Step 6. Do we need to upgrade the database?

No, or rather, we don't need to upgrade to a newer version of MySQL. There are times you may upgrade Nola, and aside from a shutdown and restart of Apache and MySQL, be done with the job as soon as you complete Steps 1 through 5 above. But, other times, Nola's developers will make some changes to the MySQL database "schema" -- tables, names, etc., -- found under /usr/local/mysql/var/noguska.

This raises some questions, such as:

  • Does this represent a risk to data stored in the database?
  • How do we accomplish this task?
  • How do we determine that it needs to be done?

To answer these questions, I asked Nola's developers. In their opinion, the risk to data is minimal, although present, and backups should be made before an upgrade. We will skip that for now, because we are actively looking for things that might trash the system.

At some time in the future, the method used to upgrade will be different. Rather than the manual upgrade we are going to perform, it is their intent to provide an upgrade script that will take care of everything. We shall see whether this happens, and for now, they were kind enough to explain how to perform a manual upgrade of the database schema.

The answer to the third question is simply to look inside our just-unpacked nola directory and inspect it for the presence of a particular file. If it exists, we need to manually update the database. If it doesn't, we are all done with the upgrade and we can reboot our server. So let's go check it out...

Step 7. The all-important "upgrade from" script...

Remember back in Part 15 of our series when you originally installed Nola and created the noguska database under /usr/local/mysql/var? (You're growing sleepy, your eyelids feel as if they have little lead weights hanging from them...snap out of it! Right now! This was a career decision you made.) We need to look in the same location to see if an upgrade is in order:

cd /usr/local/apache/nola/documentation/sqlscripts/MySQL [ENTER]

Now we run the ls -l to see what we have:

drwxr-xr-x    2  apache   apache       1024       Apr 20  14:07   CVS
-rwxr-xr-x    1  apache   apache     89637       Feb  5   06:04   database.sql
-rwxr-xr-x    1  apache   apache  3109529      Jan  15  15:33   filldata.sql
-rwxr-xr-x    1  apache   apache          140      Jan    8  05:58   upgrade.from 1.0.0.sql
-rwxr-xr-x    1  apache   apache      64015      Jan  15  17:25   upgrade.from 1.0.1.sql
-rw-r--r--    1  apache   apache         168      Jan   18  08:14   upgrade.from 1.0.0a.sql
-rw-r--r--    1  apache   apache       1955      Jan   18  08:14   upgrade.from 1.1.1.sql

The last line, containing upgrade.from.1.1.1.sql tells us we have a little more work to do. We originally installed version 1.1.1 and are upgrading to 1.1.2, therefore we have to upgrade from 1.1.1. Duh. If no such file is found, then all we need to do is reboot the machine, or restart Apache. Another duh.

If you would like to see the changes that will be made to the database before you perform the upgrade, you can look at the contents of the file with less, as in:

less upgrade.from.1.1.1.sql [ENTER]

Step 8a. Upgrading the database schema...

The process is similar to that used when we originally created the noguska directory during the initial Nola installation. From the /usr/local/apache/nola/documentation/sqlscripts/MySQL directory, you simply invoke the following:

/usr/local/mysql/bin/mysql noguska < upgrade.from.1.1.1.sql [ENTER]

Without any error messages or evidence of problem, you are returned to the command prompt. You may now reboot your server -- UNLESS -- you got all uptight and officious since we installed Nola in the last installment, and heeded the security warnings, and used the mysqladmin utility and set the MySQL root user password. If you did that, you got a whole bunch of errors and complaints and "access denied" messages. (You weasel! This is a test set up behind a firewall! Why did you have to get fancy and mess around like that? Huh? Huh? Do you really believe there's an "Axis of Evil" poised to jump all over your test server? Well, maybe there is and I guess it doesn't hurt to take a few precautions.)

And so...

Step 8b. Upgrading with MySQL password protection in place...

If you followed the advice most MySQL tutorials provide, you used mysqladmin to set a MySQL root user password. I won't attempt to quantify the security risks of not doing that, except to say that in a reasonably trusted small business network environment, behind a decent Linux firewall, the risk appears minimal. You decide for yourself, and of course, in a medium to large business, or in any situation where your Nola server is accessible from the Internet, paranoia isn't just healthy -- it's a requirement for survival.

I actually have Nola running on several boxes and, on one of them, I did set a MySQL password. Then I promptly forgot that I had done so. (Pan to beet-red face of author.)

Ummm, anyhow...oh what the heck. There's no way to save face here. Following the advice of Nola's developers, I proceeded to attempt to upgrade the database schema to 1.1.2. With my brain in neutral, I tried to make it work. Repeatedly. After a short session of tearing at myself which left wads of hair on the floor all around my desk, I fired off a hasty e-mail demanding to know what was wrong with this stupid thing.

The reply came an hour or so later. Here it is, in it's entirety (except I left off the signature to protect the time and privacy of a very busy individual):

"...Any access denied message given while running a Nola upgrade script means that MySQL is rejecting the username / password that was passed to it. If you created a mysql user named 'root', with a password of 'dbpass', and your Nola installation was using the default database name of 'noguska', a proper command to have MySQL run the Nola upgrade script could be:

mysql -u root -pdbpass noguska < nola/documentation/sqlscripts/MySQL/upgrade.from.1.1.1.sql

More information on MySQL permissions is available from the MySQL manual..."

Uhhh, password? What password? Then I checked my notes.

Oops.

Yes, it worked fine. Get off my back. Sheeesh. Just reboot your server and go about your business. I'm just going to sit here in the dark for a while.

Step 9. Show menu items as images?

You may get some errors after you reboot your server and login again from a Web browser. Nola gives a choice of displaying menu items as images or as text, and there's occasionally some tweaking involved to display them as images. Why bother? I prefer text anyway, because I despise having to guess what some little picture is supposed to represent when there is no text to accompany it, and if there is text, I don't like an image just cluttering up the space. This is an accounting server, not some soda pop company's Web site that promotes caffeinated fizz-water for kids and bleary-eyed Web site editors.

To eliminate all this, and to display menu items with a serious, sober appearance -- more suited to GAAP standards than some pro-forma style image would be -- login at the Nola server's local console and change to the /usr/local/apache/nola/includes directory.

Open the defines.php file with a text editor such as sucky old vi (Ed. Can we make that "the classic text editor"?) and scroll down until you encounter the "Menu Section." At the end of this section are six lines that read:

//show menu items as images
  define('MENU_SHOW_AS_IMAGE', '1');
//show explain items
  define(EXPLAIN_SHOW_AS_IMAGE', '1');
//show icons on explain* submenus
  define('EXPLAIN_SHOW_PICTURES', '1');

Now, change the "1" to a "0" ( a zero, not an "oh" -- duh) in each of these lines, so that they now read:

//show menu items as images
  define('MENU_SHOW_AS_IMAGE', '0');
//show explain items
  define(EXPLAIN_SHOW_AS_IMAGE', '0');
//show icons on explain* subgenus
  define('EXPLAIN_SHOW_PICTURES', '0');

Then reboot. Easy enough, now isn't it?

"Mistakes were made..."

Yes, indeed. The next item wasn't really an oversight, or memory lapse, like forgetting that I had set a MySQL password. It was more on the order of a stupid blunder.

One of the interesting features of Nola is that you can set it up for multiple companies. This might be attractive to a book keeping firm with several small sole proprietorships as customers...perhaps an independent home repair contractor or two, owner/operator truckers, you name it. One-man and one-woman shows needing to outsource basic book keeping, billing, etc., because there is no one on staff to do the job.

In the process of testing (playing with?) Nola, on one machine, I set up a few little client companies, and then decided to clear them out of the way in preparation for more tests.

If you login to nola as "admin," you have powers similar to "root" on a local console. In other words, you possess the power to destroy. New client companies are added to Nola, by "admin," under the admin link on the Nola navigation frame on the left side of the page. (You have to login as 'admin" first, or this link doesn't appear.)

Do not, repeat, DO NOT delete all the client companies and then logout, with the intent of coming back later and adding a new company. If you do this, you are going to be sorry. Nola won't let you back in. Ever. It just sits there, reporting, "No companies found. Cannot continue." Want to see what it looks like?

Author's Nola blunder documented. Click to see a larger image.

Sometimes it feels very cold when you are locked outside. Learn from the mistakes of others, and to learn more, rejoin us for Part 17 as we delve deeper into the mystery and power of Nola!

More Stories By Colin Mattoon

When not buried under his real job in commercial two-way radio system design and sales, Colin Mattoon is a part-time Linux system administrator at Northwest Communications in Lewiston, ID.

Comments (1) View Comments

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


Most Recent Comments
Fred Finster 01/18/05 12:56:12 AM EST

I also have the not installed No MySQL connection message as above on my Debian MySQL, Nola, Apache testing setup.

I see that file /usr/share/apache/noloa/includes/my_defines.php needs some editing with the VI editor to change the line

define('DB_SERVER_USERNAME', 'root');
define('DB_SERVER_PASSWORD', 'changethis');

to

define('DB_SERVER_USERNAME', 'mysql');
define('DB_SERVER_PASSWORD', 'mysql');

I am using an upgraded version of knoppix 3.2 with KDE 3.3.1
and apt-get or synaptic install of mysql software

Banging my head at the momemnt getting the apache and MySQL to interoperate, but reading through the NolaPro website documentation to locate more specific files to change.

Maybe the MySQL Port connection needs to be set in some file define. Maybe it uses the default port connection 3306 or 63306

To change the port NolaPro's MySQL database runs on, open up the file NolaPro/Apache/mysql/my.ini in a text editor. Change the line “port=63306” to read “port=X” where X is your new MySQL port number. If you decide to make this port something other than 63306 or MySQL's default port 3306, you will need to make a change in one other file.

Change the line “define('ALT_MYSQL_PORT',':63306');” in the file NolaPro/Apache/htdocs/includes/my_defines.php to
“define('ALT_MYSQL_PORT',':X');” where X is your new port number other than 63306 or 3306. After making changes you will have to restart the MySQLNolaPro service. Open up the Control Panel, Administrative Tools and Services. Right click on the service named MySQLNolaPro and select restart. Close all browser windows and log back into NolaPro.

See this www.nolapro.com website for more information
http://www.nolapro.com/index.php?content=documentation_faq

http://www.nolapro.com/index.php?content=documentation_faq