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.
| 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. |
| Section | Item | Description |
|---|---|---|
| DEFAULT | host | Interface JCR listens on. Default is 0.0.0.0, 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. |
Configuration is likely to be required in the service startup script (bin/jcr) provided with JCR. This is covered in the installation guide.
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.
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.
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.
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.