CodeTrack: Bug Reporting and Tracking for the Rest of Us!
A pain-free solution for tracking and managing code defects using
a friendly web front end. Create, review and manage bug reports and
developer responses for multiple projects from a common interface.
Particularly suited for intranet and extranet environments, CodeTrack
includes built-in strong authentication, and allows custom access
control to individual projects.
If you've got a generic build of PHP and Apache, you can run CodeTrack.
No database or mail server is needed. No bizarro
make files! No lib-you've-never-heard-of. No Apache rebuilds
or funky Perl mods. Just a modest tool for medium and small development shops,
with an emphasis on open non-proprietary standards.
Bug data and developer notes are stored using simple XML text files, via the built-in XML support
in PHP4/5. The system runs equally well under Linux, BSD, or Windows, and it supports all
major browsers. And yes, of course, it's free.
CodeTrack is built for developers who, like us, despite having a soft spot
for Open software, find themselves with feet squarely in both the *nix
and Windows worlds. We all serve different masters and often wear many hats.
So, if the QA folks need a no-fuss, robust tracking system, your boss needs
the occasional Excel report, and you want built in scalability and data
future-proofing, then give CodeTrack a try.
- CodeTrack is fast: search thousands of bugs in seconds
- CodeTrack is svelte: A database of 4,000 bugs takes only 2MBs, rendered pages < 10K
- Trivial install -- Sets up in less than five minutes
- Track issues across multiple projects
- Full bug history and auditing by default
- Strong authentication out of the box
- Full support for older browsers (like Netscape 4.x)
- No database needed for the backend
- No mail server needed
- No need for obscure shared libraries to scatter across your system directories
- No Apache rebuild or new mods required
- Screen prints or other attachments can be included with bug reports
- Many built-in quick reports: Closed bugs on project Foo, Severity Level "Fatal" only, Submitted by Fred, etc.
- Interface is a thin-client model which works with all major browsers
- Restrict access according to user or role, by system or by project
- Pain-free maintenance: The entire application is a single PHP program
- Plain-vanilla install of Apache and PHP
- (Really, that's it)
CodeTrack is a standards-compliant, cross-platform software engineering tool. We are fanatical about
inter-operability, and subscribe to the "build it in right, the first time" school of thought. As
such, several major data formats are available out of the box, and you are guaranteed never to be held
hostage to some proprietary, vendor-specific information structure. Here are a few examples:
- All bug and user data are stored natively as self-describing XML
- Document Type Definitions are written in plain English and easily customized
- The user interface is pure-web; all HTML and CSS output is 100% W3C compliant
- Specifically built for multi-environment development: No browser-detect hacks!
- Export bug data into standard CSV, tab-separated, and even portable SQL script build files
- A one-click translator allows pointy-haired bosses
to view aggregate bug data directly in Excel!
- Raw XML and DTD data files can be viewed using any browser or downloaded directly
Why another bug tracking system? Aren't there already several mature
applications that serve the same purpose?
There are, indeed. Bugzilla, Gnats, and Jitterbug are examples of
several fine open source bug tracking systems, not to mention the plethora of commercial
products such as Census Bug Track, TrackWeb, and PCVS Tracker.
The problem with most of the existing systems is that the vast majority require
a dedicated database backend and full-time mail server (not to mention all the
maintenance that comes along with that). In addition, nearly all require significant
configuration and additions to the operating system. Case in point, take a look at the Bugzilla
instructions. This isn't meant as a slam, incidentally, just an illustration that setup is not
trivial; you really
better be prepared to devote a day (or two) to the cause,
and accept that there will be a significant (ongoing) amount of care and feeding for the supporting
infrastructure. If you are developing a 2 million line app like Apache or OpenSSL, and need
to catalog 30,000 bug reports for each branch of your codebase, then go for it --
Bugzilla will serve you well. But if you're among the mere mortals who need a little less,
then take a look at CodeTrack's installation
contrast, and decide what's best for your situation.
We would be remiss, by the way, not to mention yet another alternative. Over the past
few years several Application Service Provider (ASP) vendors have also sprouted up with
their version of Bug/Issue Tracking web-based systems. But frankly, the case for outsourcing
this sort of thing has never been very convincing for many of us. And with the recent fall of so
many promising dot coms, it seems a tough sell to buy into the give-us-all-your-data-and-trust-us
CodeTrack, on the other hand, requires nothing more than a plain vanilla build of
PHP-on-Apache. No special libraries or mystery shared object files are needed to fill up
your system directories. CodeTrack was designed to serve that niche somewhere
between a small MS Access database or even an overflowing bugs spreadsheet and
an industrial-strength solution like Bugzilla. Think of it as Bugzilla-Lite.
The closest open source alternative to CodeTrack is Jitterbug, used by the Samba
and OpenSSL projects. We appreciate Jitterbug's less-is-more philosophy
("no Java or gratuitous graphics")
, but like most of the available free
bug management systems, it must a.)
run as a CGI program and spawn a new
interpreter process for each request, and b.)
requires running Sendmail in
daemonized mode. Here's a table
comparing CodeTrack with several major free and commercial bug tracking applications.
Why aren't you using MySQL or PostgreSQL for the backend?
One word. Simplicity. For the vast majority of projects, the number
of bug reports would be very unlikely to ever exceed a few thousand over the
lifecycle of the application (in most cases, probably more likely a few hundred).
It seems to us that a full-blown relational DBMS for that level of data is a
For the record, I am a big Oracle fan, and actually began the
initial design of CodeTrack using 8i Server as a backend (using the excellent
OCI library that comes with PHP). But after finishing the data model, I realized
that I only needed three tables (two of which were unlikely to grow beyond
20 or 30 rows). Seemed a bit like killing a housefly with a surface-to-air
How many bugs can CodeTrack track? (If a woodchuck could chuck wood...)
For the best response, CodeTrack was designed to normally service approximately 2,00 bugs per
project, with a 10,000 bug per-project ceiling. As a practical matter, the upper bound is
really a function of how much RAM and CPU you're willing to give Apache for each thread (8MB is
the default, which translates in CodeTrack terms to roughly 14,000 bugs drop-dead maximum, at
least out of the box). You also have to ask how acceptable, say, a 2-3 second delay is to you, in
retrieving bug reports. Again, if you're Boeing and really need to catalog and manage hundreds of
thousands of bug reports for millions of lines of code, this system probably won't suit you.
That doesn't seem like a lot.
By way of comparison, we've done a little research on this topic. The SAMBA file server
project has closed roughly 21,000 bugs over it's lifetime, and the entire Red Hat Linux
distribution has closed about 56,000 since the company's inception.
So, are 10,000 enough? In the end, only you can answer that question, based on the demands of your situation.
Okay, but how is the performance of CodeTrack for real-world projects?
fast. Customized reports, using even complex queries, are nearly instantaneous
for projects with up to 1,500 bugs. <shameless_plug
> For what it's worth,
in collecting data for the question above this one, it took over 30 seconds to run a query
and get those numbers out of their respective bug tracking systems. That may not seem like a long time, but
when you're just staring at the screen waiting...
Why XML as the data format?
Once the decision was made that an entire database for three table just might be
, several standard formats were considered, including
simple DBF, tab-delimited, and XML. PHP's support for DBF files is limited, and the documentation
strongly recommends against write-heavy use.
I could have used a custom tab-delimited scheme, but XML is vastly more flexible. And, as one
pointy-hair that I work for once observed, "The nice thing about XML is it's extensible."
Seriously though, the case for XML is a no-brainer: self-describing structure, built-in inter-
operability with databases and active-content web servers, not to mention ease of editing
(consider, the pain to dynamically add or move a column in a large existing comma-separated
(CSV) flat file, compared to XML). Plus, it's extensible.
How big do the XML database files get? I heard XML is kind of bloated.
In our observations, the typical CodeTrack bug report takes about 550 bytes of
file space (not counting some minor overhead with the DTD header at the top of the
database). So, doing the math, expect to see 1.5 to 2 MBs per 4,000 bugs. Quite
respectable compared to any database like SQL Server or PostgreSQL, which would need
perhaps 100 MBs of file space just for the RDBMS and setup files. You be the judge.
Will CodeTrack work well with [fill-in-your-favorite-browser] ?
Yes! CodeTrack presents a sharp
interface at all major resolutions, and has been fully tested on these browsers:
- Microsoft Internet Explorer 4-6 (Windows)
- Netscape Navigator 4.5-4.79 (Windows, Linux: KDE & Gnome, Solaris)
- Netscape Navigator 6.2 (Windows, Linux: KDE & Gnome)
- FireFox/Mozilla 1, 1.5 (Window, Linux: KDE & Gnome, Mac OSX)
- Konquerer 2.0 (Linux: KDE)
- K-Meleon (Windows)
- Opera 5, 6.01, 7, 7.2, 8 (Windows, Linux: KDE, Gnome, Ximian, Mac OSX)
- OmniWeb (Mac OSX)
- IE 5.2 (Mac OSX)
Also, CodeTrack is very friendly to tele-commuters connecting over dial-up. All pages are
very lightweight (rendered size, including graphics, is between 2-10K total!).
And, all CodeTrack system pages meet these rigorous standards:
- XHTML: W3C v. 1.0 Strict
- CSS: W3C v. 1.0 and 2.0
- XML database and inline DTDs: W3C v. 1.0, Valid and well-formed
Will the CodeTrack app run under [fill-in-your-favorite-OS] ?
Most likely! We have either first-hand experience or reputable direct reports of the system
running under these operating systems and Apache/PHP engine combinations in production settings
(many other configurations are no doubt possible, but these have been verified):
Note: Although not CodeTrack specific, there are known issues running PHP with Apache 2.0, due to threading
problems in third party libraries, so tread carefully if using in a production environment.
- Apache 1.2.0 - 1.3.34 + PHP 4.0-4.4.2/5.0-5.1.2
- Red Hat Linux 6.2, 7.2, 8, 9, Fedora Core 1-3, AS/ES 2.1/3.0
- CentOS 3/4
- WhiteBox Linux 3.0/4
- Mandrake Linux 8.1
- NetBSD 1.5.2 - 1.6.2
- Windows 2000 SP2/3/4
- Windows XP SP1/2
- Mac OSX Jaguar/Tiger
on the Core PHP developer list for
more history. Also straight from the
(i.e., the install guide on php.net): "We do not recommend using a threaded
MPM in production with Apache2. Use the prefork MPM instead, or use Apache1."
If you have a success story you'd like to share, please mail us; we'd be delighted to hear from you.
Are any special XML libraries or RPMs required?
No. The default PHP build already includes the XML functions needed (note -
CodeTrack does not
require the experimental XDOM libraries; instead it depends
on the Expat routines). Unless you went out of your way to specifically exclude
the XML library during the modPHP make process, things should just "automagically" be
there. If you're completely paranoid, a quick little
can confirm whether Expat is in
place. Look for "XML Support" -- if it's listed as "Active" you're set. If it's not,
most likely you're running PHP version 3.x.
Is CodeTrack secure?
It depends. Every reasonable measure has been taken to sanitize form data
(especially screen print attachment uploads), but a formal security audit has not yet
been completed. CodeTrack is ideal for in-house (i.e., intranet) environments. If
you decide to run this on a public server, you are strongly
urged to run Apache
in SSL mode, and limit access to a known group of users via the built-in MD5
authentication mechanisms. Like any active-content web application, (e.g., ASP,
Cold Fusion, traditional CGI), there is always some degree of risk for denial of service
attacks by bombarding the web server repeatedly with resource-draining requests, mal-formed
page requests, embedded shell escape characters, and form POST buffer overflows, so
proceed with caution. Remember, most hacks are done by exploiting applications in very
non-intuitive ways. So, don't be surprised if you ignore these warnings, run CodeTrack
naked on a publicly exposed server, and one morning discover that, not only have you been
rootkit'ed, but also have the joy of explaining to the boss precisely why there are
2 gigs of fresh pornography in the attachments directory, and thousands of download
requests referred from warez.com in your access logs!
CodeTrack intentionally includes unforgiving authentication checks in
the first few lines of execution. Should credentials be missing or fail, a
redirection is forced to the login page. No GET-style requests are permitted either
for either login or posting a new or modified bug. But, we cannot emphasize enough,
if you disable authentication, or give out "one-size-fits-all" passwords to users,
and run CodeTrack in public web space, you are insane
The Man to monitor our every move.
Yes, and cattle disappearances are on the rise too. Seriously, though,
because HTTP is a stateless protocol, the options for managing active-content sessions
between pages are limited. Let's look at our options - traditional HTTP authentication
(i.e., Apache htaccess/PHP_AUTH_USER), ala Lotus Notes. The main problem with this
approach is that passwords are sent to the web server in plaintext for every
page request. If SSL is not used, a number of freely available sniffer tools would be
happy to collect your users' passwords via CONTENT headers passed prior to every page
request. Did we mention that every page request would transmit the plaintext password?
is used often and can be a workable solution in some applications. The major
drawback is that each page request requires the client-side agent
store and update all session variables, and either append it to every traditional
link(i.e., page?foo=bar&session_id=ABC), or in the case of form posts, add it
as an explicit or dynamic hidden variable to be sent as part of the submit.
While these issues are manageable, the biggest headache to the
variable-in-frame technique has to do with user behavior, specifically the back
and forward buttons. Once the entire frameset is part of the browser
history(i.e., not the currently displayed page), all bets are off with respect
to variable state. When the user navigates back, maybe frameset variables are
the way they were set when the frame first loaded, or maybe they are exactly as
they were on last viewing. It's completely browser-dependent. And, surprise,
surprise, the current crop of major browsers all behave completely differently. Anything
other than the most trivial dynamic applications are thus wed to vendor-specific hacks,
or have to take more draconian measures like disabling navigation buttons. The only
other option? Cookies. Full circle, huh?
But can't Apache or PHP automagically handle sessions and related authentication?
No such thing as a free lunch. Read the fine print, and you'll see that what's
actually being used are either cookies or on-the-fly URL translation. The only difference
is that the web server manages session information and page variables with ad hoc
One of CodeTrack's main design goals was simplicity. Forgetting for the moment the
known issues with proxy servers, stateful packet firewalls and "lost" URL sessions,
honestly, how many medium- and small-traffic folks would read too much further if the install
instructions began with, "First, grab the latest modRewrite from foo.org, then
re-compile Apache, then create htaccess files, then overhaul httpd.conf..." I
know I would have tuned out.
the traditional HTTP header method. Why?
At the risk of inciting religious wars, the answer is, there is no single
technique to set cookies server side which works cross-browser and cross-platform.
What's my evidence for such a bold claim? See the very interesting site
These guys have collected
the best empirical numbers on the topic that I've seen. They have tested 11 different
server-side techniques on over 10,000 unique hits (IPs), for visitors to a major public
(adult) web site, amassing 50MBs of test logs. The audience represents a mix of nearly
worked over 98% of the time, versus 60-80% for other methods. It also turns out that Netscape,
Opera, Mozilla, and IE all require slightly different header strings on server-set cookies,
but, oddly enough, all apparently do
platform or browser (so much for RFC guideline standards...)
And, by the way, this is true even within
same-vendor products (see the newsgroups
about the cornucopia of methods used by the many IE flavors on different operating
systems, especially XP and the Mac, not to mention IE 4 versus 5.5 versus 6...).
For real pleasure reading, take a look at the user-annotated PHP
except maybe for some net-friendly form validation, to save unnecessary trips to the server,
consistently) on every major contemporary browser. So, there we are...
The latest code is always at our SourceForge
A 5 minute guide to installing CodeTrack v.0.99
(FIRST TIME only; existing users, see below)
In a nutshell: copy files to Apache-owned space, set permissions, specify a return e-mail
address, and go.
1. Create a directory in the htdtdocs root space, for example:
2. Unzip and untar the codetrack files to this directory:
tar -xzvf codetrack.tar.gz /home/httpd/htdocs/codetrack
(Windows users can use Winzip, either on the *.gz or *.zip release)
3. Set the permissions for the directory so that it is readable and writable by
the apache owner:
chown -R nobody.nobody /home/httpd/htdocs/codetrack
chmod -R 600 ` find /home/httpd/htdocs/codetrack -type f `
chmod -R 700 ` find /home/httpd/htdocs/codetrack -type d `
(Windows users can do the same thing through the GUI, just make sure the XML
files and the attachments directory are writeable. You may have to set the
ownership to Administrator. Thanks, Microsoft!)
4. To use e-mail notification, edit codetrack.php and set a real return address for codetrack:
change: DEFINE ("CODETRACK_RETURN_ADDRESS", "firstname.lastname@example.org" );
to: DEFINE ("CODETRACK_RETURN_ADDRESS", "CodeTrackAdmin@myCompany.com" );
or: DEFINE ("CODETRACK_RETURN_ADDRESS", "DoNotReply@foo.org" );
To *DISABLE* e-mail in CodeTrack, edit codetrack.php, and set
CODETRACK_ENABLE_EMAIL to FALSE
SPECIAL NOTE TO PHP-ON-WINDOWS USERS ONLY:
If you've never used the PHP mail functions on your web server before, edit
the php.ini file and set the options below. Note that you might be able
to use your ISP's SMTP server if you don't have one. The box running PHP
does NOT have to be running a mail server (i.e. Exchange) for this to work.
SMTP = localhost ;for win32 only
sendmail_from = email@example.com ;for win32 only
SMTP = mailserver.foo.org ;for win32 only
sendmail_from = firstname.lastname@example.org ;for win32 only
You will need to stop and restart Apache for the changes to take effect
5. Fire up a browser and navigate to server-name/codetrack/
6. Initially, login as the System Admin:
project: Test Project
After logging in, change your password, set up a few users and your initial
"real" project, and go!
If you get stuck, please re-read this document, and check
SourceForge bug report, but feel free to write us at: email@example.com
A 5 minute guide to UPGRADING to CodeTrack v.0.99.3
(For existing v.0.99.2 users ONLY)
In a nutshell, four basic steps: run a backup from within CodeTrack,
directory, copy your existing xml data files and config.inc.php configuration
somewhere safe, Untar/zip the v.0.99.3 files to a temp directory (NOT your real
htdocs location!) and then replace your exising codetrack.php and config.inc.php
with the the new codetrack.php and config.inc.php files from the v.0.99.3
release, but *only* these two files. Set permissions, and you're ready to go.
*** CRITICAL NOTE ***
Do NOT unzip the new files to your working codetrack
directory, or you will overwrite your existing data with
empty bugs, users, and projects files!!!
1. Run a backup of your existing xml files:
In Codetrack: Admin/Backup XML Databases/Backup Now
2. Copy your current xml files and configuration file somewhere safe:
cp /home/httpd/htdocs/codetrack/backups/*xml* ~/somewhereSafe/
cp /home/httpd/htdocs/codetrack/config.inc.php ~/somewhereSafe/
(Windows users: the key here is that these are your *current* files, not the ones
3. Untar/unzip the updated codetrack.php and config.inc.php files to your web directory:
tar -xzvf codetrack.tar.gz ~/tempDir (Windows users just unzip to a temp directory)
cp ~/tempDir/co*php /home/httpd/htdocs/codetrack
4. Set the permissions for the directory so that the two new files are readable writable by
the apache owner:
chown -R nobody.nobody /home/httpd/htdocs/codetrack/co*php
chmod -R 600 /home/httpd/htdocs/codetrack/co*php
You might want to diff the two config.inc.php files if you've made any tweaks,
otherwise, the defaults should Just Work(tm).
If you get an error when trying to start CodeTrack, the first thing to verify is a simple sanity check
that you can view a known document with your browser on the same server, i.e.,
Next, verify that PHP is behaving
in the directory where CodeTrack lives
creating a dummy test file like this:
<? phpinfo(); ?>
Save it as something like "foo.php
" in the CodeTrack directory,
see if you can view that (should dump lots of system and diagnostic information). If this doesn't work,
then you've got bigger problems. Check your Apache setup, and if necessary run the installer again and
pay attention to the questions is asks. 99% of problems with starting CodeTrack are caused
by improper Apache setup, or erroneous permissions or file ownership. You can also look
at TROUBLESHOOTING.txt for more troubleshooting advice.
The Top 5 CodeTrack Support problems (and solutions):
1. If you are seeing a horrible looking white login screen with huge default Times Roman fonts,
your permissions on the style (and likely all other) subdirectories is wrong. See INSTALL.txt,
but the short version is that the Apache owner needs read+write+execute on several directories,
and read+execute on ALL directories under codetrack.
2. If you are having mail problems, review INSTALL.txt and TROUBLESHOOTING.txt. Also take a look at
and try the first or second example as a simple sanity check that ANY outbound mail will work with your
PHP webserver. If the one-liner at PHP.net isn't working, there is no way CodeTrack will work.
3. If you find a really broken screen that includes PHP error messages about "Headers already sent" --
the real problem is in the source code line number. Typically this is seen when trying to send mail
on a Linux box where no outbound mail agent exists, or a broken Windows SMTP setting in php.ini.
4. If you are using Windows and trying to run CodeTrack on IIS, as laid out in the
Requirements section above, CodeTrack has two simple needs: Apache and PHP.
Because it relies on Apache-specific server variables, it WILL NOT work with IIS.
If you have a desperate need to run CodeTrack as an IIS CGI, by all means,
Use the Source and submit a patch!
5. If you are seeing strange problems with export downloads, verify that any mods you made to either codetrack.php or
config.inc.php did not accidently add new lines above or to the right of the opening and closing php tags (yes,
literally a few extra spaces at the end of the file will cause IE to "outsmart" the proper MIME format, and
try to parse a file as raw HTML.
If you have questions or comments, e-mail firstname.lastname@example.org
And, please God, provide these basic data: OS version, Apache version, PHP version,
browser -- example: MacOSX 10.4, Apache 1.34, PHP 4.36, Opera 8.0
(not trying to be a pain -- we *really* want to help, but we're pretty blind without this information).
Also, please be sure to include the word "CodeTrack" in your subject line, so
you're not filtered out as spam!
CodeTrack is released under the
by Kenneth White
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.