Basic installation and setup of Issue-Tracker should be relatively simple for most people. First thing you will need of course is the latest version of Issue-Tracker which can be found at http://sourceforge.net/projects/issue-tracker/. For those of you running an rpm-based Linux system, installation of the files should be completely painless. Simply download the Issue-Tracker rpm and run the command:
rpm -ivh issue-tracker-<version>.noarch.rpm
and all files will be installed to your system, in the /var/www/html directory. For everyone else you will need to download the tar-ball (.tar.gz) or zip, uncompress the file and then place the files in your web server's document root directory.
This location depends on what OS you are using and what web server you are running. For most Linux distributions running Apache, this directory will be /var/www/html. Once the files are installed it is time to configure Issue-Tracker for your setup. A little further on I will explain what you need to do if you do not want all of your Issue-Tracker files to be inside your document root, but for now we will assume that you have left everything in one directory. Included with Issue-Tracker is a generic configuration file inside the conf directory named config.php-default. You will need to rename/copy this file to config.php so that Issue-Tracker will find it. Once you have renamed the file you will need to use a text editor to edit the file and include the values for your setup.
$db = array( "type" => "", "host" => "", "port" => "", "name" => "", "user" => "", "pass" => "" );
This is the information that Issue-Tracker will use to connect to your database, so if this is not setup correctly Issue-Tracker will not work. This array should be pretty easy to understand but I'll run through what each value is.
If you are the system administrator you might want to look at the documentation for your database server.
A generic example may be:
$db = array( "type" => "mysql", "host" => "localhost", "port" => "3306", "name" => "issuetracker", "user" => "it", "pass" => "makesomethingup" );
Ok, this covers what really needs to be set for normal functionality of Issue-Tracker.
Ok, that should take care of the main configuration file. You may have noticed that at the bottom of the config.php there is an include call to the second file in the configuration directory, const.php. The const.php configuration file should not be edited unless you absolutely know what your doing. This file allows you to move certain directories to other locations outside of the main Issue-Tracker directory and is also where the system constants for things like status types and severities are set. There is one setting in this file though that you may need to change. By default the directory where Issue-Tracker will keep uploaded files (_FILES_) is set to /var/files. Now if this directory is not available to you, or you are using a Windows machine then you will need to change this. This directory needs to be write-able by your web server but for security reasons should not be directly web accessible.
$db = array( "type" => "mysql", "host" => "localhost", "port" => "3306", "name" => "issuetracker", "user" => "it", "pass" => "makesomethingup" );You will need to login as root and allow this user (it) to access the database (issuetracker). Easiest is with mysql command:
% mysql -u root -p Enter password: <root password> Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 20 to server version: 4.1.3-beta-log Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> grant all on issuetracker.* to 'it'@'localhost' identified by 'makesomethingup'; Query OK, 0 rows affected (0.04 sec) mysql> quitHEADS UP: If you're running any of the Fedora releases, you'll want to see the troubleshooting section for the gotchas of installing a newer version of MySQL without also updating Apache (httpd) and mod_php. Method 2 A worked for me:
mysql> SET PASSWORD FOR
-> 'it'@'localhost' = OLD_PASSWORD('makesomethingup');
Now that your configuration files are setup correctly, or at least should be, we will move on to the database setup. If you haven't done so already you will need to create your database. [If you're very new to MySQL, before continuing, please try running the little scrip in docs/ called test.php. It will verify that PHP can talk to your mysql server, on which all the stuff below depends!] If you are using a MySQL database you will want to run the command:
mysqladmin -u <username> -p create <database name>
and if you are using a PostgreSQL database the command is:
createdb -U <username> <database name>
If you run into an error when creating the database please see the documentation for your database server. Once the database is created we need to import the schema and default data. The files that you will need to import are located in the setup directory that is included with Issue-Tracker. You should have 4 files, schema.pgsql, schema.mysql, data.sql, and indexes.sql. The filenames should give you a pretty good idea of what each one is for (and if not, see the contents of the script 'create_db.sh'). The first one we will need to import is the schema. The command to do this on MySQL would be:
mysql -u <username> <database name> < schema.mysql
and on PostgreSQL:
psql -U <username> <database name> < schema.pgsql
If you get any errors importing the schema you can post to the project forums at http://sourceforge.net/projects/issuetracker/ and we will be happy to help you figure out why you are getting the errors. Once the schema is imported you will also want to import data.sql and indexes.sql using the same command but with the correct filenames. If all 3 files for your database import without any errors then your database should now be setup correctly for users to login, but first we need to make sure permissions for a couple directories are set correctly.
If you installed Issue-Tracker from an rpm then you should not need to worry about this section unless you run across any problems. There are a few directories that must be writeable by your web server for Issue-Tracker to function properly. These directories are cache, CSS, download, logs, sessions, and themes. The commands to do this in Linux is:
chown -R <username> cache
chown <username> css download logs sessions
themes
where username would be the web server user, normally either apache or nobody. Unfortunately I do not run Windows web servers so if you are having trouble with permissions to these directories please check Microsoft's site (http://www.microsoft.com/) for help on setting the permissions correctly. Now if you will also be using the graphing support for the reporting module you will also want to make the images directory writeable using the same command as above.
Once all of the above is complete you should be able to point your browser to the URL you specified for the base URL and you should get a login screen that looks something like this:
If you do not see the login screen then you might want to check your logs directory and see if you have any error messages. If you get the login screen then attempt to login with the default administrator:
Username: admin
Password: demo
There is also a employee account setup with the following information:
Username: demo
Password: demo
If you login successfully then you should be all set. I would recommend that the first thing you do is change the password on the admin account. You might also want to visit the administration section of Issue-Tracker and update the Message of the Day for your setup. If at any point during the installation and setup you encounter any errors and need help just head over to the project forums and we would be happy to help.
Access to the users module of Issue-Tracker is limited to users within the employees group, or administrators. All other users the option for this module should not even be visible. To access the user management module you will need to click the administration button which, in the default theme, is located in the upper right hand corner of the page. If you do not see the button there, then the user you are currently logged in as does not have access to any administrative tasks. For now we will assume that the user you are logged in as has administrative privileges. Once you have clicked on the administration button you should see a panel with the administrative options available to you. For now the only one we need worry about is the 'User Management' button, which in most cases should be the first option. To enter the main user management page simply click on the button and it will take you there. You should see a page that looks something like this:
This is a listing of the users currently in the system. The default list displays all users with usernames beginning with the letter "A". To see all user's within the system click the "All" link under the titlebar. The list should be pretty easy to understand, you have username, last name, first name, email address, and the user's current active status. If the user's account is currently active you should see a green check mark, and if their account has been deactivated then you should see a red X. Toggling a user's active status can be done easily through this listing by simply clicking the icon.
Towards the top of this page you should also have a section to search the listing. As of v4.0 the fields that you can search on are username, first name, last name, and email address. To search for any user(s) just enter your criteria and click the search button. SQL wildcards are also accepted in the search. For example say you wanted to find all users who have an "a" in their username, no matter where it is. You would check the username checkbox and enter "%a%" as your search criteria. Simple enough right?
To create a new user, click on the "Create Users" link at the top of the user list. This will take you to a page that looks something like this:
This page contains ten (10) rows of fields, allowing you to create up to 10 users at one time. The fields here should be pretty easy to understand but I'll go over them just in case.
You may have noticed that this form does not include a place to enter a password for the user(s). This is because a randomly generated password is sent to the user(s) when they receive their notification of account creation. So make sure that the email address entered for the user is correct, otherwise they will not receive their password and will have no way to login. Also, you are not required to fill in all 10 rows, a row will be skip automatically if data is not found in the username field.
Once you have filled in the information for the user(s) you want, just click the "Create Users" button and the user(s) should be created. If there are any errors the page will refresh and display the errors towards the top of the page.
Modifying a user is just as easy as creating a new one. First of course you must select the user you want to modify through the user listing page discussed earlier. Once you select the user, by clicking on their username, you should be presented with a page that looks something like this:
Most of the things here are the same as the fields from the new user page so I will only cover the things that did not show up there. First we have the "Permissions" select box. This box will contain any permissions in the system that have been set as a "User Permission". I will cover user and group permissions later in the Permissions section. Selecting any items from this box will give that permission to the user, and of course deselecting any items from the box will remove that permission from the user. Below that you should have two more select boxes side by side.
The box on the left contains any groups in the system which you are allowed to add new members to. And the box on the right contains any groups that the user is in that you have the right to remove members from. As you may have guessed, selecting groups from these boxes will add or remove the user from those groups. And last but certainly not least is the Active checkbox. If this box is checked then the user's account is active and they are able to login and work with the system. If this box is not checked the user is not allowed to login at all. Well that should pretty much cover the basics of user management.
Access to the group management module is limited to the same users as the user management module, employees and administrators, and is accessed in the same way. First click the administration button in the top right corner and then click Group Management. You should be present with a listing similar to that of the user list, and should look something like this:
The group listing should be very easy to understand so we'll move on to creating a new group.
To create a new group click the "Create Group" link at the top of the group listing. You will be taken to the group creation form which should look something like this:
I'll go over each of the fields here and explain what they are used for. Very few of these fields are actually required, and most people have no need for some of them but they are there for informational purposes.
Once you have filled out the information for the group just click the "Create Group" button and the group should be created. If there are any problems the page should refresh with error(s) at the top of the page letting you know what's wrong. If all went ok you will be sent to the next step of group creation. Each group has their own set of statuses, categories, and products which they can select to use from the master list of each. None of these are automatically propagated to your new group, so it is up to you to select which ones your group will use. You should be presented with three pages, one for statuses, one for categories, and one for products, possibly not in that order. Each one should look something like this:
Simply select the ones that you want to add to your group and click the update button. Once you are done adding your statuses, categories, and products, you should be presented with the group summary for your new group which should look something like this:
To get to a group's summary page simply click on its name in the group listing. The summary page contains a non-editable view of the group's current information, including a listing of all the group members, along with system administrators and group administrators highlighted. At the top of the summary page you should see a row of links which will take you to the different sections of the group management module. If you do not see these links then your user does not have the correct permissions to modify the group you are currently looking at, and you will need to contact one of the group administrators to get the correct permissions. For now we will assume that you have the correct permissions, and we'll move on to general group information.
To edit the general group information click the link titled "Edit Information". This should present you with a page that looks similar to the form you saw when creating a new group, with the addition of the "Status Reports" and "Active" checkboxes. Since these are the only difference between this form and the group creation form, these are the only two I will cover here. Checking the Status Reports checkbox will enable Status Reports for this group. This allows technicians to enter periodic reports to let management know what's going on with the group, along with a standing indicator to show how things are going. As with users, the active checkbox is what determines whether the group is active or not. To modify any of this information simply edit the fields you want to update and then click the update button. To get back to the group summary page you can click the "Back to Group Information" link at the top.
To add or remove users from your group, you will need to click the link titled ironically enough "Add/Remove Users". This will take you to a page that looks similar to the one you were presented with for statuses, categories, and products during group creation. On the left is a list of users that can be added to this group, selecting any users from this list will add them to the group when the form is submitted. On the right is a list of users that already belong to the group, and selecting anyone from this list will remove them from the group when the form is submitted. Pretty simple don't you think. To get back to the group summary page you can click the "Back to Group Information" link at the top.
Sub groups are a new feature in v4.0 and can be very confusing if you don't layout your group structure first. Sub groups allow you to create groups within groups. Think of each sub-group as a separate department of the same company. The sub-groups page should look something like this:
There are three sections to this page, the first being the propagation of data from the group you are currently modifying. This section determines what data will propagate from the parent group down to the children (sub groups). To change one of the settings simply click the icon. If your group has any children then the next section will contain the propagation settings for each one of the child groups, and the option to disown the child. Each one of these settings determines whether or not that type of data propagates from the child up to the parent group. As with the parent, to change one of these settings just click the icon. The last section of this page contains a select box with possible children for this group. These are groups which you are allowed to add as children of this group. To add a child just select it in the box and click the add button. The group should then display within the children section of the page. If the group you are currently modifying has a parent group you will also see a non-editable section for the parent group, letting you know what data does and does not propagate down to this group.
Managing group permissions has been simplified greatly in v4.0, and with simple comes limits. Group administrators no longer have to manage huge lists of permissions for the members of their groups, but this also means that they can no longer give or take away a single permission from a user. Instead we now have permission sets, or roles. Each permission set is a grouping of permissions which can then be assigned to a user. Issue-Tracker v4.0 has five default permission sets which are covered later in the Permissions section of this guide. To get to the permissions section of a group click the link titled "Permissions". You should see a page that looks something like this:
There are two sections to this page, the member permissions, and the overall group permissions. We'll start with the member permission sets. Each member of the group should be listed here along with their current permission set. If the user has not yet been assigned a permission set then their drop down should say "Read Access". This means that the user can not actually create or update issues within the group. To update a user's permission set simply choose one of the sets from the drop down and click the update button. At any time you can remove the user's permissions by setting this back to "Read Access".
Below the member's permission settings you should see the overall group permissions. By defaultIssue-Tracker does not have any overall group permissions. This is here for module developers who may want to use such functionality. What an overall group permission will do is grant all user's in the group the specific permission by simply enabling it here, and of course you could also remove a permission from all group members by deselecting it.
Managing the statuses, categories, and products of a group is very easy. Each one of these has their own section but are identical to the forms you were presented with at the time of group creation. Since they are identical, if you would like an explanation of these forms please see the section on Creating a Group.
Each group has two separate notifications lists, one for email notifications and one for sms notifications. Issue-Tracker's support for sms messaging is strictly through email based services, so technically you could use the sms field as just a secondary email field for your users. To modify the notification lists of a group you click on the link titled "Notifications". The page should look something like this:
On the left is two boxes for email notifications, one to add members of the group to the default list, and another to remove members that are already on the default list. On the right is two boxes for sms notifications, same as with emails, one to add members, and one to remove them. Users will still receive notifications for certain reason even if they are not on the default notification lists, such as if they opened or are assigned to an issue, or if they are selected in the notifications list for an update. Adding a user to one of these lists simply means that they will receive a notification for any action taken within the group, including issue creation, issue updates, etc.
Each group can have their own set of escalation points. These are groups that issues from the current group can be escalated into, which basically just includes that group as part of the issue. Members of the escalation group can then view the issue as if it were in their group, including with the permissions that they have in the escalation group. If a user belongs to multiple groups that are involved in the same issue they will be presented with a select box to choose which group they will be viewing the issue as. This is done for a couple of reasons but mainly for correct permission checks and also private events. By default all events posted from a group which is not the original group of the issue will automatically be forced private.
The form for adding and removing escalation points is essentially the same as that of adding and removing users. You have one box for adding new escalations points, and a second box for removing escalation points. Simple enough.
The permissions system for Issue-Tracker V4.0 is a complete rewrite from how things worked in V3. Permissions can now be grouped into definable permission sets which make managing user permissions within groups much easier for group administrators. You can also define separate user and group permissions. User permissions will grant a permission just to that user, group permissions will grant a permission to all members of the given group. All additions and modifications of permissions are done through the permission section of the administration module, which can be accessed by clicking on the administration button in the top right corner and then going to "Permissions Management". You should then be presented with a page that looks something like this:
This is a list of all permissions currently present in the system along with whether or not they can be set as user or group permissions. You may have noticed that this listing does not allow you to edit or remove the stock Issue-Tracker permissions. This is because these permissions are set as "System" permissions, which means that they are required for Issue-Tracker to function properly. Removal or modification of one of these permissions could cause Issue-Tracker to show odd behavior so these actions are not allowed. At the top of the listing you should have two links, one to create a new permission and another to view the currently defined permission sets.
To create a new permission click on the link titled "New Permission". This will take you to a page that looks something like this:
This form should be pretty easy to understand but as usual I'll go over what each item is for. The text field is of course the name of your permission. This is what will be used in permission checks to determine if a user has the permission. Make sure this matches whatever the permission checks in your code will be looking for. Next is the group permission checkbox. Checking this box will allow the permission to be assigned to a group, which gives the permission to all members of the group. And last is the user permission checkbox. Checking this box will allow the permission to be assigned directly to a user instead of through a permission set. This is used for permissions such as "status_manager". To create the permission simply click the create button and it should be created, if there are any problems the page will refresh with an error letting you know what's wrong.
To modify a permission simply click the icon located in the edit column of the permission list. As stated earlier, system permissions can not be edited or removed. Once you click on the icon you will be presented with a form identical to the one you saw when creating the permission. Simply modify the settings you want changed and click the update button.
To remove a permission you would click on the icon located in the delete column of the permission list. This will take you to a page asking you to confirm or cancel the action. If you confirm the action then the permission will be removed from the system and you will be taken back to the permission list. If you cancel the action then you will just be taken back to the permission list.
As mentioned earlier, as of Issue-Tracker v4.0 you are now able to create groups of permissions called Permission Sets, or Roles. These permission sets allow group administrators to quickly and easily setup the permissions for the users within their groups without having to manage huge lists of permissions. Issue-Tracker Ver4.0 has five default permission sets:
To view the current permission sets you can either click on the Permission Sets link under the administration panel, or click on the link located at the top of the permission list. You should be taken to a page that looks something like this:
This is a listing of all the currently defined permission sets including which permissions are active and which are not. Just as with permissions, the stock permission sets can not be edited or removed. Underneath the name of each permission set should be a short description letting you know what the permission set is used for. To the right of the description is a list of permissions and their current status for that permission set. A green check means that that permission is active in that permission set, and a red X means that the permission is not active.
To create a new permission set, click the link at the top of the listing title "New Permission Set". You should then be presented with a page that looks something like this:
Here is an explanation of each field:
Once you have filled in the information for your permission set and chosen the permissions you want it to have then simply click the create button and the permission set should be created. If there were any problems while attempting to create the permission set, then the page will be refreshed along with an error letting you know what went wrong.
Looking back at the listing for permission sets, if you have any permission sets which are not stock system permission sets, then they should have two links above the list of permissions. There should be one link for modifying the permission set, and another for removing it from the system. To modify a permission set simply click the link titled "Edit Set" and you will be taken to a form that looks identical to the one you would see when you create a permission set. Modify the information how you would like it, and click the update button to update the permission set with the new information.
To remove a permission set you would click the link titled "Delete Set". You will be presented with a page to confirm or cancel the action. If you choose to confirm, then the permission set will be removed from the system and you will be sent back to the permission set listing. If you cancel then you will just be sent back to the permission set listing. Well that covers the basics of managing permissions and permission sets, now lets move on to Statuses, Categories, and Products
Once you have entered one of the sections you should be presented with a listing that looks similar to this:
Of course in the category and product listings you will not have a "Type" column, but other than that they should be the same. From here on I will refer to statuses, categories, and products simply as items. At the top of the listing should be a link to return to the administration panel and another one to create a new item. Each item in the listing should have two icons to the far right, one to modify the item and a second to remove it.
To create a new item you click the link at the top and should be presented with a form that contains a text field and in the case of statuses a drop down to select the status type. Simply fill in the text field and click the create button to create your new item. If there is a problem creating the new item then the page will refresh along with an error letting you know what went wrong.
To modify one of the existing items simply click the icon to the right that is in the edit column and you should be presented with the same form you saw at item creation. Modify the data for the item and click the update button and then item will be updated in the database. If there is a problem updating the item then the page will refresh along with an error letting you know what went wrong.
To remove an item, click the icon located in the delete column of the listing, and you should be presented with a page to confirm or cancel the action. If you confirm the action then the item will be removed and you will be taken back to the listing. If you cancel then you will just be taken back to the listing.
Ok, now that I have you confused, let me explain what status types are. Each status must have a status type assigned to it. This status type lets the system know what the status is used for, functionality wise. The status type is then used later to determine which statuses should be used in certain checks against issues like inside the is_closed() function. Any status with a status type of Closed will be used within that function to determine if the issue is closed or not. Here is a quick explanation of the available status types:
That should cover these three things. If I've confused you, or you need more information please visit the project forums at http://sourceforge.net/projects/issue-tracker/. Now lets move on to debugging.
Issue-Tracker v4.0 includes a couple of tools which can be handy for simple debugging of problems that users might encounter with the system. These tools include the ability to switch users, built-in debugger, and an interface to directly query the database from the web interface. As stated these tools are meant for simple debugging and are definitely not a replacement for an actual code debugger.
The Switch User action of the administration module provides a very easy way to determine whether a problem that a user reports is something that is happening on the server or something that is caused by the client. To switch users, enter the administration panel, and then click on the "Switch Users" button. You will be taken to a simple form which includes a drop down list of every user in the system. Once you select a user click the "Switch Users" button and you will be logged in as that user, including having the exact same permissions and groups as the user. You can then navigate through the interface to try and replicate a problem that a user has reported. Once you want to switch back to your normal user, simply click the link located on the main navigation menu titled "Switch Back".
Well there may not be much to the included debugging tools of Issue-Tracker but they can definitely come in handy when you need to quickly track down small bugs. If you have any suggestions for tools/functionality that could be added to make debugging problems within Issue-Tracker easier for you, please let me know by sending me an email at tm@tuxmonkey.com.
A: The simplest is to run "mysqladmin status" from the shell prompt. Any output similar to following indicates that all is well:
Uptime: 8780 Threads: 1 Questions: 227 Slow queries: 0 Opens: 117 Flush tables: 1 Open tables: 11 Queries per second avg: 0.026If Issue-Tracker still redirects you to the "Could not connect to SQL server" error page, it's possible that the httpd server is started before the mysqld server.
If not, try "ps aux | grep mysql" and look for a line similar to:
mysql 3306 0.0 1.8 86404 9560 pts/0 S 10:58 0:00 /usr/local/libexec/mysqld --user=mysql --socket=/var/lib/mysql/mysql.sockIf the above command only returns:
root 27378 0.0 0.1 3584 592 pts/1 S 13:29 0:00 grep mysqlthen the mysql server is not running and you will need to investigate why that is. Go read the MySQL documentation.
If the mysql server is is running but Issue-Tracker still can't connect, it's possible that the default socket path that the server is configured to use is different from where Issue-Tracker is looking. Depending on MySQL version, look for "/etc/my.cnf" and ensure that the "socket" line and
[mysqld]
datadir=/var/lib/mysql
socket=/var/lib/mysql/mysql.sock
[mysql.server]
user=mysql
basedir=/var/lib
[safe_mysqld]
err-log=/var/log/mysqld.log
pid-file=/var/run/mysqld/mysqld.pid
Q:
I get a "Fatal" message and it tells me that MySQL returned an error code. What does
it mean?A: Usually, an error code will be followed by the "english translation" on the next line. If not, locate the MySQL file called "mysqld_error.h" (usually in /usr/include/mysql) and look up the code manually. This may help you figure out what the problem is. This FAQ prolly needs a list of the most common ones and their resolution. Fmg's first code was 1251 - no fun.
(Often, you can login using the same user and password to the issuetracker database (e.g., "mysql -u it -p issuetracker" and the command "SHOW TABLES;" works just fine!)
mysql> SET PASSWORD FOR
-> 'some_user'@'some_host' = OLD_PASSWORD('newpwd');
B) Use UPDATE and FLUSH PRIVILEGES:
mysql> UPDATE mysql.user SET Password = OLD_PASSWORD('newpwd')
-> WHERE Host = 'some_host' AND User = 'some_user';
mysql> FLUSH PRIVILEGES;
Substitute the password you want to use for ''newpwd''
in the preceding examples. MySQL cannot tell you what the original
password was, so you'll need to pick a new one.
mysql> SELECT Host, User, Password FROM mysql.user
-> WHERE LENGTH(Password) > 16;
For each account record displayed by the query, use the Host
and User values and assign a password using the
OLD_PASSWORD() function and either SET PASSWORD
or UPDATE, as described earlier.fmg: this error occurs if you're running a system with apache and mod_php of an older version than the MySQL server. For example, if you don't consider the potential problems and download a newer version of mysql and install it without remembering to also update apache and mod_php! This error drove me nuts until I realized it wasn't a problem with issue-tracker but with php<->mysqld! The 'mysql.pl' script worked dandy all along, of course (uses Perl).
Documentation is definitely not one of my strengths so please bear with me. Thanks to Pawel Zygadlo for proof reading this version and finding my enormous amount of screw-ups :). Please send suggestions, comments, and complaints to tm@tuxmonkey.com.