PiranaJS installation guide Ron Keizer, January 2015 Introduction PiranaJS is the web-based version of Pirana, a workbench for pharmacometricians aimed at facilitating the use of NONMEM, PsN, R/Xpose, and other software. PiranaJS needs to be installed and configured on a Linux or OSX system, along with several dependencies. Since PiranaJS runs in the browser there are no client-side dependencies other than a modern browser and a network connection. However, the user is required to have a system account on the server and the user s credentials will be requested upon login in the web application. Similar to the original Pirana software, PiranaJS is licensed under two licenses: for academic use, a Creative Commons license (Attribution-NonCommercial- NoDerivs 3.0) allows free use of the software for non-commercial use. For commercial use, proprietary software licenses are available. Please check the Pirana website (www.pirana-software.com), or contact us for more information (info@pirana-software.com). Commercial use of PiranaJS on IaaS solutions like Amazon EC2 or Google Compute Engine is restricted to use within Metworx. Requirements NONMEM PsN : Perl speaks NONMEM, a collection of tools for NONMEM Node.js: Javascript-based webserver framework APIrana: command-line based interface / API to Pirana functionality Pirana modules: library and Pirana scripts library: basic functionality for handling NONMEM/PsN/datasets/results etc. R and ggplot2 library: for plotting expect: a small linux tool to automate interaction with other command-line tools. Installation The installation procedure is detailed below for Linux, but installation on Mac OSX is highly similar. PiranaJS on Windows servers might be possible with some modifications but will not be supported. The installation procedure may take about 20-30 minutes (assuming you already have NONMEM and PsN installed), and can also easily be scripted using tools like Ansible, Chef, Vagrant, etc. 1
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 expect On Ubuntu: sudo apt-get install 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 Next, 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 If you are not on Ubuntu, 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: 2
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 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): cpan -i HTTP::Date cpan -i DBI cpan -i DBD::SQLite cpan -i Text::Diff cpan -i Text::Diff::HTML cpan -i HTTP::Lite cpan -i Archive::Zip cpan -i Image::Size cpan -i JSON::XS cpan -i XML::TreePP cpan -i Text::Table 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 3
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 The source repository for PiranaJS itself is hosted on BitBucket instead of GitHub. The easiest way of keeping up to date with development versions is to obtain a a BitBucket login and request the rights to access this repository (mail me at ron@pirana-software.com). 4
cd /opt/pirana sudo git clone https://<yourusername>@bitbucket.org/ronkeizer/piranajs.git Stable versions are released through our website. Please see there or contact the developers for a link. After cloning from BitBucket or unzipping the downloaded file, please 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", "piranajs": "/opt/pirana/piranajs", "pirana_scripts": "/opt/pirana/pirana_scripts" }, "commands": { "apirana": "perl /opt/pirana/apirana/apirana" } # main folder # PiranaJS folder # Scripts folder # APIrana Make sure not to mess up the JSON format of this file, otherwise PiranaJS will not be able to read the configuration and won t start. See below for more information about the configuration file. A few NodeJS modules need to be installed as well. They are specified in the file package.json and can all be installed automatically using: sudo npm install. 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. While this can be accomplished by running PiranaJS as root, this is generally a bad idea as your system will much more vulnerable to attacks. The recommended 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 is accomplished by first running: 5
useradd piranajs passwd 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 or, in a scriptable way: sudo cp /etc/sudoers./sudoers.new sudo echo 'piranajs ALL=(ALL,!root) NOPASSWD:ALL' >>./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. Please refer to the sudoers manual page for more information. SSL authentication PiranaJS supports secure sessions over https as well as over regular http (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. Also, you will have to point to your domain s SSL private key and certificate. A dummy key and certificate have been supplied with PiranaJS, but these are intended for testing purposes. If you use 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. Running PiranaJS Before you can start the PiranaJS server, a setup script needs to be run. This script needs to be run with root priviliges, since it will create a new user (piranajs) and group (piranajs) on your system. The script will ask you to specify a password for the new user. 6
sudo bash setup.sh Note: This setup script is linux-specific, and at current we have no version for Mac OS X. If the purpose of you installation on Mac OSX is just for local (personal) use, you can skip the creation of the new user and start the server with: node app, as there is no need to run the server as a separate user. After the setup script has finished succesfully, 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 instead: forever start app.js 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/ 7
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 (default is 8000, but can be customized in piranajs.json) is open. 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 in the RStudio (Server) interface, you can run the following command in the R console in RStudio: 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 when RStudio releases their API. Configuring PiranaJS In the file piranajs.json the following configuration options are available: folders: Set paths pirana: The parent folder for PiranaJS, APIrana, and pirana_modules piranajs: The folder for PiranaJS pirana_scripts: The folder for Pirana R scripts user_home_folder: If specified, overrides the default of PiranaJS to show the user s $HOME folder on startup (when no projects have been defined). license: Settings related to the PiranaJS license file: Path to the license file commands: Miscellaneous commands apirana: The command to invoke apirana (apirana by default) zedrem: Experimental feature. Provide support for the server-side editor Zed (http://zedapp.org). ssl: Settings for security (SSL) key: SSL key (./ssl/server_placeholder.key) cert: SSL certificate (./ssl/server_placeholder.crt) general 8
use_https: Secure mode, use HTTPS instead of HTTP. false by default. port_http: 8000 by default. port_https: 8001 by default. trust_proxy: true/false. (true by default) allow_tty: true/false. PiranaJS contains a builtin TTY simulator. At the moment this functionality is not completely secure, so it is advised to set this to false unless in development mode. ui: Settings related to the user interface sound_fx: true/false. Use sound effects to indicate successful login / run completion etc (default is true). links: Links to other apps or sites, will be shown in menubar. RStudio (default is http://localhost:8787) Note: Make sure to restart the server each time you update the configuration. Troubleshooting PiranaJS Please inform us of any problems you encounter. In the webapplication under Help you will find a link to our support system. When reporting problems, please provide a clear description (and how to reconstruct the problem), and include the following files from your server (from the PiranaJS main folder, if available): log/piranajs.log log/piranajs_stdout.log log/piranajs_stderr.log Also, if possible, run PiranJS in the Chrome browser with the Javascript Console open (Control-Alt-J / Command-Option-J) or using Firefox/Firebug and copy any errors or messages in the console into the ticket. Getting started tips At this point, a user manual for PiranaJS is not yet available. For general questions about the workflow in PiranaJS please have a look in the manual for Pirana (as much of the interface is similar for the desktop product). Until a manual will be released we will be gathering some tips on the usage of PiranaJS in this document. 9
Tips: For testing purposes, if you don t have a test set of NONMEM models available you can clone some here: https://github.com/ronkeizer/nonmem_examples.git PiranaJS has a built-in feature for uploading models or data to the cluster. Just drag the files from Finder (Mac) or File Explorer (Windows) onto the PiranaJS interface they will be uploaded. PiranaJS, like the original Pirana software, works most efficiently if you use the keyboard shortcuts (see Help link). 10