One User's Testitool Installation Experience

Listed below is one person's experience installing Testitool, along with the other majordojo applications. A good read if you are experiencing problems yourself, and helpful because it covers the installation of Apache, MySQL, and PHP.

Setting up Testitool -- one user's experiences

Read the documentation at www.majordojo.com before this document, and always trust that source way more than anything you read herein.

ENVIRONMENT/CONTEXT NOTES

• This install was performed on RedHat Linux 7.0 and 7.3 boxes.
• Although PMI isn't a dependency, its integration with Bugzilla and its document - storage features were compelling enough to make me want to install it, too, so these notes refer to three majordojo applications:
  • php_users (0.9a6)
  • testitool (1.0-b4)
  • PMI (1.0-b1)
• I haven't yet done any Bugzilla integration.

OVERVIEW OF THE INSTALLATION STEPS

Install the following:

• Apache 1.3.x (I used .26)
• PHP 4.2.2
• MySql 3.23.51 (I installed server, client, shared rpms)
• mcrypt (libmcrypt-2.5.2)

Then install the three majordojo tools. Some detail follows.

INSTALL APACHE

This section contains mental breadcrumbs which may or may not be wise to duplicate in your environment, but which worked for me.

Installed Apache from source. Quick APACI config. Added option for shared object support:

./configure --prefix=/usr/local/apache --enable-module=so make make install

INSTALL MYSQL

Installed MySQL 3.23.51.*

*Why did I use an rpm for MySQL? (See below.)

Compiler Advisory: Several of our users have reported random crashes and table corruption with MySQL binaries compiled with gcc 2.96 on the x86 Linux platform. Although we were unable to duplicate the problems ourselves or understand their exact cause, we suspect with a great degree of confidence that the problem was compiler related. Replacing the faulty binary with our binary always eliminated the problem. We recommend that MySQL be compiled with gcc 2.95 if you have to compile your own binary at all. It is also acceptable to compile it with gcc 2.91 - builds with these compilers have been tested extensively. We would suggest, however, that you stay away from gcc 3.0 series until we have had some time to do some more extensive testing. The best solution in terms of stability and performance for most users is to use our binary instead of compiling their own. Please visit http://www.mysql.com/ to obtain an Official MySQL binary.

rpm -ivh MySQL-3.23.51-1.i386.rpm
rpm -ivh MySQL-client-3.23.51-1.i386.rpm
rpm -ivh MySQL-shared-3.23.51-1.i386.rpm

INSTALL MCRYPT

Set up mcrypt if you want encrypted cookies: Get source from ftp://mcrypt.hellug.gr/pub/crypto/mcrypt/libmcrypt. I built with

./configure --disable-posix-threads
make
make check
make install

INSTALL PHP

./configure --with-mysql --with-apxs=/usr/local/apache/bin/apxs \
            --with-mcrypt
make
make install
cp php.ini-dist /usr/local/lib/php/php.ini

Modify /usr/local/apache/conf/httpd.conf to add the following line:

AddType application/X-httpd-php .php

SETUP MYSQL DATABASE

Set the MySQL root user password:

mysqladmin -u root password '*******'
mysqladmin -u root -h [hostname] password '******'

Log into mysql with:

shell> mysql -u root -p

(enter the root password that you just set when prompted).

Our needs aren't huge, so I decided to lump everything into one database.

mysql> CREATE DATABASE testplans;
mysql> USE mysql;

Delete the anonymous default mysql user for security purposes:

DELETE FROM user where user="";

Add a SQL user (or several) for the majordojo applications (I defined one user for all three applications):

mysqladmin -u testitool@[myhostname] password '**********'
mysqladmin -u testitool@localhost password '**********'

Grant privileges and set passwords:

mysql> GRANT ALL PRIVILEGES ON testplans TO testitool@"mazu-stacy.mazunetworks.com" 
mysql> IDENTIFIED BY 'xxxxxxx' WITH GRANT OPTION;

mysql> GRANT ALL PRIVILEGES ON testplans TO testitool@"localhost" 
mysql> IDENTIFIED BY 'xxxxxxx' WITH GRANT OPTION;

