Installation guide

The installation procedure is detailed below for Linux (Ubuntu and RedHat). Installation on Mac OSX is highly similar but not specifically detailed in this document. PiranaJS on Windows servers might be possible with some modifications but is untested and will not be officially supported. The installation procedure may take about 30 minutes when done manually (assuming you already have NONMEM and PsN installed), but can also easily be scripted using tools like Ansible, Chef, Vagrant, etc.

Git

To get the latest versions of PiranaJS, APIrana and the Pirana modules you will need to install Git. On Ubuntu this is done as follows (if it isn't already installed):

sudo apt-get install git-core

and on RedHat:

sudo yum install git

PAM / expect

PAM and expect, libraries for authentication:

On Ubuntu:

sudo apt-get install libpam0g-dev expect

and on RedHat:

sudo yum install pam-devel tcl expect

Typing expect on the command-line should now give a shell. Installing from source can be done from here: http://sourceforge.net/projects/expect/files/Expect/5.45/

NONMEM and PsN

The installation procedure for NONMEM and PsN is not detailed here since installation guides are available from the respective developers, at ftp://nonmem.iconplc.com/Public/nonmem730 and http://psn.sourceforge.net.

Node.js

If running Ubuntu, you can install this webserver framework easiest using aptitude:

sudo apt-get install nodejs

and to update to the latest version:

sudo apt-get update
sudo apt-get install -y python-software-properties python g++ make
sudo add-apt-repository -y ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs

On RedHat use the following to install NodeJS:

curl -sL https://rpm.nodesource.com/setup | sudo bash -
sudo yum install -y nodejs
sudo yum install gcc-c++ make

If you are not on Ubuntu or RedHat, binaries for other Linux distributions are available, check e.g. here for more information: https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager. Alternatively, you can install from source:

sudo apt-get install python g++ make checkinstall
mkdir ~/src && cd $_
wget -N http://nodejs.org/dist/node-latest.tar.gz
tar xzvf node-latest.tar.gz && cd node-v*
# (remove the "v" in front of the version number in the dialog)
./configure
checkinstall
sudo dpkg -i node_*

After installation you should be able to run node from the command line:

$ node
> 1+1;
2
> (^C 2x quit)

To allow running PiranaJS as a daemon, install the module forever as a global module:

sudo npm install -g forever

The remaining part of this manual is exactly the same for Ubuntu and RedHat.

Perl modules

A few Perl modules need to be installed on the server. Run the following commands (some modules may already be installed): (Select [yes] if any questions are asked during the configuration of CPAN):

On both Ubuntu and RedHat run:

sudo cpan -i HTTP::Date
sudo cpan -i DBI
sudo cpan -i DBD::SQLite
sudo cpan -i Text::Diff
sudo cpan -i Text::Diff::HTML
sudo cpan -i HTTP::Lite
sudo cpan -i Archive::Zip
sudo cpan -i Image::Size
sudo cpan -i JSON::XS
sudo cpan -i XML::TreePP
sudo cpan -i Text::Table
sudo cpan -i File::Copy::Recursive

APIrana and Pirana modules/scripts

APIrana, the Pirana modules, and the Pirana R scripts form the basis of the original Pirana software and are re-used in PiranaJS. All components are released under an open source license (MIT) and can be use as stand-alone as well. Currently, development versions are available from GitHub, stable versions will be released later through our website.

You should decide now where you want to install Pirana, e.g. under /opt would be common place to put it. Although the folder structure proposed below can be altered, it is advised to have a parent folder (e.g. /opt/pirana) under which the different parts and PiranaJS will be installed. E.g.:

cd /opt
sudo mkdir pirana
cd pirana
sudo git clone https://github.com/ronkeizer/apirana.git
sudo git clone https://github.com/ronkeizer/pirana_modules.git
sudo git clone https://github.com/ronkeizer/pirana_scripts.git

You should now have three folders under /opt/pirana. Next, the API to Pirana functionality (APIrana) should be configured to your system. Run the following commands (of course with the appropriate folder names):

sudo /opt/pirana/apirana/apirana -set_pirana_dir=/opt/pirana

Check if APIrana works correctly by running e.g.:

cd apirana
./apirana -psn_nm_versions

This should give a listing of NONMEM versions available in PsN (assuming PsN is installed correctly). If you like you can create a symbolic link from /usr/bin to this file so apirana is more easily available from the command line:

ln -s /opt/pirana/apirana/apirana /usr/bin/apirana

R and ggplot2

R and the plotting library ggplot2 need to be installed to be able to make plots and use the DataInspector in PiranaJS. Note that PiranaJS uses the Rscript command in /usr/bin to run R scripts.

PiranaJS installation

Stable versions are released through our website. The latest stable version is always available for download here. The following would install PiranaJS in your main folder:

cd /opt/pirana
wget https://s3-us-west-1.amazonaws.com/pirana-releases/piranajs/
  current/piranajs_current_stable.zip
unzip piranajs_current_stable.zip

Development versions: The source repository for PiranaJS is hosted on BitBucket instead of GitHub. If you want to keep up-to-date with development versions, please obtain a a BitBucket login and request access rights to this repository (mail me at [email protected] for more details).

After cloning or copying the files, a few external NodeJS modules need to be installed as well. They are specified in the file package.json and can all be installed automatically in one go using npm:

sudo npm install

PiranaJS configuration

After unzipping the downloaded file (or cloning from BitBucket), open the file piranajs.ini in the piranajs folder, e.g. using:

cd piranajs
nano piranajs.json

In this JSON file, set the folders for the necessary components of the PiranaJS system:

{
    "folders": {
        "pirana": "/opt/pirana",                        # main folder
        "piranajs": "/opt/pirana/piranajs",             # PiranaJS folder
        "pirana_scripts": "/opt/pirana/pirana_scripts"  # Scripts folder
    },
    "commands": {
        "apirana": "perl /opt/pirana/apirana/apirana"   # APIrana
    },
    "custom": {
      "user_r_libs": "/data/R/libs",
      "user_r_scripts": "/data/R/scripts"
    }
}

The user_r_libs and user_r_scripts folder are the locations where user can respectively install custom R libraries, and save custom R scripts, leave empty if not relevant. If the folders don't exist yet, PiranaJS will try to create them. User-installed R libraries and R scripts are useful when users do not have rights to install new R libraries/scripts on the system, and their home folder is non-persistent (e.g. on cloud systems).

See appendix I for more detailed information about the configuration file.

Note: make sure not to mess up the JSON format of this file, and not to make any comments in the file, since PiranaJS will not be able to read the configuration and the server will not start.

MPI: multi-threaded NONMEM

NONMEM 7+ can be run multi-threaded using the message passing interface (MPI). PiranaJS can use this functionality (through PsN) by auto-generating the required parafiles. You might have to adjust a few settings in PiranaJS though. Have a look in piranajs.json in the mpi section:

"mpi": {
  "presets": {
    "mpi 2 cores": ["-parafile=<template>", "-nmqual", "-run_on_sge",
      "-sge_prepend_flags='-pe orte 3 -V'"],
    "mpi 4 cores": ["-parafile=<template>", "-nmqual", "-run_on_sge",
      "-sge_prepend_flags='-pe orte 5 -V'"],
    "mpi 6 cores": ["-parafile=<template>", "-nmqual", "-run_on_sge",
      "-sge_prepend_flags='-pe orte 7 -V'"],
    "mpi 8 cores": ["-parafile=<template>", "-nmqual", "-run_on_sge",
      "-sge_prepend_flags='-pe orte 9 -V'"],
    "mpi 12 cores": ["-parafile=<template>", "-nmqual", "-run_on_sge",
      "-sge_prepend_flags='-pe orte 13 -V'"],
    "mpi 16 cores": ["-parafile=<template>", "-nmqual", "-run_on_sge",
      "-sge_prepend_flags='-pe orte 17 -V'"]
  },
  "parafile_template": {
    "template": "templates/parafile1.pnm"
  }
},

The above JSON code specifies the parallelization options that will be available to the PiranaJS user in the PsN execute dialog. The arguments listed under the various presets are all added to the execute command, in combination with the -nodes=# argument. You should adjust these arguments to match your system. The default arguments shown above are appropriate when you want to run NONMEM using MPI and distribute the computations using the Grid Engine. E.g. if you use a different job scheduler, such as SLURM or Torque, you will have to use -run_on_slurm or -run_on_torque, as well as any required flags for these tools. If you do not have a job scheduler installed, or do not want to use the scheduler for MPI runs, the following suffices:

"mpi": {
  "presets": {
    "mpi": ["-parafile=<template>"]
  },
  "parafile_template": {
    "template": "templates/parafile1.pnm"
  }
},

PiranaJS will create a copy of the template parafile specified in piranajs.json. The default template is just a vanilla NONMEM parafile template, which uses the most common parallelization settings. This file can be edited for more fine-grained control over the parallelization (see NONMEM manual for more details).

Security & user authentication

PiranaJS allows users to log in using their server credentials, i.e. the same login and password the user would use to log in over ssh (or into RStudio Server).

Furthermore, to be able to run commands as a specific user, e.g. execute run1.mod, PiranaJS needs to have sufficient rights on the system to run commands as the logged-in user. Running PiranaJS as root user is a bad idea as your system will be vulnerable to attacks. The appropriate approach is to create a new dedicated user for PiranaJS, and grant this user the rights to run commands as different users, except as root. This can be done both manually or scripted (see below). When doing this manually, first:

useradd piranajs
passwd piranajs

To make sure the user is the 'owner' of the complete Pirana folder:

sudo chown -R piranajs .

Then, to allow the new piranajs user to run commands as different users, edit the sudoers file:

sudo visudo

and add the following line:

piranajs ALL=(ALL,!root) NOPASSWD:ALL

The above can also be accomplished using the following script:

sudo cp /etc/sudoers ./sudoers.new
sudo chmod 777 ./sudoers.new
sudo echo 'piranajs ALL=(ALL,!root) NOPASSWD:ALL' >> ./sudoers.new
sudo chmod 400 ./sudoers.new
sudo cp ./sudoers.new /etc/sudoers
sudo rm ./sudoers.new

If you don't want PiranaJS to be able to run as all users on your system, you can instead list the allowed and non-allowed users in the sudoers file, or define groups. This is beyond the scope of this installation guide, though. Please refer to the Linux sudoers manual page for more information.

SSL authentication

PiranaJS supports secure sessions over https as well as over regular http (which is default). Connections over https use SSL encryption and allow encryption of all traffic between the client and the server, as well as authentication of the host to which the user is connected. To enable this, in the piranajs.json file set use_https to true, and possibly update the port set for http and https. All traffic will then be redirected to the secure port. To be able to support HTTPS connections, you will have to point to your domain's SSL private key and certificate. A dummy key and certificate are supplied with PiranaJS, but these are intended for testing purposes. Using these dummies, the PiranaJS sessions will still be encrypted, however host verification will fail and the certificate will be shown in the browser as 'untrusted'. Depending on your browser and settings, it might even block access to PiranaJS altogether.

Starting the PiranaJS server

If all of the above has been finished successfully, start a shell for the new user and start the PiranaJS server from the command line:

su piranajs
cd /opt/pirana/piranajs
node app

To output debug information on the command line, start the server with:

DEBUG=nodejs node app

Starting the PiranaJS server directly calling node is appropriate for testing purposes only: once you log out of the ssh-session to the server (or when an unexpected error occurs within PiranaJS), the PiranaJS server will stop. To run the server as a persistent daemon with automatic restart, use e.g. forever or pm2 instead:

forever start app.js

PiranaJS will then be started in the background, and will automatically restart should it crash. You can now safely log out of the server. Running instances can be checked using:

forever list

and daemons can be stopped using:

forever stop <uid>

Other commands include:

forever restartall
forever stopall

If all went well, you can now access Pirana from your browser, e.g. go to the following URL:

localhost:8000/

Of course if the server is not local, you should put the URL or IP address of the server instead, e.g.:

http://<yourserver.net>:8000/

Tip: Make sure that the port you choose for PiranaJS is open (default is 8000, but can be customized in piranajs.json). E.g. on Amazon EC2 you will need to go to 'Security groups' and define a TCP rule for port 8000.

Tip: If you want to integrate the PiranaJS interface inside the RStudio (Server) interface, you can run the following command in the R console in RStudio Server:

viewer("http://localhost:8000")

At current, there is no direct interaction possible between PiranaJS and RStudio Server, but this may be possible in the future if RStudio releases an API.

Starting PiranaJS automatically

Starting PiranaJS manually using forever or pm2 is fine on a server that is continuously on, since you only have to do it once. However, if you intend to run PiranaJS on on-demand cloud instances, it is more convenient to install it as a service, so that it gets reloaded when the server restarts. There are many ways to do this, depending on the Linux distribution and personal preferences. An example of an easy way to do this (using pm2 rather than forever) is as follows:

sudo npm install -g pm2
sudo env PATH=$PATH:/usr/local/bin pm2 startup -u piranajs

You should see output like:

Adding system startup for /etc/init.d/pm2-init.sh ...
/etc/rc0.d/K20pm2-init.sh -> ../init.d/pm2-init.sh
/etc/rc1.d/K20pm2-init.sh -> ../init.d/pm2-init.sh
... etc
[PM2] Done.

Now PM2 is installed as a service, and each time you (re)start the server all NodeJS application running through PM2 are re-started. So to make sure PiranaJS gets reloaded, you'll have to start it manually once:

pm2 start app.js

You can then safely reboot, and PiranaJS will restart once linux is booted up.