Install VRPipe

VRPipe is comprised of Perl modules and scripts, none of which need any compilation. In theory to 'install' it (after completing configuration) you can just include the modules directory in your PERL5LIB and the scripts directory in your PATH.

However for use in production where you might have multiple people using the same installation, and where you'll need one version that doesn't change while things are running in production, and at least one other version to meanwhile test updates to VRPipe or changes you make yourself, you need at least 2 copies of VRPipe.

There are multiple sensible ways of dealing with this; the next 2 sections give installation examples. Pick the one that best suits your needs, or combine aspects of them both. Where example command lines are given, we assume you're following the guides elsewhere on this wiki for an Amazon EC2 deployment; adjust the command lines as appropriate for your own environment (ie. change directory and file paths).

Build.PL install

If you're just one person using VRPipe, do not plan to do any development and testing of your own pipelines, and will just occasionally upgrade to the latest versions of VRPipe as they are released, you can have just 2 copies of VRPipe: the clone of the VRPipe git repository, and a 'properly' installed set of modules and scripts. Doing things this way is perhaps the easiest and most straight-forward way of installing.

1. Go to the root directory of your clone of the VRPipe git repository (where the README file is).
   cd $SRCDIR/vr-pipe/
2. Make sure that the contents of the directory reflect what you want to install. Eg. if this is your first install, make sure that you're on the master branch with git status and that you've successfully passed the test suite from this directory (part of configuration).
3. Carry out the install using the Build.PL script:
   ./Build install (to install to a certain directory add the --install_base /shared/install/directory option)
   Which will install VRPipe's Perl modules and scripts into your systems standard locations (which will typically require root permissions, unless you're using the --install_base option or something like local::lib). It will list out what files it created in which locations. It is critical that the installation location be on a shared file system readable by all nodes in your cluster. If you use the --install_base option, then you will have to ensure that /directory/you/chose/lib/perl5 is in your PERL5LIB and /directory/you/chose/bin is in your PATH. (If you're on Amazon EC2 and are using our public unconfigured VRPipe AMI, local::lib is already set up so that you don't have to anything other than run ./Build install with no options.)
4. Now when you use VRPipe on the cmdline (from any working directory) you are using the installed versions, but when you run tests with ./Build test (from your git clone) you are using the files in the git repository. This means that in the future you can update the repository with git pull to get the latest VRPipe and run tests to make sure everything still works on your system, without affecting production VRPipe that might still be running in the background. Only when the tests pass (and you've followed any advice in the IMPORTANT_NOTES file) would you then stop your production vrpipe-server and then install the latest VRPipe by following step 3 again.

The disadvantage of this method is that the Build.PL installation system is unable to uninstall things, and some updates to VRPipe might delete files, and those files might cause problems if they're still installed after you upgrade. The IMPORTANT_NOTES file should warn you about these files, and you'll have to manually find and delete them.

Environment Variable install

To avoid problems with Build.PL not being able to uninstall deleted things, and to simplify "installing" the latest VRPipe across multiple different systems, you can have a 2+ clone set up.

On a given system you have a "production" clone of the VRPipe git repository checked out on the master branch with no changes to any of the file contents. You put the modules sub-directory of that clone in your PERL5LIB environment variable, and the scripts sub-directory in your PATH environment variable. Now when you run vrpipe-* cmd lines, including starting the server, you are using this stable, tested code.

In a different directory you have another clone of the VRPipe git repository that you can use to run tests. When a new version of VRPipe is pushed, you update this clone with a git pull and test that it works (in particular by running any tests for the pipelines that you use or made yourself). Running the test suite with ./Build test uses the code in this second clone. To use this code for running tests without using the Build script, use commands like perl -I/path/to/non-production/clone/modules /path/to/non-production/clone/scripts/vrpipe-status; do not add your non-production clone path to your PERL5LIB or PATH, at least not in your shell login script. Also, do not do anything that would write to your production database: use the --deployment testing option for all vrpipe-* cmd-line scripts except for things like vrpipe-status which is read-only. This way you won't affect the running production server as you test new things.

Only once you're happy with the latest code in your second clone would you stop the production server and git pull the first clone to upgrade your production code. If you had multiple systems you could easily upgrade them all at once by having a simple shell script that ssh'd to those systems and ran git pull in each production clone directory.

After Installation

If this is your first time using VRPipe in production with a given database, you need to populate your empty database with VRPipe's schema (create all the tables):
vrpipe-db_deploy