Welcome to Anthill!
Anthill's home page is anthill.vmlinuz.ca.
Table of Contents
Anthill is free software and is released under the GNU GPL License version 2.0 (see the COPYING file for details).
Anthill is the product of a need that Bugzilla could not fill. Quite frankly, I found Bugzilla to be bulky and overly-complex for what I needed. And configuring Bugzilla to look different turned out to be an overly-huge ordeal that I couldn't be bothered with. At the time, I thought writing my own software in PHP would be easier and faster. I was right on the first count, wrong on the second. The time it took for the first public release of Anthill was roughly six months. I'm sure in that time I could have configured Bugzilla the way I wanted to, but then you wouldn't have this really cool software to play with. =)
Anthill is a very mature product used by many individuals and organizations to handle their bug reporting tasks. However, it is an in-development project with new features, enhancements, optimizations, etc. being added over time. Anthill is meant to be feature-rich while reducing it's complexity. In short, I wanted a bug tracking database system with few pre-requisites (like additional software such as PHPlib), and one that was quick and easy to get up and running. I believe this has been accomplished.
Anthill was originally written to handle the MandrakeSoft Secteam bug-tracking interface. The first bug ever reported in an Anthill installation was May 25th, 2001. Anthill was in development for roughly six months prior to that.
Anthill is free software and comes without any warranty of any kind and no technical support other than what you will find on the mailing lists. Many hundreds of man-hours have gone into work on Anthill, and expressed appreciation is more than welcome. This can come by dropping me a note letting me know how much you enjoy Anthill, a monetary donation via PayPal to help encourage future development, adding a link your Anthill installation (if public) on the Anthill home page... Letting me know that you value and enjoy Anthill will encourage me to continue spending valuable time on the software.
Anthill requires a webserver (such as Apache) and PHP 4.1 or higher. Your PHP must have gettext support compiled in. This is not something you can enable or disable "on the fly". PHP must have been built with:
./configure --with-gettext
You can easily check if you have gettext support by issuing on the commandline:
echo ""|/usr/bin/php|grep gettext
Of course, change the path to the php executable to wherever it is installed on your system. If nothing is returned by grep, gettext support is not compiled into the PHP installed on your system and will require you to recompile PHP with gettext support prior to using Anthill.
Anthill also requires that your PHP installation has mail() support compiled in and on *NIX systems this requires you to install a vendor-supplied PHP or compile it with sendmail (or at least /usr/sbin/sendmail) on the system. If this file does not exist, PHP will build without mail() support.
Finally, Anthill requires a database backend. Currently only MySQL is fully supported. Plans are in place to use a database abstraction layer so that other backends like PostgreSQL can be used.
You must also have your PHP configured to allow short open tags; you can verify this by editing your php.ini file and make sure that:
short_open_tag = On
is set.
The installation of Anthill is quite simple. As of version 0.2.4 Anthill's directory filesystem layout has changed. In the interest of security, you should no longer unarchive the distribution archive into your webroot directory (ie. /var/www/html). You should instead create a new directory specifically for Anthill, such as /var/www/anthill. Unarchive the distribution package there.
Change to that directory and edit html/include.php. Change the path in the include_once() function to the your config.inc.php file (which would be ../include/config.inc.php or /var/www/anthill/include/config.inc.php). You cannot use relative links here, however. You must specify the full path to the config.inc.php file. Once you have saved this file, change to the include/ directory and edit config.inc.php. This file contains a number of variables that must be defined. Instructions as to what each variable means is detailed in the file itself.
Anthill configuration is done in two places: Online via the administration link and via the include/config.inc.php file. This was done to allow the more-often configured options to be handled via the web interface and the more permanent settings to be done in a configuration file. To properly configure Anthill, you need to understand the contents of the config.inc.php file.
The first section of config.inc.php deals with file locations:
$_CONF['root'] = "/Volumes/Users/vdanen/code/anthill-0.2/html"; $_CONF['incdir'] = "/Volumes/Users/vdanen/code/anthill-0.2/include"; $_CONF['webroot'] = "http://tibook.linsec.vx"; $_CONF['imgdir'] = "/images"; $_CONF['tmpldir'] = "/backend/template"; $_CONF['langdir'] = "/backend/language"; $_CONF['shadowdir'] = $_CONF['root'] . "/shadow"; $_CONF['tmpdir'] = $_CONF['root'] . "/tmp"; $_CONF['gpgdir'] = "/gpg"; $_CONF['attachdir'] = "/attachments"; $_CONF['cssfile'] = $_CONF['webroot'] . "/anthill.css"; $_CONF['difftool'] = "/usr/bin/diff";
This is all quite straightforward. $_CONF['root'] is the location on the filesystem for the html/ directory of Anthill. This directory is what is publicly exposed via the web server. The "incdir" option points to the include/ directory; this directory should not be publicly exposed. Ie. in Apache, you should have the DocumentRoot pointing to "root" and not the anthill directory itself. The "webroot" option is where the Anthill installation will be made available via the web. The next options are relative paths to various directories; they are re-locatable so you can rename the attachments directory and move it if you like.
The final option, "difftool" points to the location of the diff program which is used to generate the emails Anthill sends out. If you have safe_mode enabled in PHP, you must include the directory this program lives in otherwise Anthill will not work properly.
$_CONF['datefmt'] = "Y-m-d"; $_CONF['timefmt'] = "h:i A";
These options specify the date and time formats used across the site. You can change these to whatever suits you. To see the different codes you can use read the PHP reference manual: http://www.php.net/ manual/en/function.date.php.
$_CONF['cookie_timeout_permdef'] = "86400"; $_CONF['cookie_timeout_session'] = "7200"; $_CONF['cookie_name'] = "anthill"; $_CONF['cookie_session'] = "ant_session"; $_CONF['cookie_path'] = "/"; $_CONF['cookie_domain'] = $_SERVER['SERVER_NAME']; $_CONF['cookie_secure'] = 0;
This section deals with cookie settings. The "cookie_timeout_permdef" option specifies the default seconds for cookie expiry for permanent cookies. Users are able to select their cookie expiry via their Preferences, so this is the system default: one day. The "cookie_timeout_session" option determines the default seconds for cookie persistence and is only useful if you do not want permanent cookies set. With permanent cookies, this is largely ignored.
The "cookie_name" and "cookie_session" options should be unique to your system as they are the names for the main cookie and the session cookie.
The "cookie_path" determines the path where the cookie is valid. You should leave this at the default "/" unless you have a reason to change it. The "cookie_domain" setting defaults to the name of the server which should be sufficient in most cases. Finally, "cookie_secure" determines whether the cookies should only be sent over an SSL connection. This should not be set unless you only allow access to Anthill via SSL.
$_CONF['meta_lang'] = "utf-8";
This option determines the charset sent in the HTTP headers. This setting should not be changed unless you really need to set it to one specific charset.
$_CONF['forcereturn'] = "0";
This option was introduced in Anthill 0.2.6 and is useful with certain MTA's, although it is unnecessary for others. For instance, if you have your php.ini set to send mail to localhost:25, you do not need this. This is only useful for MTA's like sendmail, postfix, and exim that do not set the Return-Path despite the fact that we set the header. With these MTA's, the Return-Path is set to the localhost name (ie. tibook.linse.vx) and the user of the web server (so you would have a Return-Path set to www@tibook.linsec.vx, for example). This may not be desired if you wish bounces to be sent back to the anthill-daemon (which likely would be, or should be, set to a human mailbox to catch these errors). If you are using qmail, you do not need to set this option. As well, if you use safe_mode, this option has no relevance as PHP will not allow us to pass commands to the sendmail (or similar) binary. With postfix, you do not need to make any configuration changes for this to work, however with exim you will need to set the "trusted_users" option to the user running the web server otherwise the option will be ignored. If you are unsure whether or not you need this, it is advised to leave this at the default setting of "0" (or off).
$_CONF['db_user'] = "anthill"; $_CONF['db_pw'] = "pass"; $_CONF['db_host'] = "localhost"; $_CONF['db_name'] = "anthill"; $_CONF['db_type'] = "mysql";
These options deal with the database backend. Currently only MySQL is supported, so "db_type" must be set to "mysql". The other options determine the user to connect to the user as, that user's password for the database, the hostname of the database, and the name of the database to use. You should change these from the defaults.
Once you have completed this and defined the database name for Anthill, you need to create the database structure. Currently, Anthill only supports MySQL.
Create the database you plan to use (defined as $_CONF['db_name'] in config.inc.php) by issuing:
# mysqladmin -u root -p create anthill
if "anthill" is the name of the database you chose. This will create the database. Next, import the database structure using:
# cd etc # mysql -u root -p anthill < sql.dump
Log into MySQL to give your anthill user access to the database:
# mysql -u root -p mysql>> GRANT ALL ON anthill.* TO anthill@localhost IDENTIFIED BY "pass";
Obviously, change "anthill@" to the user you defined as $_CONF['db_user'] in config.inc.php and "pass" to the password defined as $_CONF['db_pw'].
There is a default "admin" user with the password "test123" (without quotes). Be sure to log in as that user and edit your preferences to change the password and also configure some Anthill configuration basics.
Before making your Anthill installation public, you will have to take care of a few permissions issues. There are four directories that need to be owned by the user running your webserver (ie. "nobody" or "apache") in the Anthill directory tree: html/shadow/, html/tmp/, html/gpg/, and html/attachments/. To do this, go into your Anthill root directory and execute:
# cd anthill # chown apache.apache shadow tmp gpg attachments
Replace "apache.apache" with "nobody.nobody" if your webserver runs as the user "nobody" (or any other user name it may run as). The other option is to make those directories world writeable, but that presents security risks. It is better to have the directories owned by the user running the webserver because Anthill needs to write to each of these directories. The directories should likewise only be mode 700, so only the webserver user can read, write, and execute in the directory. You can make that modification by executing:
# cd html # chmod 700 shadow tmp gpg attachments
In Anthill 0.2.0pre3 a .htaccess file was included in the include/ directory because it was in the publicly accessible web tree. With 0.2.4, the include directory should be outside of what is publically accessible, so it is no longer necessary to keep the .htaccess file there.
Anthill can, and has, been used on many different platforms. I deploy it on Mandrake Linux systems and develop on Mac OS X. The Linux installation instructions are extremely straight-forward; if you have Apache and PHP 4.1+ installed as per the instructions in the requirements, you have nothing else to do. For other operating systems, here are some general (or specific) instructions. I welcome additions to the documentation if you feel something is inaccurate or wish to add some information (possibly for a different web server or OS).
Updating PHP for Apache 1.x in Mac OS X
Anthill will work with very few changes from the Linux instructions noted above, but there are a few significant differences. First, Apple ships with Apache itself and does not configure it to use PHP out of the box, although PHP is installed. However, Apple's PHP, while having support for MySQL, does not have support for gettext. Marc Liyanage has contributed a binary libphp4.so for OS X users on his web site:
http://www.entropy.ch/ software/macosx/php/
Now, his module doesn't have gettext support either, which is essential for Anthill to operate. You will have to rebuild PHP yourself. Marc has some good instructions on how to build PHP at the end of his page as well, including a patch to apply to 4.2.3 (which was used for testing Anthill on OS X). The following is the ./configure line I used to build my copy of PHP 4.2.3 which works fine with Anthill:
./configure --with-apxs --with-mysql --with-gd=/sw --with-png-dir=/sw \
--with-zlib-dir=/usr --with-jpeg-dir=/sw --with-freetype-dir=/sw \
--with-t1lib=/sw --enable-trans-sid --enable-exif --with-xml \
--enable-wddx --with-curl=/sw --enable-ftp --enable-mbstring \
--enable-mbstr-enc-trans --enable-sockets --enable-dbx --enable-dbase \
--with-gettext=/sw
You will need some additional libraries if you want some of the features like gd, t1lib, etc. I found the best way to install these is to use Fink and build the latest versions from unstable sources. When you build PHP and if it complains about being unable to find something, you must install the corresponding libraries or remove the call from your configure line. You will have to install gettext via Fink prior to building PHP. There are no other functions in Anthill, at this time, that require any external libraries. All of the configuration options pointing to /sw are Fink packages.
If you don't want to compile PHP, you can download a libphp4.so from the Anthill website. You can install it by executing:
$ curl -O http://anthill.vmlinuz.ca/files/libphp4.so.bz2
$ bunzip2 libphp4.so.bz2
$ sudo cp libphp4.so /usr/libexec/httpd
$ sudo apxs -e -a -n php4 libexec/httpd/libphp4.so
$ echo 'echo "AddType application/x-httpd-php .php" >> \
/etc/httpd/httpd.conf' | sudo sh -s
$ sudo apachectl graceful
You will need to modify /etc/httpd/httpd.conf and change the DirectoryIndex line to also contain index.php, for example:
<IfModule mod_dir.c> DirectoryIndex index.html index.php </IfModule>
Updating PHP for Apache 2.x in Mac OS X
Alternatively, you can use Apache2 instead of Apache1 which OS X comes with. Server Logistics have created a very nice set of packages for Apache2 and PHP (compiled for Apache2). So if you're looking for the easier way to install PHP, and don't mind using Apache2, this is a better choice. You can get Apache2 from:
www.serverlogistics.com/apache2.php
You can get PHP compiled for Apache2 at:
www.serverlogistics.com/php4.php
Installation of both packages is extremely straight-forward and you should be up and running in a few minutes. This PHP package does have gettext support compiled in, along with many other modules.
Using Apache2 with Anthill works great; if at all possible, I advise using Apache2+PHP using Server Logistic's excellent packages.
Sendmail in OS X (I don't know about OS X Server) doesn't really work with PHP out of the box. By default, you may get deferred connections in your mail.log because it can't connect to the localhost to deliver mail. To do this, you will need to either install another MTA if you can't stand sendmail (like me), or else get sendmail to start on boot. You can get more info on sendmail on Mac OS X from:
http://www.macdevcenter.com/pub/a/mac/2002/06/07/sendmail_1015.html
This article will tell you what you need to do to start sendmail on boot in OS X and some of how to configure it to get it working properly.
To get MySQL installed, use Fink. Optionally, you can grab MySQL4 from Server Logistics as well:
http://www.serverlogistics.com/mysql.php
Everything else is identical to the Linux installation so follow the instructions.
Every effort has been made to allow Anthill to work with PHP's safe_mode enabled. For this to work, however, you must make a few additional changes. Firstly, the entire Anthill web tree should be owned by the user running the web server (ie. apache). You can accomplish this by doing:
# cd /path/to/anthill # chown -R apache.apache *
The permissions for the shadow, tmp, gpg, and attachments directories should still be 700, writable only by the user apache.
You will have to modify /etc/php.ini and set safe_mode_execdir to the location of where the diff utility is stored. For example:
safe_mode_execdir = "/usr/bin"
If this is too loose for you (a lot of stuff is in /usr/bin), you can always move the diff utility to a special directory that only contains the diff tool and set safe_mode_exec_dir to that special directory.
Finally, you should also be able to use Anthill with register_globals turned Off.
It is actually recommended that you operate with register_globals off and safe_mode on.
If you are upgrading from a previous version of Anthill, use the upgrade script in etc/. It will take the format of [old_ver]-[new_ver].sql (so to upgrade 0.1.4 to 0.1.5 the file would be 0.1.4-0.1.5.sql). To use it, simply execute:
# cd anthill/etc # mysql -u root -p anthill <[upgrade_file].sql
After this, copy all of the files over your existing files with the exception of anthill/html/include.php and anthill/include/config.inc.php. Compare your files to the new files to see if there are any changes to be made. Of course, replace "root" with the username you are using to access the Anthill database and "anthill" with the name of the database.
It is important to compare the supplied config.inc.php file to your existing one as with new features come new configurable options at times. For this reason, reading over the CHANGES file is a good idea before upgrading.
If you are upgrading from a really old version (ie. 0.1.5), you should run each upgrade file, one after the other. For instance, if you are running 0.1.5, you should run the 0.1.5-0.1.6.sql and 0.1.6-0.2.0pre1.sql, etc. files, one after the other.
Upgrading from Anthill 0.1.x to 0.2.x
If you are upgrading from Anthill version 0.1.x to version 0.2.x you must copy the upgradepw.php script in the etc/ directory to the html/ directory. This will send out emails to all of your users with new generated passwords. This is required due to 0.1.x using crypt()-based passwords and 0.2.x using md5-based passwords. Your users will be unable to login until you execute this file. You can do so by pointing your browser to:
http://yoursite.com/upgradepw.phpDelete this file after you have executed it. This file has NO access checks because if you upgrade Anthill while you are not logged in, you will be unable to execute the script without resetting the admin password manually. Because of this, anyone who can reach this file can re-generate and wipe out your user's old passwords, creating an annoying situation. It will not delete or otherwise harm your users, but they will need to login with the regenerated passwords and re-set them to their own (big PITA). So, for sanity's sake, remove upgradepw.php once you have executed it.
In 0.1.x, the file include/site.inc.php was used to store configuration information. This has now been changed, in 0.2.x do not touch the include/site.inc.php, but modify include/config.inc.php instead. include/config.inc.php stores all of the configuration information and should be used from this point forward.
Anthill has a new feature in 0.2.x that allows the system to email users who have open bug reports with a reminder to deal with the bug associated with them. This is done via the contrib/anthill-emailuserscron.php file. You will need to edit the script to point to your Anthill implementation's include.php file and you may also choose to tell it what statuses should be mailed (by default NEW and UNRESOLVED bugs are emailed). This should be installed in your crontab to automatically send out these emails at whatever interval you choose.
There are also other third-party contributions in the contrib/ directory. There are scripts that are either useful with little modification, or simple "proof of concept" type scripts that can be modified to work with your data in a specific way to extend the functionality of Anthill. Problems/suggestions on these scripts should be directed to their individual authors.
IMPORTANT NOTE: The order of some status types (like those listed in status_d, resolve_d, priority_d, etc.) are significant! If you change the order, Anthill will not work as it should. For instance, if you decide to change the DUPLICATE entry in resolve_d from id 3 to id 2, Anthill will break. The reason I chose not to hardcode the status codes into Anthill itself was so that it could easily be changed to suit your particular language (ie. change DUPLICATE to whatever the equivalent French word is if you run a french site). Please keep this in mind if you decide to make changes to the SQL data.
Known Bugs
For some reason, and I believe it is how cookies are managed, access Anthill via http://localhost or http://server, etc. (despite having Apache configured to handle this properly, and having Anthill configured the same) you will be unable to login. While the login looks like it works properly, when you are returned to the index page, Anthill will still show you as not being logged in. I'm quite certain this has to do with the (mis-)management of cookies, but don't know of a good way to work around it. You must access Anthill via something like http://myserver.mydomain.com in order for everything to work properly.
Using mod_gzip in apache with Anthill likely will not work too well. For some reason, admin.php doesn't POST properly while everything else seems to work. For now, if you encounter problems with admin.php and use mod_gzip, disable it.
Anthill is provided without any warranty of any sort. I don't warrant that it works or that it doesn't. I do provide commercial support for Anthill; email me to get my rates. I do not provide free support for Anthill outside of the mailing lists. I will try to help you figure out any problems you may have, but please don't be upset if I don't respond immediately. I have many other things to do than deal with Anthill support.
As a result, a few mailing lists have been created to provide some discussion, direction, and support on future Anthill versions. The lists include:
anthill-announce: announcements only (read-only, very low
traffic);
subscribe by emailing
anthill-announce-subscribe@vmlinuz.ca
anthill-workers: discussion of development versions of Anthill, new
features, code, etc.;
subscribe by emailing
anthill-workers-subscribe@vmlinuz.ca
anthill-users: support and discussion for Anthill installations,
configuration, themes, etc.;
subscribe by emailing
anthill-users-subscribe@vmlinuz.ca
The main Anthill homepage is http://anthill.vmlinuz.ca/
You can submit bugs at http://anthill.vmlinuz.ca/ anthill/
There is a demo site of the latest stable or unstable version of Anthill at http://anthill.vmlinuz.ca/demo/
Anthill is a Bugzilla-like clone written entirely in PHP. While not as comprehensive as Bugzilla, it is much easier to use, setup, and customize. One such customization is it's built-in comprehensive language support using PHP's gettext() function. To make Anthill more appealing to the masses, the more languages available, the better. Anthill is entirely open source and GPL, so your contributions will not be used to make a profit, but will be there to help others who are looking for quality software in a certain language. All language contributions would be extremely appreciated!
You can also help in other ways. Testing the beta, pre-release, and CVS releases helps track down bugs more quickly. Anthill 0.3 will be featuring quite a large rewrite in a number of core areas so that we can have real templating, database abstraction, and optimized code all over the place to make Anthill even faster. Getting involved in the development will help that goal come to fruition much quicker.
Donations of money are great. They help to encourage me to continue working on Anthill and they also allow me to purchase new books and various subjects that allow me to research new ways to enhance Anthill. And, if nothing else, they show your appreciation for all of the hard work I've put into Anthill. Use PayPal to send me some encouragement (there is a button on the Anthill homepage enabling you to do this).
$Id: README.html,v 1.2 2003/11/11 19:44:57 vdanen Exp $