This section is intended to guide you through the absolute minimum required to get a sort-of operational JCR installation, so that you can have a play and decide whether it's useful or not. You'll end up with the following configuration:
- Database: Sqlite (not recommended for heavy production use, but generally OK)
- Base directory: under the install directory. This works, but it's better to have it separate
- Log file: in the install directory. This works, but it's better if you put it under your (relocated) base directory (see previous point)
- Sample review project installed, along with 2 sample users (in addition to the admin user)
- Optionally, integration with one or more Subversion repositories
- No email notifications (but these are easy to configure).
Make sure you have the following installed - if you need to install them, use your package management system, e.g. apt-get or yum.
- Python 2.4+ (2.5+ recommended)
- Python header files (i.e. .h files) to match your version of Python. The package may be python-devel (Fedora) or python-dev (Ubuntu).
- Windows Note: Not required for native Windows
- Pysqlite - typical package names are python-sqlite (Fedora) or python-pysqlite2 (Ubuntu).
- Windows Note: Windows binaries are available from google code - ensure you get the right one for your Python version
- Cygwin Note: Pysqlite may not be available as a package, so instead just install Sqlite 3
- GCC (or a similar C compiler). At least one package used by JCR compiles a C-based extension
- Windows Note: Not required for native Windows
- Pysvn (if you want to create review projects directly from Subversion) - may be available as pysvn package (Ubuntu, some versions of Fedora and RHEL), or you may have to build it from source (see section below).
- Windows Note: Windows binaries are available from tigris.org - ensure you get the right one for your Python and Subversion versions.
JCR uses easy_install for installation.
Check if you have easy_install, by typing which easy_install. If not, as root, install or update easy_install as follows:
# cd # wget http://peak.telecommunity.com/dist/ez_setup.py # python ez_setup.py
If you have any problems, check this page for advice.
Windows Note: Download the binary installer from pypi, install, then add your Python/Scripts directory to the PATH.
As yourself (not root!), untar JCR in an appropriate place (the example uses your home directory):
$ cd $ tar xzf jcr-0.7.2.tar.gz
As root, change to the JCR directory you've just untarred, and run easy_install:
# cd <yourHomeDirectory>/jcr-0.7.2 # easy_install -f . jcr
This should install a number of dependencies (Pylons, Paster, Sqlalchemy, Authkit etc.), and then install JCR. JCR will be installed under the site-packages directory of your Python home directory, e.g. /usr/lib/python-2.5/site-packages/jcr-0.7.2.egg/
Cygwin Note: If you were not able to install Pysqlite as a package, you should now install it using easy_install as shown below. Note that this will require both GCC and Sqlite 3 to be installed. See the Installation section of the FAQ if you have any problems
# easy_install pysqlite
If you have any other problems with this step, see the Installation section of the FAQ.
As yourself (not root!), change to the JCR directory, and generate a config file (any name you like - the example uses jcr.ini):
$ cd <yourHomeDirectory>/jcr-0.7.2 $ paster make-config jcr jcr.ini
This will create the jcr.ini config file in the current directory. For sample use with Sqlite, you shouldn't have to change anything in it, but usually you'd adjust things like the database URL to use, the base directory, and the log file path.
Still as yourself, and in the JCR directory, run the setup command, and answer 'Y' (and hit Enter) to every question. This will initialise the database and directories, and insert a sample project in the database:
$ paster setup-app jcr.ini
This will also ensure that you have the required libraries and utilities installed to integrate with Subversion, and to upload filesets for review.
Windows Note: This will complain about the absence of GNU tools such as grep, and ask if you want to continue with the installation - you should say yes (Y).
Still as yourself, and in the JCR directory, run JCR:
$ paster serve jcr.ini
You should now be able to login to JCR at http://localhost:5000/. You have the following users available (all with the password 'password0'):
- admin - the administrator or superuser
- johnd - a normal user, who owns the sample project
- wille - a normal user.
NOTE: If you wish to use a Subversion repository, you must log in as the admin user, select Maintenance and then the Repositories tab, and add the details of your repository.
Once you've played with JCR and decided that you'd like to use it in anger, these are the things you should change from the above minimal installation:
- Subversion: If you have the appropriate Python Subversion interface (pysvn) installed already, JCR should allow you to use Subversion without any further action. However, if you don't have the library installed, see the Full Installation section below
- Database: Sqlite is very impressive for what it does, but if you're likely to be using JCR a lot, Postgres or MySQL are recommended. Note that some binary versions of Sqlite are not built to be threadsafe on Linux/Unix - these will not work with JCR
- Data Location: You should put the JCR base directory somewhere appropriate on the filesystem, and not under the JCR binary directory (where the installer creates it by default)
- Log File Location: Again, it's best to have this somewhere other than the binary directory
- Email notifications: If you want email notifications for reviewers and/or review action owners, you'll have to complete the jcr.email and jcr.notify configuration properties
- Security: Now's the time to ensure that JCR runs in a suitably secure manner. This is mainly an issue of ensuring that JCR runs (and connects to the database) as a suitably unprivileged user.
See the following section for details. Note that the easiest way to configure JCR is by running paster setup-app /path/to/jcr.ini again, and entering your choices.
These instructions are currently written for a fairly standard Linux system where the root account isn't locked, and using RPM as the package manager (e.g. RedHat, Fedora).
If you're using Ubuntu or one of its variants, you'll find a few differences, including:
- You have to use sudo instead of su-ing to root
- You'll be using apt-get or one of the GUI wrappers (Adept, Synaptic etc.) instead of RPM and Yum
- You don't have a service command - you have to use one of the scripts in /etc/init.d directly to start and stop services.
Most commands below that mention being root will work with sudo prepended. E.g.
# easy_install -f . jcr # For RedHat, Fedora etc. # sudo easy_install -f . jcr # For Ubuntu
The following required items need to be in place before installing JCR:
OS: Linux, other UNIX, Cygwin or Windows
JCR is currently tested on Redhat EL 4 and Kubuntu Hardy (8.0.4), and has also been used successfully on Cygwin and Windows (with less testing on the latter).
If you want to support direct upload of tarballs or zipfiles for review, JCR depends on several GNU tools (note: don't try to use the Solaris versions), including:
- tar (if uploading tarballs for review)
- unzip (if uploading zip files for review)
- diff (only for projects created before version 0.6.2)
- grep (only for projects created before version 0.6.2)
Python 2.4 or later (2.5+ recommended)
It's pretty likely that Python came with your distro. Tested with 2.4 and 2.5
This is a package management system for Python. It allows installation of systems like JCR, as well as location, downloading and installing of dependencies.
Install this by downloading ez_setup.py, and executing it as root.
Database: PostgreSQL 8.x, MySQL 5.x, or Sqlite
Postgres is a very capable multi-platform database. It's almost certainly available as a package with your distro - for RedHat-based systems the packages are postgresql, postgresql-server, postgresql-libs and postgresql-docs. Make sure that it's set to start on system startup. Tested with 8.0 and 8.2.
Alternatively, you can use MySQL, which is also probably available as a package (for RedHat try mysql and mysql-server, for Ubuntu mysql-client and mysql-server). MySQL tends to be a little faster than Postgres but not quite as feature-complete. Tested with 5.0.
Sqlite is a light-weight database that is trivially easy to set up, but which you probably shouldn't use it for heavy production use. The default JCR configuration is set to Sqlite, just because it's the fastest way to get a working installation. If you plan to use it, ensure that your version is compiled to be threadsafe - if not, JCR will fail in spectacular and random ways.
Note: The in-memory configuration for Sqlite WILL NOT WORK with JCR.
Version Control System: Subversion
If you want JCR to extract files from a Subversion repository, you'll need the Subversion client libraries installed. For Ubuntu, and some versions of Fedora and RedHat Enterprise Linux, you should install the package python-svn. For other distros, including Cygwin, see the section below on building Pysvn from source.
Note that JCR uses the built-in web server in Pylons to serve all pages. It therefore doesn't require a web server (like Apache).
NOTE: This section must be carried out as root.
First, decide which user and group JCR should be owned by, and create them if necessary (using useradd). You may want to create a special user called 'jcr' for this - I'll assume you have done so from now on. Note that this is not strictly necessary, it's just a good idea from a security standpoint.
Untar the binary distribution to some suitable directory, e.g. /opt. None of the files in the directory (e.g. /opt/jcr-0.7.2) are required to run it, but they're necessary while configuring. Change ownership of the directory and all files to the JCR user and group:
chown -R jcr. /opt/jcr-0.7.2
IMPORTANT NOTE: Unless you particularly enjoy pain, and are looking for more of it in your life, you should install the appropriate database driver using your OS's packaging system, or from some other binary source. The drivers required are:
- Postgres: psycopg2. Ubuntu package is python-psycopg2
- Mysql: MySQL-python. Ubuntu package is python-mysqldb
- Sqlite: pysqlite. Ubuntu package is python-sqlite
Also, if you want to use Subversion, ensure you have Subversion installed (client only required).
Change to the JCR directory, and use easy_install to install JCR plus its dependencies. Insert your chosen database inside the square brackets - options are postgres, mysql or sqlite:
# easy_install -f . jcr[postgres] # or mysql or sqlite instead of postgres
This should retrieve and install a number of other packages, including Pylons, Paster, Authkit, SQLAlchemy etc. If you have any problems with downloading and installing anything but the database driver, check the Easy_install page, particularly for information about proxy settings etc.
IMPORTANT NOTE: The most likely problem is in installing the database driver, since these typically require both a C compilation step and access to the header files for your chosen database. See the note above about installing the appropriate driver as an OS package before starting.
If you have any problems, see the Installation section of the FAQ.
NOTE: This installs JCR under your Python site-packages directory, e.g. /usr/lib/python2.5/site-packages/jcr-0.7.0/.
You'll have to create the database, and tell the DBMS about the user that JCR runs under (on the assumption that you created a user for this). The way you do this depends on whether you chose Postgres or MySQL as your DBMS (there's no setup required if you're using Sqlite).
All actions in this section should be performed as the 'postgres' OS user. This user may not have a password set, so su to it from root:
# su - postgres $
Create the jcr user (for security, we say that it can't create databases and is not a superuser). Enter a password for the user (in postgres) when prompted. Note that if you're using a non-standard port or another host, you'll have to set the appropriate options here:
$ createuser -ADEP jcr Enter password for new user: Enter it again: CREATE USER
Create a database for JCR, which will be owned by the 'jcr' user:
$ createdb -O jcr jcr
IMPORTANT: Make sure that the 'jcr' user can connect to the database (you'll be prompted for the password). If the command succeeds, and you end up in psql, press Ctrl-D to exit:
$ psql -h localhost -U jcr jcr
Welcome to psql 8.0.4, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help with psql commands
\g or terminate with semicolon to execute query
\q to quit
jcr=# <-- Hit Ctrl-D when you get to this point
$
If this doesn't succeed, you'll need to update postgres's host-based access control file (pg_hba.conf), to tell it how the user can connect. You'll probably need a line like the following, but note that it must appear before any more general line - postgres takes the first setting that applies, and uses it:
# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD host jcr jcr 127.0.0.1 255.255.255.255 md5
Remember to set your own IP address details if required. Note that the md5 setting tells postgres to require an MD5 hash of the user's password to connect.
JCR is less well tested with MySQL, but should be OK. However, I know less about MySQL than I do about Postgres, so bear that in mind when reading these instructions. You may need to read between the lines, or indeed straighten the lines...
Start off logged in as root. First, ensure that MySQL is running and accepting TCP/IP connections - on a RedHat or Fedora box you could use:
# service mysqld status mysqld (pid 10163) is running... # netstat -an | grep 3306 tcp 0 0 0.0.0.0:3306 0.0.0.0:* LISTEN
Next, you need to create the database (still as root, I presume):
# mysqladmin -p create jcr
Now, create the jcr user, and give it rights to access the database. Hit Ctrl-D to exit mysql when you're done. Remember to set your own password :}
# mysql -p jcr Enter password: Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 37 Server version: 5.0.45 Source distribution Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> grant all privileges on jcr.* to 'jcr'@'localhost' identified by 'itsasecret'; mysql> grant all privileges on jcr.* to 'jcr'@'%' identified by 'itsasecret'; mysql> <-- Hit Ctrl-D when you get to this point
Now check that you can connect to the database as the jcr user:
# mysql -p -u jcr jcr Enter password: Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 37 Server version: 5.0.45 Source distribution Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> <-- Hit Ctrl-D when you get to this point
You don't have to do anything for Sqlite - JCR will create the database and schema for you in the setup-app stage.
Pysvn isn't available via easy_install.
If there is no pysvn package available for your distro, and you want JCR to connect to Subversion, you'll need to build Pysvn from source. This isn't difficult, but it has a few dependencies. The following lists are typical:
- subversion
- subversion-devel
- apr-devel
- apr-util-devel
- e2fsprogs-devel
- neon-devel
After all the dependencies are met, you'll have to do something like this (for Python 2.5):
$ python setup.py backport $ python setup.py configure $ make $ su # cp -a pysvn /usr/lib/python2.5/site-packages/
See the pysvn website for details.
NOTE: All these steps must be carried out as the JCR user, i.e.
# su - jcr
Now that JCR is installed, the next step is to generate a configuration file. You can put this anywhere you like, but the JCR install directory (where you untarred JCR) is probably a good choice.
$ cd /opt/jcr-0.7.0 $ paster make-config jcr jcr.ini
This creates a default configuration file called jcr.ini in the current directory.
NOTE: The config file contains the database credentials (username and password) as cleartext, so you should ensure that this file (and preferably the whole JCR install directory) are not accessible to other users.
Note that paster was installed automatically by easy_install as one of the dependencies of JCR.
At a minimum, you need to configure the following items in the config file you just generated. See the configuration file page for details.
- sqlalchemy.url - connection details for the database you've chosen
- sqlalchemy.pool_recycle - if using Mysql
- jcr.base.dir - the base directory you created under Package installation above
- args (under [handler_file]) - path to the log file
You'll also likely want to configure email notifications, in the jcr.email and jcr.notify sections.
The last step is to set up JCR. This checks that everything is ready to go, and can also:
- Create the database and schema
- Add the superuser to the database
- Create the required directories
- Install a sample project.
Change to the directory containing the JCR config file, and, as the JCR user:
$ paster setup-app jcr.ini
Follow the prompts, answering 'Y' or 'N' (and pressing Enter) for each one.
You should now have everything you need to start JCR. You should probably start it from the command line first, to make sure that everything's OK, then you can move on to running it as a daemon.
As the user who owns JCR (I'm assuming jcr), change to the directory in which you created the JCR config file:
$ paster serve jcr.ini Starting subprocess with file monitor Setting boolean property jcr.superuser.advanceprojects to True ... serving on 0.0.0.0:5000 view at http://127.0.0.1:5000
You should now be able to login to JCR at http://localhost:5000/. You have the following users available (all with the password 'password0'):
- admin - the administrator or superuser
- johnd - a normal user, who owns the sample project (if you installed the sample project)
- wille - a normal user (if you installed the sample project).
This would be a very good time to change the admin password!
To kill JCR, just press Ctrl-C in the terminal window.
You'll probably want JCR to start when the system starts. I'm assuming in this section that your system uses the SysV Init (runlevel-based) mechanism. Furthermore, these instructions assume that your system is RedHat-based, so you'll have to modify them a bit for other distributions.
In the bin directory is a script called jcr, suitable for starting and stopping jcr as a daemon. You should follow these instructions as root.
First, copy the script from your jcr directory to /etc/rc.d/init.d, and make it executable:
# cp /opt/jcr-0.7.2/bin/jcr /etc/rc.d/init.d # chmod 744 /etc/rc.d/init.d/jcr
Check the script to ensure that it matches your installation. In particular, check or change the following variables:
- JCR_CONFIG_FILE - path to your JCR config file
- JCR_VAR_DIR - the base directory for all data about projects, filesets etc.
- JCR_USER - the user that JCR should run as
Now, use chkconfig to install the service. By default it's set to run at runlevels 3, 4 and 5:
# chkconfig --add jcr # chkconfig --list jcr jcr 0:off 1:off 2:off 3:on 4:on 5:on 6:off
You should now be able to control the JCR service with the service command:
# service jcr status JCR is not running # service jcr start Starting JCR
Sorry, but this section largely remains to be written...
If the issue you see isn't in the list below, check the logs that JCR writes - these are usually in the log directory under the JCR_VAR_DIR you defined above in Starting as a Daemon. The most useful is likely to be the JCR log itself. Check your JCR config file to ensure that you have the log level set to DEBUG. If that doesn't tell you anything, check the stdout.log.
If you get a stack trace and IOError, check the directory and permissions for the log file. See the FAQ entry on this for details.
This indicates that you have installed version 0.5.x (or later) of SQLAlchemy. This has made an API change which is incompatible with JCR.
Resolve this by changing the version of SQLAlchemy you installed:
# easy_install SQLAlchemy==0.4.8
NOTE: This issue is resolved in JCR 0.6.3, which restricts the acceptable versions of SQLAlchemy.
Once JCR is running, you'll need to:
- Log in as admin with the password password0
- Change the admin password (!)
- Use the Maintenance | Users page to add users
- Use the Maintenance | Repositories page to add any Subversion repositories you need. See the documentation for the Admin role for more information.
Upgrading JCR should be relatively straightforward, but there are a few manual steps to ensure that you can recover in the event of something going wrong.
Before starting, back up:
- The JCR database
- The JCR data directory (see the baseDir setting in the config file)
- Your existing JCR installation, e.g. in /opt/jcr-0.6.2
- Your existing JCR egg directory, e.g. in /usr/lib/python2.4/site-packages/jcr-0.6.2/
- Your existing config file (if it's not in the installation directory)
- If you're launching JCR as a daemon, the launch file, e.g. /etc/rc.d/init.d/jcr
Untar the new JCR tarball alongside the existing version (the directory name will always include the version number, so you won't overwrite anything).
Stop JCR
Use easy_install to upgrade JCR (as root):
# cd /opt/jcr-0.7.2 # easy_install -U jcr-0.7.2.eggGenerate a new config file (to ensure that you have any new entries in the config file). As the JCR user:
$ cd /opt/jcr-0.7.2 $ paster make-config jcr jcr.iniDiff the old and new config files, and copy across your customisations (from your previously-installed version)
Copy across any customisations you've made to scripts or HTML help pages. These will usually be in the jcr/public/assets directory under the JCR installation
Change to the directory containing the JCR config file, and, as the JCR user:
$ paster setup-app jcr.iniThis will not only check your installation, but also will prompt to upgrade the DB schema if this is required.
- Alternatively, you can do this manually using the scripts under db/upgrade/<version>. You need to check for changes in all versions between your current version and the version you're upgrading to Typically, you'll run the upgrade-jcr-<dbms>-1.sql script, followed by any other scripts present (except for the -2 script), then finish off with the upgrade-jcr-<dbms>-2.sql script. Repeat this for each version you've skipped.
Check for any changes to the bin/jcr service/daemon script. If there are any, apply any customisations you'd made to the previous version, and install it as described in Starting as a Daemon above
If there were no changes to the bin/jcr service/daemon script, i.e. you didn't have to do anything in the bullet point above, you'll just have to alter the init script to point to the new location for the config file. Again, this is documented in Starting as a Daemon
If there were any other scripts to run or changes to be made, these should be documented in the CHANGES file
Clear the contents of data/sessions and data/templates under the JCR data directory. These are cache directories maintained by Pylons, and if left intact may prevent new features from working
Restart JCR.