How to Create a New CCA Roundup Issue Tracker

This procedure requires that you know how to login to www.cca-forum.org and ultimately become root. If you don't have this kind of access, ask someone who does.

1. Choose a name for your tracker. The name for the tracker is going to be used as a database name, a user ID, and an email address; hence, the tracker name should be different than all the current trackers, all the current user IDs, and all the mailing lists. For this example, let's assume the tracker name is cca-tutorial
2. Send email to the ORNL system administrators (a.k.a. volunteers) asking them to create an nonlogin user account with the name of your tracker. This account should have the same UID/GID numbers as the babel-bugs user.
3. Give Roundup permission in MySQL to create a new database to hold the issue tracking information. If your tracker name has hyphens in it, the databasename should be the tracker name with the hyphens removed; otherwise, the databasename is simply the tracker name. In our example, databasename is ccatutorial.Become root on www.cca-forum.org. Find the database user name with
   grep "user =" /var/roundup/trackers/babel/config.ini
   . Use name that appears to the right of the equal sign as the username below. The command show databases is included below, so you can verify that databasename is not already taken by some other application. Bad things will happen below if a database named databasename already exists.
   export HOME=~root
mysql -u root
mysql> show databases;
mysql> grant all on databasename.* to username@localhost;
mysql> flush privileges;
mysql> quit
Bye
   In our cca-tutorial example, the grant line is
   mysql> grant all on ccatutorial.* to username@localhost;
4. Now we can initialize the Roundup database and make the tracker directory. As root execute the following on www.cca-forum.org.
   # export PATH=/usr/local/python2.4.4/bin:/usr/local/roundup/bin:${PATH}
# export LD_LIBRARY_PATH=/usr/local/python2.4.4/lib
# roundup-admin install
Enter tracker home: /var/roundup/trackers/trackername
Select template [classic]: classic
Back ends: anydbm, mysql
Select backend [anydbm]: mysql

 You should now edit the tracker configuration file:
  /var/roundup/trackers/trackername/config.ini
5. Edit the tracker configuration file /var/roundup/trackers/trackername/config.ini using a text editor. Make sure to edit the name:
   name = trackername issue tracker
   Set the web:
   web = https://www.cca-forum.org/bugs/trackername/
   Set the email:
   email = trackername
   This assumes that the user ID created in the second step is equal to trackername. Down in the [rdbms] section, set the database name with
   name = databasename
   Remember from above that the database name cannot have hyphens in it. In the same section, set the database login ID and password
   user = username
password = password
   You should lookup username and password from /var/roundup/trackers/babel/config.ini or some other tracker's config.ini file. In the [logging] section, set the filename to ../../log/internal.log with
   filename = ../../log/internal.log
   . Set the level as well
   level = WARNING
   . In the [mail] section, set the domain
   domain = cca-forum.org
   and the host
   host = localhost
6. Copy /var/roundup/trackers/bocca/schema.py to /var/roundup/trackers/trackername/schema.py.
   cp /var/roundup/trackers/bocca/schema.py /var/roundup/trackers/trackername/schema.py
7. Initialize the database. This step creates a new MySQL database. If there is a preexisting database named databasename, it will be blown away during this step. In this step, you will need to provide an administrator password that you will need to remember.
   # roundup-admin initialise
Enter tracker home: /var/roundup/trackers/trackername
Admin Password: adminpassword
       Confirm: adminpassword
   This message appeared on the screen the last time I did one. I don't believe it's a problem.
   /usr/local/roundup-1.1.2/lib/python2.4/site-packages/roundup/backends/rdbms_common.py:155:
Warning: 'TYPE=storage_engine' is deprecated; use 'ENGINE=storage_engine' instead
  self.cursor.execute(sql)
8. Assuming you want email notification for new issues, copy /var/roundup/trackers/bocca/detectors/newissuecopy.py to /var/roundup/trackers/trackername/detectors/newissuecopy.py.
   # cp /var/roundup/trackers/bocca/detectors/newissuecopy.py /var/roundup/trackers/trackername/detectors/newissuecopy.py
   Edit /var/roundup/trackers/trackername/detectors/newissuecopy.py and change the email address in the cl.send_message function to one appropriate for the new tracker.
9. You can change the look and feel of the tracker by editing the files in the /var/roundup/trackers/trackername/html directory. Normally, I edit style.css, page.html, and issue.item.html. You may want to copy cca_logo.png and/or cca-logo-trans-180.gif from /var/roundup/trackers/bocca/html/. It may also be useful for you to compare the default files with those in the bocca tracker
   # diff -r /var/roundup/trackers/bocca/html /var/roundup/trackers/trackername/html
   You may just copy some files from bocca if you want to mimic it's style.
10. Now we need to fix up some of the file/directory permissions. Change directory to /var/roundup/trackers/trackername and execute the following chown and chmod commands.
    # cd /var/roundup/trackers/trackername
# chgrp -R babel-bugs .
# chmod -R go-w .
# chmod -R g+wX db
# chmod -f g+s db db/files db/files/*
11. If the administrators have not created the user ID you asked for in step two, pause here! You don't want to do any other the rest until you have a working user id and hence a valid mailbox.
12. Use your favorite text editor to edit /etc/default/roundup. Find the line with trackers= followed by a space separated list of trackername=trackerdirectory definitions. For example,
    trackers='babel=/var/roundup/trackers/babel ccafe=/var/roundup/trackers/ccafe'
    Add your tracker to this list by inserting a space followed by trackername=/var/roundup/trackers/trackername. Once you save this file, the cronjob that brings in email will start checking for mail to trackername. If you want weekly reminders about unassigned issue sent to a particular address, add an entry to the unassignedreminders variable defined in /etc/default/roundup. Each entry is
    trackername=emailaddress
13. Restart the Roundup server.
    # /etc/init.d/roundup restart
14. Verify check your new issue tracker with a WWW brower. Open URI https://www.cca-forum.org/bugs/trackername/. You can login to the tracker with username admin and the password adminpassword used above.
15. You can tweak the look and feel with more editing in /var/roundup/trackers/trackername/html/ if you want. Don't create any issues yet.
16. If the administrators have created the user ID you asked for in step two, edit /etc/postfix/aliases.virtual. There are several lines in a section labeled # Roundup related. Add an analogous line for your tracker
    trackername@cca-forum.org      trackername
    I am not really sure why this is necessary.
17. Try creating a sample issue using the WWW interface. If it fails, double check that /var/roundup/trackers/trackername/db and it's subdirectories are writable by either group babel-bugs or by user babel-bugs. The Roundup server runs as user babel-bugs/group babel-bugs, so it must be able to run in this area.
18. Verify that the new issue email was delivered. If the recipient is a Mailman mailing list, it may be stuck waiting for moderator approval. In these cases, it's good to subscribe trackername@cca-forum.org to the mailing list, but click the "nomail" option in the Mailman's Membership Management screen. This will probably allow the tracker to send email to the list without needing moderator approval.
19. By adding your tracker to /etc/default/roundup, some jobs in the babel-bugs crontab already have started executing on your tracker. Every three minutes, /usr/local/roundup/bin/roundup-email processes incoming email to all the trackers, and /usr/local/roundup/bin/roundup-remind-all runs weekly to remind people about unresolved issues that have been assigned to them. You may want to look at babel-bugs crontab to look at the other available things that you can run on the new tracker.
    # crontab -u babel-bugs -l
    If you want to edit the crontab to add some additional jobs on your tracker, use
    # crontab -u babel-bugs -e
    .
20. At this point, your tracker is pretty much done. If spam becomes excessive you make want to install ASK like I did for the babel-bugs tracker.