Today I’m installing Ubersmith, a billing system solution, on a server to test it out. I have to say that Ubersmith has a more complex installation process than I’m used to these days. I guess that I’ve been spoiled.

Here’s a quick word about what I’m running. My test server is a dedicated system running CentOS 5.2 64-bit. The software setup is nothing special as most of the packages are straight from the repository.

I loaded the release files on the server, untarred them, and proceeded to read the instructions. Everything looked to be straight-forward. I quickly got down to the part about installing Ioncube. That’s when the trouble started.

I followed the instructions for getting Ioncube loaded, quickly modified my php.ini file, and restarted Apache. I then tried to access the site and got nothing. I looked at the logs and found that Ioncube wasn’t loading while reporting the following error:

Frankly, I had no idea what that meant. A bit of searching later, I find that I apparently have the wrong Ioncube loader. That didn’t make any sense since I loaded the exact loader that the ioncube-loader-helper.php program told me to use. I had a hunch that I knew what the problem was and decided to check it out. Yup, Ioncube Loader has 32-bit and 64-bit versions, the problem has to be that the Ubersmith code came with the 32-bit code. I downloaded a Linux (x86-64) archive from the Ioncube Loader packages page, loaded it up, restarted Apache again, and got Ioncube to load properly.

Ioncube was now loaded, but the page still didn’t render. Looking at the logs, I found this wonderful gem:

My first thought was, “great, the software is broken.” A quick google later, I found that mb_internal_encoding is part of PHP, but it is not a defaultly included option. I looked around at how to activate or add it, and everyone was going on about needing to recompile PHP. I’ve compiled everything from simple command-line tools to Apache2, but I always prefer using repository releases as it makes maintenance that much easier, so I was very upset to see that I needed to compile PHP with a new set of options just to run this software.

I was about to give up on Ubersmith altogether when I remembered how many amazing things package management can do. I ran “yum search mbstring” and found that there was a package called php-mbstring ready and waiting for me to install it. I ran “yum install mbstring“, restarted Apache, and finally the Ubersmith setup wizard was ready for me.

So, there are a few key pieces of wisdom that I have learned from my experience with installing Ubersmith:

1. Don’t trust that the installation documents/tools give you all the information you need. Ubersmith made a bad assumption that all systems will only require the 32-bit Ioncube while not making any notes that people on 64-bit platforms need to download new software. Ioncube’s installation helper neglected to check to see if the Ioncube files I had were built to work on my platform, and just like Ubersmith, the helper made no attempt to notify me that I may require different files depending on whether my platform is 32-bit or 64-bit.
2. Never trust that the third-party software packaged with another piece of software is the correct software for your system. If something breaks, first replace that packaged software with software freshly downloaded from the developer’s site.
3. When references say to compile your own software to get something to work, always remember to try using the package management tools first.

As I continued on the setup path, this wisdom had immediate use. The setup wizard indicated that two PHP extensions were missing: Mcrypt and XML-RPC. I immediately ran “yum search mcrypt” and “yum search xmlrpc” which returned positive results. I then ran “yum install php-mcrypt” and “yum install php-xmlrpc” and was golden. Just think if I had decided on compiling my own version of PHP earlier, I would have finally finished, gotten it working, and then had to do it all over again when I ran the setup and hit this snag. Thank you yum.

One thing that I have a gripe about is Ioncube’s navigation structure. I went to their site looking for download links for Ioncube Loader, and could not find them anywhere. I ended asking Google where I could find Ioncube Loader, and like a good little Google, it was right on the first try. I then tried again to find that page in the nav and found it under Products > Free Loaders for Encoded Files. I’m probably just daft, but I skipped right over that stuff because I was skimming the left side of the nav looking for something that started with “Ioncube …” not “Free …” At the very least, put links on the encoder pages that point to the loader page and say, “Looking for Ioncube Loader? Click here.”</rant>