JCR - Setup and Configuration

Return to contents page


Configuration File

JCR uses a config file in .ini file format, a la Windoze. You'll have generated it at some stage using paster make-config jcr jcr.ini (or whatever you decided to call the file).

Most of the config file is really system configuration, and shouldn't be changed. However, the things you can change are listed in the following sections. The most important items are shown first, followed by less commonly changed items.

Note: In all parts of the config file except the logging section, the string %(here)s is automatically expanded to the path of the directory containing the config file.

Main Configuration Items

Section Item Description
app:main sqlalchemy.url

Url for connecting to the database - format depends on the DBMS you are using.

For Postgres (using the psycopg driver), the format is: postgres://user:password@host/dbname, e.g. postgres://jcr:itsasecret@localhost/jcr

For Mysql (using MySQL-python), the format is: mysql://user:password@host/dbname, e.g. mysql://jcr:itsasecret@localhost/jcr. You'll want to also set the sqlalchemy.pool_recycle item for Mysql.

For Sqlite (using pysqlite), the format is: sqlite:///path-to-db-file, e.g. sqlite:///%(here)s/jcr-sqlite.db or sqlite:////var/jcr/jcr-sqlite.db. Note that Sqlite is usually not build thread-safe on Linux or UNIX, so it shouldn't be used for production.

