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.3 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 and PostgreSQL are fully supported. Anthill uses PEAR so other database support can be added in the future.
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 rename html/include-dist.php to html/include.php and edit the file. 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 rename config.inc-dist.php to config.inc.php and edit the file. 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'] = "/var/www/anthill/html"; $_CONF['incdir'] = "/var/www/anthill/include"; $_CONF['webroot'] = "http://www.yoursite.com"; $_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"; $_CONF['peardir'] = $_CONF['incdir'] . "/pear/"; $_CONF['includes'] = $_CONF['incdir'] . ":" . $_CONF['peardir'];
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 "difftool" option 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.
As of Anthill 0.3.0, PEAR is being used to handle the database abstraction layer. Because of this, both the location of PEAR itself and a re-defined include needs to be noted. If you wish to use the version of PEAR on the system rather than that which comes with Anthill, set $_CONF['peardir'] to a null string (ie. ""). If you have it in a location other than the default (include/pear), be sure to append a trailing slash to the path. Likewise, in order to properly use PEAR, the path needs to be included in PHP's include() path. The "includes" option appends extra directories to include; by default both the includes/ directory and includes/pear are appended to the path. If you use the system PEAR, you should edit this option to remove the colon and "peardir" path, as the system PEAR should already be in the site-wide include path.
$_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. If your Anthill install is something like http://anthill.mysite.com/ or http://mysite.com/ then leave it at the default '/'. If it is in something like http://mysite.com/anthill/ then it should be set to '/anthill'. Essentially, this needs to point to the path that Anthill is available via the web interface. If Anthill is available via more than one URL (ie. it is available via http://mysite.com/anthill/ and http://anthill.mysite.com/) you can try to set it to "" (or blank) and it might work (entirely untested). Otherwise you may have to settle on one URL or the other as opposed to both.
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 and PostgreSQL are supported, so "db_type" must be set to "mysql" or "pgsql". 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. As well, if you are using sockets to connect to your database (ie. using postgresql and not having it listen to TCP), you can add the protocol to use to the "db_host" option (ie. "unix+localhost" to use unix sockets and connect to localhost). The default is to use TCP (ie. "tcp+localhost", but putting the protocol in there is not required). For more information on this, or if you need other options, you can specify the DSN in site.inc.php manually (refer to the PEAR manual for more information on how to construct a DSN). For most people, this is sufficient and being able to use 'protocol+hostspec' or just 'hostspec' (for TCP connections) in "db_host" should be enough.
Once you have completed this and defined the database name for Anthill, you need to create the database structure.
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'].
Create the database you plan to use (defined as $_CONF['db_name'] in config.inc.php) by issuing:
# createdb anthill
if "anthill" is the name of the database you chose. Be sure to use createdb as an appropriate user; the configuration of PostgreSQL is beyond the scope of this documentation. You may also have to create the database user as a privileged user. Ie. if you webserver is running as user apache, you may wish to use user apache (this again depends on your authentication scheme and PostgreSQL configuration):
# createuser -D -A -P -e apache
This will create the apache user with no special privileges (unable to create new users or databases).
You have to import the database scheme from etc/pgsql.dump. This is largely dependant upon how, again, PostgreSQL is configured, but you may end up using something similar to:
# cd /var/www/anthill/etc
# psql anthill < pgsql.dump
Finally you have to grant permissions to the tables (not being a PostgreSQL expert by any means, there may be easier ways to do this:
# psql anthill
sql > GRANT ALL ON config,users,status_d,severity_d,priority_d,resolve_d,sessions,\
products,components,versions,bugs,bugdesc,bugactivity,attachidx,users_seq,\
bugs_seq,bugdesc_seq,products_seq,versions_seq,components_seq,bugactivity_seq TO apache;
This also depends on how PostgreSQL is configured and how you want to restrict access to the database. Anthill needs to be able to create new sequences and also has to be able to fully write to nearly all of the tables (other than status_d, severity_d, priority_d, and resolve_d). You should really have some familiarity with PostgreSQL and have it properly configured before attempting to use Anthill with it. For those unfamiliar with database types, I recommend using MySQL since it's a lot easier to configure and use for inexperienced users.
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.
As well, a default .htaccess file exists in the attachments directory. In future versions, the attachments directory will likely move to being outside of the webtree. The .htaccess file prevents anyone from viewing these files without going through the showattachment wrapper (for your own safety).
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.3+ 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.
Now that PEAR is being used, you need to add the PEAR directory to your safe_mode_includepath like this:
safe_mode_include_dir = "/Library/PHP4/lib/php"
This allows you to execute scripts in /Library/PHP4/lib/php without UID/GID checks, which is important if the DB.php file is not owned by the user running the webserver. This is only required if you are using a site-wide PEAR; if you use the bundled PEAR, you shouldn't have to modify anything here.
It is actually recommended that you operate with register_globals off and safe_mode on.
As of Anthill 0.3.0, database changes are handled using the upgrade.php script in the webroot. The config.inc.php and include.php files are also bundled as "-dist" files so you can copy a new Anthill over the old one without worry about anything being overwritten unless you make custom changes to the code.
BEFORE DOING ANY UPGRADE YOU SHOULD ALWAYS BACKUP YOUR DATABASE!
Once you have copied in the new files, you should go to http://www.yourdomain.com/upgrade.php and follow the instructions (ie. select the version you are upgrading from and the version you are upgrading to. The upgrade script shouldn't break anything, but please make a backup first, just to be safe. Refer to the documentation of your database type for info on how to dump a database and it's contents. Better yet, setup a cronjob and do this regularly.
Once the upgrade has been completed, delete the upgrade.php file from the webroot. If you do not, you will see a nice warning on every page you visit (and your users will too). Removing the upgrade.php file is for your safety (thus the warning).
It is important to compare the supplied config.inc-dist.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.
The old upgrade scripts are no longer bundled with Anthill and the upgrade script only handles upgrades from 0.2.0 and higher. If you are using a really old Anthill (0.1.x), you should download 0.2.6 and upgrade to it (or 0.2.0 if you like) before attempting to upgrade to 0.3.0. No effort has been made to make it possible to upgrade from 0.1.x to 0.3.x.
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.7 2004/02/09 07:35:38 vdanen Exp $