Installing Atmail Webmail Client on Mac OS X (PERL)

Last week, my company decided to use a different webmail client with a better look and feel. I was assigned the job of searching for a good webmail client. I came up with some commercial ones and some free ones. My project leader shortlisted two of them (i) Round Cube (ii) atmail. I was asked to to do a demo setup of Round Cube. He did not like it because it was lacking some features that we wanted and also it wasn't a stable release then. Then I tried installing atmail on my Mac OS X Server machine. I tried to follow all the instructions from their website but couldn't get it to work properly. I emailed atmail's technical support team but they referred me to their knowledge base. I could not find instructions for Mac OS X Server there. Atmail Technical Support charges $100 for a remote installation of their product but my project leader wanted me to do it myself so that someone in the company could understand the product better.

I tried a lot of my Unix tricks but nothing seemed to work right for me. I was about to give up but then I came to know about ActivePerl, a free Perl interpreter for almost all OSes. I decided to use ActivePerl instead of Apple's default Perl interpreter for Mac OS X. I got atmail up and running successfully by using ActivePerl. Now, I have decided to write an article on this topic so that I could help others save some of their precious time.

Point to be noted before you begin: In my 8 years experience in IT industry, I haven't read a single tutorial that solved my problem completely without any extra effort. I am not claiming that there are no such tutorials but the point is that: DON'T EXPECT A LOLLYPOP SOLUTION HERE YOU MAY HAVE TO DO SOME EXTRA EFFORT.

Requirements:

Operating System:

  • Mac OS X Server version 10.4.8 ( other mac os x versions should work fine too)

Compilers / Development Tools:

  • Mac OS X developer tools (you can install them from your installation CD; look for Xcode Tools Package)

Software Required:

  • atmail (demo or production) version 4.5 (should work with later versions too). Download the source file with extension .tgz
  • ActivePerl (download it for free from http://www.activestate.com/Products/ActivePerl/?tn=1). Perl version greater than 5.6 is required by atmail.
  • Apache Web Server (I used the one that comes preinstalled with Mac OS X server)
  • MySQL Server and Client Libraries (download it from http://dev.mysql.com/downloads/mysql/5.0.html)

Make Sure Apache service is running properly. You can go to Server Admin and observe the DOT right beside Web. If it is green (or yellow) that means the Apache service is running else you have to click on Web and press the Start Service button from the menu at the top of Server Admin window. If you are not running Mac OS X Server then you can go to System Preferences --> Sharing --> Click the checkbox beside Personal Web Sharing. This should run Apache web server on your Mac OS X.

If you do not have MySQL installed, download and install it now. NOTE: You can install MySQL on any machine but make sure you install MySQL client libraries on the machine you are running atmail on.

The steps should be fairly simple but if you do not know how to install MySQL then refer to some other tutorial or let me know I'll try to add instructions for that or write a new tutorial completely. You need access to a MySQL database so ask the MySQL administrator to give you the username and password for the database. A separate database for atmail is recommended because this way you'll be able to restrict access and setup the database just for atmail. According to atmail manual, "The users needs full permissions over the table to modify/read/write". So give full permissions over the database to atmail user.

After isntalling MySQL, you have to install ActivePerl on your computer. Follow the standard Mac OS X procedures to install ActivePerl. Double click on the downloaded file and follow the instructions.

Now, you have to install some perl modules required for a successfull atmail installation. These modules are as follows:

  • Perl DBI module
  • Perl DBD::mysql module (named DBD-mysql in ActivePerl)
  • Perl Apache::DBI module (named Apache-DBI in ActivePerl)

In order to install additional Perl modules in Active Perl you have to run the Active Perl Package Manager ppm. On my computer ppm was installed in the folder /usr/local/ActivePerl-5.8/bin/ppm. You can find its location on your computer by using Mac OS X file finder or by running the OS X Terminal (command line processor; go to Applications --> Utilities --> Terminal) and running the command below.

sudo find / -type f -name ppm

This will tell you the location of the file. Execute the file ppm under bin folder as follows.

sudo /path/to/ppm/ppm

If it does not run this way and exits after startup then you'd probably have to run it from command line. (Go to "For command line" section below, if your gui window does not work properly).

This will open up a GUI window. Click on View --> All Packages to view all packages. First find DBI module by searching for it using the box at the top. Type "DBI" in the box, the list of packages will be shortened automtically and you'll see packages with the closest match. Right click on the package named "DBI" and select "Install DBI ". The package will be marked for installation. Now search for the other modules the same way and mark them for installation. After marking all the required packages for installation go to File --> Run Marked Actions. All required packages should now be installed.

For command line ppm:

NOTE: If you have already installed modules using the GUI method do not run the commands below.

Run the commands below:

sudo /path/to/ppm/ppm install DBI
sudo /path/to/ppm/ppm install Apache-DBI
sudo /path/to/ppm/ppm install DBD-mysql

Thats it you're done with Perl Package installation.

Now, you need to untar and unzip the atmail file that you downloaded earlier. Run the commands below to untar it in /usr/local/. First find where the downloaded file is by using Mac OS X file finder or by running the command below.

sudo find / -type f -name atmailwebmail-unix.tgz

Untar it by running the command below.

sudo tar xvzf /path/to/atmail/sourcefiles/atmailwebmail.tgz -C /usr/local/

Now, the trick is that you'll move the old perl interpreter to a different location and make a link to Active Perl's Perl interpreter in /usr/bin instead. Run commands below.

sudo mv /usr/bin/perl /usr/bin/oldperl sudo ln -s /usr/local/ActivePerl-5.8/bin/perl /usr/bin/perl

We are all set to run the installer. But before you run the installer make sure you have all the required configuration parameters. You need the following.

  • MySQL Database Name, Username, Password, and Hostname.
  • SMTP server and IMAP server hostname/addresses
  • Apache configuration files' location (sudo find / -type f -iname httpd.conf to find out the directory name where the files are located; should be under /etc directory)

Now, run the atmail installer using the new perl interpreter.

sudo perl /usr/local/atmail/webmail/install.pl

You'll be asked for configuration parameters. atmail installer may make changes to your Apache configuration file. After installation if you see the Final Note congratulating you on a scucessful setup then you're done.

Run your Apache web server (if its not running) and fire up your browser (from the computer where you installed atmail) go to http://127.0.0.1/mail/. If you are running a demo version then you should see the atmail login page or if you are using a production version then you'll have to register your product with the vendor.

Let me know if you find any errors. I'll add more notes here.

Did this tutorial help a little? How about buy me a cup of coffee?

Buy me a coffee at ko-fi.com

Please feel free to use the comments form below if you have any questions or need more explanation on anything. I do not guarantee a response.

IMPORTANT: You must thoroughy test any instructions on a production-like test environment first before trying anything on production systems. And, make sure it is tested for security, privacy, and safety. See our terms here.