Installation

There are three ways to install ElastiCluster:

  • Use the ElastiCluster Docker image: this is the quickest and easiest option if you just want to use ElastiCluster. See section Quickstart for instructions.

  • Run ElastiCluster from the Python source code. This is the recommended option if you want to develop or customize ElastiCluster. See section Installing development code from GitHub for instructions.

    Warning

    As of April 2020, Python 2.7 has seen its final maintenance release and support for Python 2.x is being phased out of major libraries. ElastiCluster’s own code is still compatible with Python 2, but libraries it depends upon will increasingly not be. Therefore, installation instructions assume you are using Python 3; if this is not the case, please see ask for help on the mailing-list.

  • Install the elasticluster Python package from PyPI. See section Installing released code from PyPI for instructions.

    Warning

    The code currently available on PyPI (ElastiCluster 1.2) is quite old and is lacking a number of important fixes and updates. Until ElastiCluster 1.3 is released, we suggest that you install from GitHub instead (see section Installing development code from GitHub below)

Quickstart

To install ElastiCluster over Docker: (1) download the elasticluster.sh script script into a file elasticluster.sh, then (2) type this at your terminal prompt:

chmod +x elasticluster.sh

That’s it! You can now check that ElastiCluster is ready by running:

elasticluster.sh --help

The first time it is run, the elasticluster.sh script will check if Docker is installed, and ask for permission to install it if Docker is not found. Follow the on-screen instructions; see section Getting Help if you’re in trouble.

You can also rename file elasticluster.sh to elasticluster, if you so like, to be consistent with the rest of the documentation.

Alternatively, you can also perform both steps at the terminal prompt:

# use this if the `wget` command is installed
wget -O elasticluster.sh https://raw.githubusercontent.com/gc3-uzh-ch/elasticluster/master/elasticluster.sh
chmod +x elasticluster.sh

# use this if the `curl` command is installed instead
curl -O https://raw.githubusercontent.com/gc3-uzh-ch/elasticluster/master/elasticluster.sh
chmod +x elasticluster.sh

Choose either one of the two methods above, depending on whether wget or curl is installed on your system (Linux systems normally have wget; MacOSX normally uses curl).

Prepare the environment for installation

Note

This section is only relevant if you are installing ElastiCluster from source code (see Installing development code from GitHub) or from the PyPI package (see Installing released code from PyPI). None of these instructions are needed when running ElastiCluster from the Docker image. (See section Quickstart for how to run ElastiCluster with Docker.)

The following sections document preliminary steps that need to be carried out in order to install ElastiCluster on a GNU/Linux or MacOSX computer.

We strongly recommend that elasticluster is installed in a python virtualenv, in order to create a controlled environment where ElastiCluster can run without conflicting with system files or Python libraries. Installing in a python virtualenv makes it also easier to uninstall or upgrade elasticluster.

Install required dependencies

Warning

As of April 2020, Python 2.7 has seen its final maintenance release and support for Python 2.x is being phased out of major libraries. ElastiCluster’s own code is still compatible with Python 2, but libraries it depends upon will increasingly not be. Therefore, the following instructions direct you to installing Python 3; if this is might be a problem on your system, please see ask for help on the mailing-list.

CentOS/RHEL

To install software prerequisites for building and running ElastiCluster, run the following commands as the root admin user:

sudo yum install gcc gcc-c++ git libffi-devel openssl-devel python3 python3-devel python3 python3-virtualenv

Debian/Ubuntu

To install software prerequisites for building and running ElastiCluster, run the following commands (omit the sudo word if running as the root admin user):

sudo apt-get install gcc g++ git libc6-dev libffi-dev libssl-dev python3 python3-dev virtualenv

MacOSX

Warning

Installation and testing of ElastiCluster on MacOSX is not currently part of the development or the release cycle. So these notes could be severely out of date. Please report issues and seek for solutions on the ElastiCluster mailing-list.

In order to install ElastiCluster, you need to install Xcode. It’s free and you can install it directly from the AppStore.

Create a Python “virtualenv”

Assuming you already have virtualenv installed on your machine (see section Install required dependencies if not), create a virtualenv and activate one with the following commands:

virtualenv --python python3 elasticluster
. elasticluster/bin/activate

Now upgrade the pip command to the latest version (to ensure that it can correctly resolve the many dependencies of the ElastiCluster code):

pip3 install --upgrade 'pip>=9.0.0'

Installing released code from PyPI

Warning

The code currently available on PyPI (ElastiCluster 1.2) is quite old and is lacking a number of important fixes and updates. Until ElastiCluster 1.3 is released, we suggest that you install from GitHub instead (see section Installing development code from GitHub below)

Please follow the instructions in section Install required dependencies before proceeding.

Please follow the instructions in section Prepare the environment for installation before proceeding. The rest of this section assumes that you have created and activated a virtualenv in directory elasticluster.

It’s quite easy to install elasticluster using pip; the command below is all you need to install elasticluster on your system:

pip3 install elasticluster

If you run into any problems, please have a look at the Troubleshooting section; the mailing-list is also a good place to get help.

Installing development code from GitHub

The source code of ElastiCluster is on GitHub, if you want to test the latest development version you can clone the GitHub elasticluster repository.

Please follow the instructions in section Prepare the environment for installation before proceeding. The rest of this section assumes that you have created and activated a virtualenv in directory elasticluster.

Then you have to download the software. We suggest you to download it within the created virtualenv:

cd elasticluster
git clone https://github.com/elasticluster/elasticluster.git src
cd src
pip install -e .

Now the elasticluster command should be available in your current environment.

If you run into any problems, please have a look at the Troubleshooting section; the mailing-list is also a good place to get help.

Building documentation files

ElastiCluster documentation is available in the docs/ directory, in reStructuredText-formatted plain text files.

You can additionally build HTML or PDF documentation; in the directory in the ElastiCluster virtualenv, type:

cd docs
make html

To build PDF documentation, use make latexpdf instead.

Note that building documentation files requires that the Python module Sphinx (click on the link for install instructions) is available in the same virtual environment where ElastiCluster is installed.

Getting help

In case you have trouble running the installation script, please send an email to elasticluster@googlegroups.com or post a message on the web forum https://groups.google.com/forum/#!forum/elasticluster. Include the full output of the script in your email, in order to help us to identify the problem.