Synapse R Client Deployment, Step by Step

Background

The Github repository for the R client has two main branches, "develop" and "master".  "Master" contains the series of released versions of the R Client, each tagged according to its version.  "Develop" is the branch for on-going development work.  It is merged into Master when a new version is released.

Builds are done using Jenkins jobs which run at http://ec2-54-245-172-65.us-west-2.compute.amazonaws.com:8080 (this will be updated with a permanent CNAME). There are jobs for (1) building the client from the Github repository, (2) deploying clients to Sage's LRAN (depot.sagebase.org) and (3) for testing versions deployed to the LRAN.

Deployment Steps

To deploy a new version of the R client to depot.sagebase.org and verify that it runs againt production Synapse:
- clone Sage-Bionetworks/rSynapseRepository
- switch to the develop branch
    git checkout develop
- set the version for the new release, by editing the "Version:" field in the DESCRIPTION file.  Also update "Date:" to be the current date and fill in "ReleaseNotes:" with a brief description of the main features or fixes which are included in the new version.  Edit inst/main/synapseClient-package.Rd, ensuring its Version and Date fields match those in the DESCRIPTION file.

-If this version of the client is incompatible with the production version of the Synapse server (i.e. if it reflects a breaking API change) then add the new client version and the production server version to the "black list", following the instructions below.

- push to Github
    git push origin develop
- go to the Jenkins dashboard (http://ec2-54-245-172-65.us-west-2.compute.amazonaws.com:8080) and verify that the "rSynapseClient-develop" job completed successfully
- merge from develop to master
    git checkout master
    git merge develop

- tag master with the latest version and push to Github
    git tag <version>

    git push origin master

    git push --tags

- go to the Jenkins dashboard (http://ec2-54-245-172-65.us-west-2.compute.amazonaws.com:8080) and verify that the "rSynapseClient-master" job completed successfully
- In Jenkins, run deploy-rSynapseClient-master, and verify that it completes successfully

- log in to Belltown/sodo and upgrade the shared version of the R client.  (You must be a member of the "sudoers" group to do this.):

# Download source package from depot.sagebase.org
# On Belltown (intel)
sudo scp depot.sagebase.org:/data/srv/www/htdocs/Foswiki/CRAN/prod/2.14/src/contrib/synapseClient_0.20-0.tar.gz .
module load R/2.14.1-intel
sudo R CMD INSTALL synapseClient_0.20-0.tar.gz -l /gluster/toolbox/R/2.14.1-intel/lib64/R/library
module unload R/2.14.1-intel
module load R/2.15.0-intel
sudo R CMD INSTALL synapseClient_0.20-0.tar.gz -l /gluster/toolbox/R/2.15.0-intel/lib64/R/library
# On sodo (amd)
module load R/2.14.1-intel
sudo R CMD INSTALL synapseClient_0.20-0.tar.gz -l /gluster/toolbox/R/2.14.1-amd/lib64/R/library
module unload R/2.14.1-amd
module load R/2.15.0-amd
sudo R CMD INSTALL synapseClient_0.20-0.tar.gz -l /gluster/toolbox/R/2.15.0-amd/lib64/R/library

Note:  The specifics will change as newer version of R are released.

How to Black List a Version

If a version of the R Client is problematic or incompatible with a version of the Synapse server, there is a mechanism to disable or "black list" that version of the client.

Log in to the platform account in aws.amazon.com.  Download the S3 file called synapseRClient in the bucket called versions.synapse.sagebase.org.  The file looks like:

{
	"client":"synapseRClient",
	"latestVersion":"0.19-0",
	"releaseNotes":"This version includes new provenance features.",
	"message":"On January 1, all clients will be required to upgrade to the latest version.",
	"blacklist":[
		{"server":"*","client":"0.0.0"},
		{"server":"1.15.0-8-ge79db7a","client":"0.10"},
		{"server":"1.14.0-1-f84egda0","client":"<0.70"},
		{"server":"1.13.0-2-vj474hdh","client":">0.10-0"},
		{"server":"1.12.0-7-ch24528f","client":"0.05"},
		{"server":"1.12.0-7-ch24528f","client":"0.19-0"}
	]
}

The "black list" is a list of client/server pairs, where the server may be a specific version or a wildcard ("*") and the client may be a specific version or may be all versions before (inclusive/exclusive) or after (inclusive/exclusive) a given version.  To get the version of a server, use the repository services "/version" service e.g:

curl http://repo-prod.prod.sagebase.org/repo/v1/version

{"version":"1.15.0-8-ge79db7a"}

Enter a new black list record for the client version (or version range) and server version (or "*"), then upload the file to S3.

Verify that the file has been modified correctly:  Run the integration test suite in Jenkins, as described above.  This will exercise the black list, ensuring correctness.

References

R documentation

bash

Jenkins