User Maintenance

The 'Users' tab page is the default after selecting 'maintenance'.

The page lists all the users on the system (except the administrator), in the standard sortable list. Links allow editing and changing the password of each user, while the 'Create new user' link allows adding a user to the database.

Clicking the 'Edit' link for a user shows the user's details above the user list. The fields are:

• Username (required). Must be unique within the system, and contain only letters, digits and underscores
• Full name (required)
• Email address (optional)
• Enabled. If this box is not ticked, the user will not be able to log in.

Click on the 'Save' button to update the user.

When adding a new user, the same fields are displayed, with the addition of 2 password fields. Passwords are mandatory, and must be at least 6 characters long. Again, click 'save' to add the user.

Clicking the 'Change password' link for a user brings up a page to do exactly that.

The administrator's password can be changed using the 'Change password' menu item on the main page.

Project Maintenance

The 'Projects' tab page lists all projects in the system, including completed projects. The list can be sorted in the usual way. For each project, links allow generation of a status report and deletion.

The status report is the same as the Status Report page visible to all reviewers of the project.

Deleting a project should be done with great caution. It will have the following effects:

• Deletes the project from the database, including all comments, status history, file selections etc.
• Deletes all file diffs generated for the project from the file system.

However, note that File Sets used by the project are not deleted - see under File Set Maintenance for details of deleting file sets.

File Set Maintenance

The 'File sets' tab page provides a project-centric view of all file sets in the system, with each item showing use of a file set in a particular project. Any unused file sets are also shown in the list, but without project details. Note that file sets are used only by projects not associated with a VCS repository.

If the file set is not used by any project, a link is provided to delete it. Deleting a file set should be done with great caution. It will have the following effects:

• Deletes details of the file set from the database
• Deletes the directory containing the physical files from the file system.

File sets may also be archived, using the Archive link. This should also be done with caution, since it cannot be undone. Archiving a fileset has the following effects:

• All files in the fileset which are not being used by review projects will be deleted. Note:

  • No file which has been Added or Removed in a review project should be deleted
  • Changed files in review projects may be deleted, since the diffs are held with the project

• The fileset is flagged as archived in the database, and can no longer be selected for any review project