app:main sqlalchemy.pool_recycle Sets the number of seconds after which a database connection should be closed (default is to use indefinitely). Use for Mysql only, and set to 3600
app:main jcr.base.dir The base directory under which JCR will store all its files (projects, filesets etc. Defaults to %(here)s/var, i.e. in a var subdirectory under the directory containing the config file, but something like /var/jcr is recommended
app:main jcr.email.server If you want notification emails to be sent to reviewers, this should be the address of the SMTP server to use for sending mail, as hostname or hostname:port, e.g. mailserver.domain.com
app:main jcr.notify.baseurl The base for all JCR URLs in emails, as http://some.host/ or http://some.host:port/, e.g. http://jcr.domain.com:5000
handler_file args

Sets the location of the log file, as well as how often it is rolled, and how many rolled versions are retained.

Format is ('logfilepath', 'midnight', 1, retaincount), e.g. ('/var/jcr/log/jcr.log', 'midnight', 1, 14), which rolls the log file daily, and keeps the last 14 days' log files. NOTE: This item does not support the %(here)s token.

The default is ('jcr.log', 'midnight', 1, 14), but note that the relative path is only used so that it always works on installation - an absolute path should be used for production.

Other Configuration Items

Section Item Description
DEFAULT host Interface JCR listens on. Default is, i.e. all
DEFAULT port Port JCR listens on. Default is 5000
DEFAULT smtp_server Hostname or IP address of an SMTP server. Comment out if none available. JCR will send email to this address on logerrors. Note the different setting for the email server used for sending notification emails to reviewers: see jcr.email.server above
DEFAULT email_to Email address to send log error emails to. Comment out if you don't want emails sent when JCR encounters an error
DEFAULT error_email_from Source email address for log error emails. Comment out if you don't want emails sent when JCR encounters an error
app:main jcr.assets.externalscriptspage

URL for a web page describing and linking to external scripts (e.g. for creating fileset tarballs from your source control system, generating selection files from your bug tracking system etc.).

Default is /assets/externalScripts.html, which describes the standard JCR scripts

app:main jcr.superuser.advanceprojects Determines whether the superuser can advance the state of projects that would otherwise not be allowed to advance, e.g. not all comments actioned before the project is completed.
app:main jcr.model.reviewdecisions If present, this is the name of a file within the conf directory (under the JCR base directory) containing your own Review Decision types. If the file is valid, these will be used instead of the standard JCR types. See below under Overriding Review Decisions for details.
app:main jcr.email.sender Sender address to use for notification emails. If blank, or if jcr.notify.ownerissender is configured in the notification service, the project owner's email address will be used instead. E.g. jcr_no_reply@domain.com
app:main jcr.notify.ownerissender If True, the project owner is used as the email sender address for all notification emails. If False or not present, the value of jcr.email.sender will be used.
app:main jcr.notify.projectreview.enable If True, email notifications will be sent to all reviewers when each project is ready for review. If False or not present, no emails will be sent.
app:main jcr.notify.projectreview.template Allows a custom email template to be used for review notifications. If set, this must be a filename in the JCR_BASE/conf/emailTemplates directory. If not set, the default template will be used. See documentation for template requirements
app:main jcr.notify.projectpostreview.enable If True, email notifications will be sent to all nominated comment actioners when the project is put into the post-review state. If False or not present, no emails will be sent.
app:main jcr.notify.projectpostreview.template Allows a custom email template to be used for post-review notifications. If set, this must be a filename in the JCR_BASE/conf/emailTemplates directory. If not set, the default template will be used. See documentation for template requirements.
app:main jcr.reviewfile-cache.enable Enables caching of rendered lines from review files, to speed up display. Accepts True or False, defaults to True
app:main jcr.reviewfile-cache.cachedir Base directory for caching rendered lines from review files. Defaults to %(cache_dir)s/reviewfile-cache, i.e. a directory called reviewfile-cache under the directory specified by the cache_dir setting in the config file
app:main jcr.highlight-syntax Enables syntax highlighting of source code (True or False). Defaults to True
app:main jcr.highlight-syntax.lexer.ext Overrides the standard Pygments file extension:lexer mapping, where ext is the file extension to map IN LOWER CASE, and the value is the name of the Pygments lexer you want to use. You may set zero or more of these, e.g. jcr.highlight-syntax.lexer.ccl = sql would force all files with a .ccl extension to be rendered using SQL syntax highlighting. See this page for details
app:main jcr.disable-vcs.TAR Disables the ability to upload filesets to JCR when creating projects - only true Version Control Systems can be used
app:main jcr.disable-vcs.SVN Disables the ability to use Subversion repositories when creating projects
app:main sqlalchemy.echo Enables or disables logging of each SQL statement executed (True or False). Defaults to False
app:main set debug Must be set to false, for security reasons
handler_file level Sets the logging level for the log file. Options are DEBUG, INFO, WARNING or ERROR. Defaults to DEBUG, but INFO should be fine for production.
handler_console level Sets the logging level for logging to the console. Options are as for the handler_file level above. Defaults to INFO, but should be set to ERROR if installed as a service.

Startup Scripts

Configuration is likely to be required in the service startup script (bin/jcr) provided with JCR. This is covered in the installation guide.

External Scripts

JCR allows project owners to download scripts via an external scripts page. These scripts typically will generate project review tarballs (possibly directly from a Source Code Management System), and may also generate file selection lists (if your Source Code Management System is integrated with your bug and enhancement tracking system, as ours is).

To add or modify a script, you need to:

  • Add the script to the asset directory, and make sure it is owned by the appropriate user and group (usually jcr:jcr)
  • Change the external scripts page to make the script available. The default page is asset/externalScripts.html, but this may have been changed in the configuration file. This page is just static HTML, so it's in your culpable hands...

If you plan to write your own scripts, see the description of the file formats.

Project Notes Template

The (optional) project notes template is conf/projectNoteTemplate.txt under the JCR base directory. If found, this is used as the default contents for the project notes field when creating a new project.

Notification Email Templates

By default, notification emails are generated using built-in templates. However, these can be overridden by user-supplied templates (see the jcr.notify.*.template configuration items above).

See notification templates for details of the format required.

Overriding Review Decisions

The optional jcr.model.reviewdecisions configuration item must provide a filename within the conf directory under the JCR base directory. The contents of the file, if valid, will be used instead of the built-in JCR Review Decision types (see the dropdown list on the comment dialogs, e.g. 'Fix before release').

The contents of the file must be as follows:

  • Lines starting with '#' are ignored

  • Whitespace, including blank lines, is ignored (except within quotes)

  • The file must start with a '[', and finish with a ']'

  • Each line between those square brackets must consist of:

    • '['
    • A one or 2 character string code for the review decision, between quotes, and followed by a comma. It is this code that is stored in the database
    • A string label for the review decision, between quotes, and followed by a comma. The label is what is shown on screen
    • Either True or False (no quotes) to indicate if the Review Decision requires action before the review project can be completed
    • ']', followed by a comma on all lines except the last.

Note that the order in this file is the order that the values will show in the dropdown box on screen.

See the provided reviewDecisions.lst file for an example.