There are several things that you need to do before you can run Rephlux:
Hopefully set up shouldn't take more than about an hour...
The top level script, rephlux.php, contains a line setting the memory limit for the application to 128M. You may need to adjust this setting to an appropriate value for your setup.
You need to create a test script that runs from the command line.
Your CLI script should return a zero exit code on success and a non-zero exit code on test fails.
A CLI runner for SimpleTest (cli_reporter.php) is provided in the var/tests/lib directory. This reporter produces easier-to-parse output than the default SimpleTest CLI output reporter.
The provided CLI reporter produces the failure output expected (and parsed) by the Rephlux_RephluxCLI class (lib/testers/rephlux_rephluxcli.php). This is the only output format that is currently supported.
Something to watch out for is the path that your tests expect to use to find your SimpleTest installation (an issue unless you have checked in a copy of SimpleTest with your project) - you may be able to deal with this issue with a pre-test script.
Rephlux currently needs 6(!) ini files to be customised. But they are all fairly small (I'll probably fold these files back into one config file at some stage). Examples of each are in the etc/ directory of the distribution.
All of the your ini files should be prepended with your project name instead of rephlux, so, for project 'time', rephlux-fails-rss.ini becomes time-fails-rss.ini etc.
etc/rephlux.ini
repository: your cvs repository, as supplied with the -d flag to cvs.
test-script: the path (and flags) from the root of your source to your test script.
export-source: whether Rephlux should export a clean copy of your source after your test scripts pass. This exported copy can be used in post-test scripts to eg. create a distribution tarball. The exported source will be removed before Rephlux exits.
etc/rephlux-pre-test.ini, etc/rephlux-post-test-ini, etc/rephlux-finalize.ini
These files allow you to set up arbitrary script to be run at the indicated times during rephlux execution (finalize scripts always run, post-test only if tests succeeded).
In each file scripts are specified on separate lines:
alias (used in reporting) = "script path and flags"
These scripts have environment variables available; for pre-test scripts:
$PHP_REPHLUX_SOURCE_ROOT = the path to your checked out source
$PHP_REPHLUX_ROOT = the path to the rephlux root dir
and for post-test and finalize scripts:
$PHP_REPHLUX_SOURCE_ROOT = the path to your checked out source
$PHP_REPHLUX_ROOT = the path to the rephlux root dir
$PHP_REPHLUX_EXPORTED_ROOT = the path to an exported (ie. clean) copy of your source code
$PHP_REPHLUX_LOGNAME = the timestamped name assigned to persistent logfiles
etc/rephlux-fails-rss.ini, etc/rephlux-revisions-rss.ini
These allow modification to the RSS reporting output.
$ cd <your rephlux directory> $ ./rephlux
(you may need to change the path to the php executable)
You should see some debugging output. If the run is successful you will find an RSS revision log under var/log/revisions.xml (duplicated as a datestamped version under var/log/revisions).
If your tests failed a fails log should be generated at var/log/fails.xml (and a persistent datestamped version under var/log/fails/).
These RSS logs should be viewable in modern browsers, or from your aggregator.
Local repositories should present no problem.
Anonymous :pserver: access should be suitable for Rephlux if available on your repository. You can create a source distribution by exporting from CVS using the date that the tests were run.
Authenticated access to pserver is supported by using the :pserver:user:password@/repository construct.
:ext: access is unfortunately a bit more gnarly. The cron job running Rephlux needs to be able to access the CVS repository via ssh. You will need a user account on the machine that provides CVS, and to set up a passwordless ssh-key pair with ssh-keygen. You will also need to ensure that your cron job knows about your ssh-key pair - this can be achieved with the keychain program.
Here's an example for setting up a keypair with a private key rephlux_dsa, and a public key rephlux_dsa.pub:
$ ssh-keygen -t dsa Generating public/private dsa key pair. Enter file in which to save the key (/home/jon/.ssh/id_dsa): ./rephlux_dsa Enter passphrase (empty for no passphrase): <enter, no password> Enter same passphrase again: Your identification has been saved in ./rephlux_dsa. Your public key has been saved in ./rephlux_dsa.pub. The key fingerprint is: <fingerprint details>
The key-pair should be saved to the $HOME/.ssh directory of the user that will run the cron job. The private key should be set to read only access:
$ chmod 0400 rephlux_dsa
You need to add your new public key to the list of authorized_keys on the CVS hosting machine.
Be careful not to overwrite any existing authorized keys!
$ scp rephlux_dsa.pub user@cvs-host:~/ $ ssh user@cvs-host ... (on cvs-host) $ cat ~/rephlux_dsa.pub >> ./.ssh/authorized_keys $ rm ~/rephlux_dsa.pub $ exit
Keychain can be used to ensure that your cron job knows about your ssh keys. For more information google 'ssh keychain', but for a quick start; after installing keychain add the following to your ~/.bash_profile
$ grep keychain ~/.bash_profile
keychain ~/.ssh/rephlux_dsa.pub
. ~/.keychain/${HOSTNAME}-sh
These two lines will start keychain and let it know about your (passwordless) key-pair.
The second line sources a file that keychain generates - this file exports some ssh details as environment variables and should be run as part of the cron job that runs Rephlux (ie. this command should appear somewhere in the script run by cron).
A quote from the SourceForge 'Guide to Generation and Posting of SSH Keys'[1]:
"Ensure that your private key has been placed only on machines over which you have direct control. Public, shared, and community machines are not suitable environments to store SSH private keys. Take action to help prevent theft of your SSH private key data. Setting a password on your SSH private key will help reduce the risks involved with private key theft."
To allow Rephlux access to your project via :ext: there are two options. Both involve use of a passwordless key-pair.
You can run Rephlux on your own machine, setting up :ext: access as above but using the SourceForge web interface[2] to upload your public key to the SourceForge CVS server.
Alternatively you could run Rephlux from your SourceForge shell account. This will require storing your private key on your SourceForge shell account. The risk is your own... If you decide to take the risk:
Follow the steps above, using your shell account on SourceForge to generate and store the key-pair. The upload the public key thru the SourceForge web interface[2]. Wait ~6 hours. Test Rephlux from your SourceForge shell account home.
EXTRA WARNING: SF has the default 8Mb memory limit in place for Php from the command line - large SimpleTest test scripts with many cases may exceed this limit. Rephlux is now setting a memory_limit of 128Mb by default (in the top level rephlux.php script). This should alleviate the problem, but if you have problems this may be the reason.
An example crontab (see example.crontab in this directory):
$ cat doc/example.crontab HOME=/home/jon/rephlux 29 22 * . /home/jon/.keychain/`hostname`-sh && $HOME/rephlux.php
This crontab will run Rephlux at 10:29 every evening. The first part of the command sources a keychain file (as described above).
$ crontab doc/example.crontab $ crontab -l HOME=/home/jon/rephlux 29 22 * . /home/jon/.keychain/`hostname`-sh && $HOME/rephlux.php
[1] SF Docs - 'Guide to Generation and Posting of SSH Keys' <https://sourceforge.net/docman/display_doc.php?docid=761&group_id=1>
[2] SF SSH Key upload interface <https://sourceforge.net/account/editsshkeys.php>