3. Installation

3.1. Installing Ensemble Toolkit

3.1.1. Installing Ensemble Toolkit using virtualenv

To install the Ensemble Toolkit, we need to create a virtual environment. Open a terminal and run:

virtualenv $HOME/ve-entk -p python3.7
  • -p params indicates which python version you use, python3.6+ is required
  • A legacy python2 installation is available with the 0.72.1 version. Hot fixes will be provided until Jul 2020. Read more at the troubleshooting

Activate virtualenv by:

source $HOME/ve-entk/bin/activate

Note

Activated env name is indicated in the prompt like: (ve-entk) username@two:~$

Deactivate the virtualenv, if you want to disengage. Your python won’t recognize EnTK after deactivation. To deactivate, run:

deactivate

It is suggested to use the released version of EnTK which you can install by executing the following command in your virtualenv:

pip install radical.entk

To install a specific branch of EnTK, e.g., devel instead of using pip installation, you will need to clone the repository and checkout the branch. You can do so using the following commands:

git clone https://github.com/radical-cybertools/radical.entk.git
cd radical.entk
git checkout <branch-name>
pip install .

You can check the version of Ensemble Toolkit with the `radical-stack` command-line tool. The currently installed version should be printed.

radical-stack

  python               : 3.7.4
  pythonpath           :
  virtualenv           : /home/username/ve-entk

  radical.entk         : 1.0.0
  radical.pilot        : 1.0.0
  radical.saga         : 1.0.0
  radical.utils        : 1.0.0

3.1.2. Installing Ensemble Toolkit using Anaconda/Conda

To install the Ensemble Toolkit, we need to create a conda environment. Open a terminal and run (assuming you have PATH to point to conda):

conda create -n conda-entk python=3.7 -y
conda activate conda-entk

It is suggested to use the released version of EnTK which you can install by executing the following command in your conda env:

conda install radical.entk

You can check the version of Ensemble Toolkit with the `radical-stack` command-line tool. The currently installed version should be printed.

radical-stack

  python               : 3.6.9
  pythonpath           :
  virtualenv           : /home/hrlee/venv3/entk.py36

  radical.entk         : 1.0.0
  radical.pilot        : 1.0.0
  radical.saga         : 1.0.0
  radical.utils        : 1.0.0

3.2. RabbitMQ

Ensemble Toolkit relies on RabbitMQ for message transfers. Users have three choices: (1) self-deploying and using a local RabbiMQ server; (2) self-deploying and using a remote RabbitMQ server that is accessible from the target HPC machine; (3) use a local or remote RabbitMQ server provided by the HPC organization or by an external partner. Note that most HPC infrastructures forbid executing servers on their login nodes. If you have no other option, please open an issue on the `EnTK GitHub repository <https://github.com/radical-cybertools/radical.entk/issues>`_and we will provide you with a testing account on our RabbitMQ server.

In case, installation instructions can be found at <https://www.rabbitmq.com/download.html>. At the end of the installation, do not forget to run `rabbitmq-server` to start the server.

The following configuration defines a default server and port number to communicate. Note that remote RabbitMQ servers may require username and password. If you are using one of the RADICAL servers, username and password are mandatory.

export RMQ_HOSTNAME={IP ADDRESS};
export RMQ_PORT={PORT NUMBER};
export RMQ_USERNAME={USERNAME};
export RMQ_PASSWORD={PASSWORD};

Note

{} sections need to be replaced with actual values, and EnTK administrators are able to provide these information.

3.2.1. RMQ Account

Open a new ticket asking a new RMQ account: https://github.com/radical-cybertools/radical.entk/issues

3.3. Preparing the Environment

Ensemble Toolkit uses RADICAL Pilot as the runtime system. RADICAL Pilot can access HPC clusters remotely via SSH and GSISSH, but it requires (a) a MongoDB server and (b) a properly set-up passwordless SSH/GSISSH environment.

3.3.1. Setup passwordless SSH Access to HPC resources

In order to create a passwordless access to another machine, you need to create a RSA key on your local machine and paste the public key into the authorizes_users list on the remote machine.

This is a recommended tutorial to create password ssh access.

An easy way to setup SSH access to multiple remote machines is to create a file ~/.ssh/config. Suppose the url used to access a specific machine is foo@machine.example.com. You can create an entry in this config file as follows:

# contents of $HOME/.ssh/config
Host machine1
        HostName machine.example.com
        User foo

Now you can login to the machine by ssh machine1.

Source: http://nerderati.com/2011/03/17/simplify-your-life-with-an-ssh-config-file/

3.3.2. Setup GSISSH Access to HPC resources

Setting up GSISSH access to a machine is a bit more complicated. We have documented the steps to setup GSISSH on Ubuntu (tested for trusty and xenial) and Mac. Simply execute all the commands, see comments for details.

The above links document the overall procedure and how to get certificates to access XSEDE machines. Depending on the machine you want to access, you will have to get the certificates from the corresponding locations. In most cases, this information is available in their user guide.

3.4. Troubleshooting

Missing virtualenv

This should return the version of the RCT installation, e.g., 1.0.0.

If virtualenv is not installed on your system, you can try the following.

wget --no-check-certificate https://pypi.python.org/packages/source/v/virtualenv/virtualenv-16.7.9.tar.gz
tar xzf virtualenv-16.7.9.tar.gz

python virtualenv-16.7.9/virtualenv.py $HOME/ve-entk -p python3.7
source $HOME/ve-entk/bin/activate

Python 2 legacy installation

As of January 1, 2020, Python 2 support is terminated by the Python Software Foundation but the previous release of EnTK i.e. 0.72.1 allows to use Python 2.7. PyPI installation with virtualenv is:

virtualenv $HOME/ve-entk-py2 -p python2.7
source $HOME/ve-entk-py2/bin/activate
pip install radical.entk==0.72.1

`radical-stack` confirms the versions of the radical cybertools:

$ radical-stack

  python               : 2.7.17
  pythonpath           :
  virtualenv           : /home/username/ve-entk-py2

  radical.entk         : 0.72.1
  radical.pilot        : 0.73.1
  radical.saga         : 0.72.1
  radical.utils        : 0.72.0