• Attempts to view deleted files (e.g. by following Java class links, or using the View any File link, will show an error message suggesting that the file may have been archived.

Note that archiving a file set will be disallowed if any project using it is not complete.

Repository Maintenance

The 'Repositories' tab page lists all the Version Control System repositories configured. You can add and edit (but not yet delete) repositories. As of JCR 0.7.0, the only repository type supported is Subversion.

Subversion URLs should be in the form file:///path/to/repo or http://host.name/path/to/repo. Include a username and password if the repository is not publicly accessible. Note that as of JCR 0.7.0, the password is stored in the database in the clear - this will change in a future version.

Any enabled repository will be available to project owners when setting up new review projects.

Project Notes Template

If JCR finds a file with the path conf/projectNoteTemplate.txt under the JCR base directory, it uses this as a template (i.e. default contents) for the project notes field when creating a new project. It's useful to add sections for items you normally expect to see in the project notes, e.g. URLs for:

• Test coverage report
• Javadoc or other documentation generated from code
• Static analysis results.

The JCR installer provides a sample template.

External Scripts Page

JCR comes with a useful scripts for generating review tarballs, but it's likely you'll want to make your own scripts available. You do this by making them available via URL, creating a web page containing documentation and links to your scripts, then setting the jcr.assets.externalscriptspage property in the JCR config file. See the Config Page for more details.

Email Notification Templates

By default, notification emails are generated using built-in templates. However, these can be overridden by user-supplied templates. Override templates must be located in the conf/emailTemplates directory under the JCR base directory, must be configured in the .ini file using the appropriate jcr.notify.* items, and must follow these rules:

• The template must be a valid Mako template

• The first line of the template must not be blank, and will be used as the subject for the email

• All lines after the first line will be used as the body of the email, except that any blank lines at the start will be stripped

• Templates must consist of US ASCII characters only

• Templates may use only the tokens listed below to refer to JCR objects. Any other tokens may work initially, but may change at any time

• Supported tokens for all notification emails are:

  • projectName - the full name of the project
  • projectOwner - the full name of the project owner
  • projectDelegate - the full name of the project owner's delegate, or '' if none
  • projectNotes - any notes attached to the project
  • projectUrl - the full URL for the main page for this project in JCR
  • commentsUrl - the full URL for the All Comments page for this project in JCR
  • projectReviewerList - a list of the name and review role (e.g. 'Joe Bloggs (Secondary reviewer)' for each of the reviewers assigned to the project

• The comment action notification email also supports a commentsToAction token. This is a list of objects with the following properties:

  • title - either the file path and line number (for a file comment) or the thread title (for a project comment)
  • comment - the original comment text
  • owner - the full name of the reviewer making the original comment
  • reviewComment - the text of any comment made in the review meeting
  • reviewDecision - the text of the decision made in the review meeting
  • reviewer - the full name of the person recording the decision in the review meeting
  • indentedComment(indentSize) - a method which returns the original comment text with each line indented by this number of spaces
  • indentedReviewComment(indentSize) - a method which returns the review comment text with each line indented by this number of spaces.

The default template for review notifications is:

[JCR] Project is ready for code review: ${projectName}

You have been made a reviewer for the JCR project:
${projectName}.

Please review the code in this project, and contact ${projectOwner}
%if projectDelegate:
(or ${projectDelegate})
%endif
when you have finished, or if you have any questions.

The review project can be found here:
${projectUrl}

Reviewers on this project are:
%for reviewer in projectReviewerList:
- ${reviewer}
%endfor

Notes attached to the project:
${projectNotes}

The default template for comment action notifications is:

[JCR] Please complete review actions in project: ${projectName}

You have been assigned review actions to complete for the JCR project:
${projectName}.

The review comments for the project can be found here:
${commentsUrl}

Please complete the following actions, and contact ${projectOwner}
%if projectDelegate:
(or ${projectDelegate})
%endif
when you have finished, or if you have any questions.

%for comment in commentsToAction:
---------------------------------------------------------------------
Location:         ${comment.title}
Action required:  ${comment.reviewDecision}
Original comment (by ${comment.owner}):
${comment.indentedComment(4)}
%if comment.reviewComment:
Review meeting comment (by ${comment.reviewer}):
${comment.indentedReviewComment(4)}
%endif

%endfor

Checking Disk Space

Because JCR typically stores 2 copies of all files for a project (for the original and modified versions), and also maintains a cache of lines from review files, it can use a lot of disk space. It's worth making sure you're monitoring disk space on the box it runs on.

If you're using a RedHat-based distribution, you may have diskwatch (?) running via anacron. This will email root if disk usage passes configured limits. This should be enough. Otherwise, you might like to check out Nagios, which is my personal favourite for system monitoring.

It's worth periodically deleting old projects and filesets which were never used. You can also archive older file sets to reclaim disk space.

Rotating Logs

The JCR log (typically log/jcr.log) will be rotated daily, and the last 14 days' logs will be kept (assuming the standard logging configuration in the config file).

However, stdout log doesn't rotate (if you're running JCR as a service). In theory there shouldn't be much written to it, but you should keep an eye on the size of this log, and periodically roll it by:

• Renaming the stdout log file
• Restarting JCR.

Clearing the Disk Cache

By default, JCR caches details of lines in review files. This makes quite a difference to the speed of rendering pages, particularly when syntax highlighting is enabled.

The cache is on disk, by default in the data/reviewfile-cache directory (see the jcr.reviewfile-cache.cachedir configuration setting). There is a separate file for each review project, under data/reviewfile-cache/container_file, although you can't tell which project each file is for.

If disk space is an issue, you can either delete individual files, or the whole data/reviewfile-cache directory. However, you should make sure that JCR is stopped if you delete the whole directory. And if you didn't stop JCR and you start seeing weird errors, restart it.

Backing Up

You should set up a backup regime that covers the following:

• JCR install directory (shouldn't change after you've finished installation and configuration)
• The database
• JCR base directory, containing all the project and fileset data. You may wish to exclude the log directory from the backup, and also perhaps prune the files backed up using mkBackupList.py (see below)
• Your SysV Init JCR script (if running as a daemon).

If using Postgres, you can dump the database using pg_dump. Here's a rough script you can use to back up named databases from root's crontab (make sure this dumps to a different filesystem than the one containing your databases!):

#!/bin/sh

# Backup postgres databases (timestamped)

BACKUP_DIR=/backup/postgres

# Add all the DB names you want to back up, as a space-separated list
DBS="jcr"

for db in $DBS; do
    outPath=$BACKUP_DIR/$db-`date +%Y%m%d`.dump
    su - postgres -c "pg_dump --blobs --format=t --file $outPath $db "
done

The JCR base directory gets large over time, with all those file sets and diffs. If backup space is limited, you might like to try the bin/backupjcr.sh script. This attempts to produce a list of all files under the base directory that are really required, by including only projects at or beyond review status. For each of these, the following files/directories will be added to the list:

• Project data directory (include java list, original file list and diff list)
• All files under project diff directory, so long as they are selected for review and have a status of 'changed'
• All files in the original file set for the project, so long as they are selected for review and have a status of 'removed'
• All files in the modified file set for the project, so long as they are selected for review and have a status of 'added'.

This list is then used as the input to tar, to produce a gzipped tarball in the backup directory, including the date in the filename. You'll have to adjust the paths in the shell script to suit your installation.

Note that this shell script is vulnerable to a temp file attack - please check it first to see that you either accept the risk or take steps to mitigate it.

Alternatively, you can use the bin/mkBackupList.py script. This produces the file list used by the bin/backupjcr.sh script. You need to pass the script the path to the site config file, e.g.:

bin/mkBackupList.py jcr.ini > ~/tmp/jcrBackupList

Note: All paths output by this script are absolute.

Resetting the adminstrator password

Use the bin/resetAdminPassword.py script. You have to provide this with the path to the JCR config file, e.g.:

$ bin/resetAdminPassword.py jcr.ini
...
Enter new administrator password:
Confirm new password:
Password updated successfully
$