(Afterwards, you can access this database from the shell with:

shell> mysql -u testitool -p testplans

INSTALL MAJORDOJO APPLICATIONS

Create a directory in which to untar the majordojo tools (e.g., /usr/local/majordojo).

Untar each of the application tarballs into it.

You'll be happier if you remember to create more simply-named symlinks for each tool within that directory.

ln -s php_users-0.9a6/ php_users
ln -s pmi-1.0-rc2/ pmi
ln -s testitool-1.0-b4/ testitool

Read all of the majordojo install/readme docs. Twice.

I populated databases with:

mysql -u testitool -p testplans < /usr/local/majordojo/pmi/schemas/mysql
mysql -u testitool -p testplans < /usr/local/majordojo/testitool/schema/mysql
mysql -u testitool -p testplans < /usr/local/majordojo/php_user/schema/mysql

If you want the sample data, also load the mysql sample data:

mysql -u testitool -p testplans < \
    /usr/local/majordojo/testitool/schema/mysql.test_data

At this point, you should be able to log into testplans as testitool and see this:

mysql> show tables;

+-------------------------+
| Tables_in_testplans     |
+-------------------------+
| Profiles                |
| ProjectTeamMembers      |
| Projects                |
| Releases                |
| Users                   |
| categories              |
| category_watch          |
| document_categories_map |
| documents               |
| events                  |
| execution_instance      |
| logged_bugs             |
| login_tokens            |
| project_watch           |
| projects                |
| release_milestones      |
| test_cases              |
| test_notes              |
| test_plans              |
| tests                   |
+-------------------------+

13 rows in set (0.00 sec)

MODIFY APACHE'S HTTPD.CONF

I'm going to blather about Apache's httpd.conf first because some of the majordojo configuration settings fall out of how you decide to slice your web server.

I added a Virtual Host using localhost -- however, the server name must have two components in order for cookies to work (machine.domain), thus, my server name became testitool.localhost. You probably won't even have to think about this, assuming that you're using a real server name. (Thanks to Byrne for helping me past this part.)

So the added pieces of my httpd.conf look like this:

NameVirtualHost 127.0.0.1
<VirtualHost 127.0.0.1>
   ServerAdmin root@localhost
   ServerName  testitool.localhost
   DocumentRoot /usr/local/majordojo/testitool/htdocs
   ErrorLog /usr/local/majordojo/logs/error_log
   CustomLog /usr/local/majordojo/logs/access_log common
</VirtualHost>

Alias /projects/ "/usr/local/majordojo/pmi/htdocs/"
Alias /users/ "/usr/local/majordojo/php_users/htdocs/"
Alias /testitool/ "/usr/local/majordojo/testitool/htdocs/"

<IfModule mod_dir.c>
   DirectoryIndex index.phtml index.html index.php
</IfModule>

<IfModule mod_php4.c>
   AddType application/x-httpd-php .php
   AddType application/x-httpd-php .phtml
   php_value include_path ".:/usr/local/majordojo/php_users/:/usr/local/majordojo/testitool/:/usr/local/majordojo/testitool/fragments/:/usr/local/majordojo/pmi-1.0-b1/"
</IfModule>

Note: the testitool Alias for testitool isn't strictly necessary since the DocumentRoot of the default-ported Virtual host points to it, but I added it as a convenience so that I could get there from [server]/testitool/, too.

MODIFY TESTITOOL.CONF

Set to the correct database values for you:

< $TESTITOOLDB = "testplans"; < $TESTITOOLDBUSER = "testitool"; < $TESTITOOL_DBPASS = "XXXXXX";

If you're not using Bugzilla, leave:

$BUGZILLA_INTEGRATION = 0;

MODIFY USERS.CONF

< $USERSBASEURL = "http://localhost/users"; became

$USERSBASEURL = "http://testitool.localhost/users";

< $COOKIEDOMAIN = ".localhost.localdomain"; # $SERVERNAME; became

$COOKIEDOMAIN = ".testitool.localhost"; # $SERVERNAME;

< $COOKIE_KEY = "my key";

stayed the same.

Set the three database settings as appropriate.

MODIFY PMI.CONF

I'm going to bow out of the document path settings in this section, actually, because I haven't really used this product much. Set the three database settings as appropriate.

If you're not using Bugzilla, leave:

$BUGZILLA_INTEGRATION = 0;

Restart Apache and point a browser at your new management system. Log in with the default user (see user/pass in the Users table in the php_users database).

TROUBLESHOOTING SECTION

MySQL and PHP have awesome troubleshooting sections on their web sites.

After you have PHP running happily and have checked the MySQL tables, there's not a heck of a lot else that can go wrong without the reason being apparent from error messages.

More misc. tips anyway:

Load a test php page in your environment.

Use the "create a new user" link in loginbox.php and go through the steps of enabling the new user. Confirm that they show up in the User table.

Double-check your ServerName in all of your .conf files and your Virtual Host section in httpd.conf.

Double-check that your $COOKIE_DOMAIN begins with a dot.

Confirm that your php_include value in httpd.conf includes everything that it should (see example above) and that it appears all on one line.

Make sure that you can log into the database(s) with the expected usernames directly from mysql, and that data appear in the tables that you expect them to be in (e.g. Users).

Try renaming the mcrypt cookie name in users.conf if you're having cookie problems.

Read all of the majordojo READMEs and INSTALL docs again. (Did you make the php.ini change, for example?)