Installing software

The application must run on Linux. Specifically, Hazel runs Linux CentOS 7.9 (use cat /etc/centos-release to check current release), which also is usually compatible with RHEL. If an application says "Windows only", or is only supported on a different flavor of Linux (e.g. Ubuntu), it cannot be installed on Hazel. Check out the VCL or contact VCL support for using applications that require a different operating system.

To find out the OS requirements for an application, look on the website under Download, "Buy it", Specs, or Install/Compiling documentation.

When Singularity is fully deployed on the cluster, users may be able to run applications that require root to install, or that only run on Ubuntu, etc.
IT staff from different departments:, please contact HPC if you are willing to assist with creating Singularity containers for your users.

There are generally three resolutions to this issue: 1) The program may be installed by specifying the proper installation directory, 2) The program may be installed 'from source' rather than via package manager, or 3) The program actually needs to be installed as root and therefore cannot be installed.

1) Generally, the basic install instructions for an application automatically try to install to a directory that only has root write access, such as /usr/bin. The solution is to specify a different install path, which should generally be in a space for user maintained software in /usr/local/usrapps/$GROUP/$USER/[packagename]. It is most commonly done in a configure step by adding --prefix=[path to installation location].

2)Many applications recommend installing an application and/or all the necessary dependencies via a package manager, e.g. sudo yum install, etc. For these, look for instructions on How to install from source. Package managers greatly simplify installations, but they are rarely necessary.

3)There are some applications that need to be installed system wide as root to function properly. These may not be installed on the cluster. Check out the VCL or contact VCL support to install these applications. Hazel also has basic support for running containers. Users may run working Singularity images, or Docker images that may convert to a Singularity image, in the sif queue. There are not enough resources (i.e. HPC staff) to install or debug containers at this time.

Before buying a software licence with the intention of running the application on the cluster, check whether or not it can be successfully installed and properly run on the cluster, but also check the licensing requirements. Some licences are system wide, but others require a license for every node that might run it - in the case of Hazel, that can be over 900 licences needed. Contact HPC Staff or NCSU Software Licensing Management for more information.

Before spending a lot of time doing a complicated software install, and before buying software licenses, check the requirements for running especially if the application requires a GUI. While GUI applications may be run on the HPC, rendering performance is often poor unless it is run directly from the HPC-VCL. HPC-VCL images are not as powerful as the compute nodes on the cluster, and by default they have 16GB of RAM and a limited number of cores. Contact VCL for information about the possibility of requesting a more powerful image.

Space for user maintained executables

The directory /usr/local/usrapps provides space for user installed and maintained applications.
A project may request a directory in which all group members may install software.
All new /usrapps directories will be named for the project group unless otherwise requested.
Directories in /usr/local/usrapps may not be used for data or as a working space from which to execute jobs. A compute node cannot write to /usr/local/usrapps. Globus and HPC-VCL cannot write to this space either.
Applications must be maintained/patched to minimize potential security vulnerabilities.
Access should be managed via Linux group permissions to comply with license restrictions.
Applications that require root access to install are not permitted.

The Project PI, or a group member with the Project PI cc'ed, should submit a request via email to HPC Support including the following information:
• Name of HPC project that will be responsible for the application
• The following statement: "The HPC group [mygroup] certifies that we will only install appropriately licensed applications on the HPC Linux cluster - e.g., applications where the license is fully open source with no applicable restrictions, applications for which NCSU has approved a clickwrap, or applications with licences purchased by our group. For licenses purchased by our group, we will maintain proper file and directory permissions to comply with the licence. The group will maintain software by installing security patches or upgrades when necessary."
A directory will be created with group read/write access for the requesting project. The project group will be responsible for installing and maintaining the application. Please contact HPC staff with any questions about licensing when installing software.

Where to install?

A space in /usrapps is by default writable by everyone in the project, so all members have permissions to write directly to the /usrapps/$GROUP space. This leads to confusion and potential permissions problems. Users should create their own space within the group directory. Each user should make their own directory to install software and adjust permissions as necessary.

mkdir /usr/local/usrapps/$GROUP/$USER

How to install?

• Learning Linux
• Setting environment variables: PATH, libraries, and modules
• Compilers and tips on compiling

To get the software, download from trusted websites to Hazel.

• Use wget. Instead of clicking to download a tar file, then scp-ing to Hazel, right click on the link and Copy Link Location, e.g. https:some-domain/mysoftware/latest.tar.gz. Then on Hazel, do

  wget https:some-domain/mysoftware/latest.tar.gz
  tar zxvf latest.tar.gz
  

• Use git. Go to the GitHub repo for the code, click the Clone or download button, and copy the URL. Then, on Hazel, do

  git clone https:github-path/mysoftware/latest.git
  

  That will download the source to a directory called latest.

Where to install? For software to be used regularly by a research group, install to the group's space in /usr/local/usrapps. Software that is used temporarily for testing purposes only might more appropriately be installed in the scratch directory at the discretion of the user.

Where to install from? Usually, installations should be done from a login node. Note that compute nodes cannot download source code and packages from the internet, and neither compute nodes nor VCL nodes may write to /usr/local/usrapps. When compiling a software using compiler options to optimize for architecture, the compilation might be done on a node with the targeted architecture, with the understanding that it consequently may not run on any nodes not having the instruction set(ISA) specified. See Advanced Compiler Options for more details on creating binaries optimized for multiple ISAs.

./configure
The configuring is done with a script, usually called configure or configure.sh.

cd [path to source directory]
./configure --prefix=[path to installation location]
make
make check  #or 'make test'
make install

The configure script checks the environment and creates a makefile accordingly; therefore, the environment must be set so that the necessary dependencies are found when running configure. For example, if the application requires the Intel compiler and Intel MPI, do

module load PrgEnv-intel
./configure --prefix=[path to installation location]
make
make check  #or 'make test'
make install

cmake
The configuring is done by CMake.

mkdir build
cd build
module load cmake
cmake [path to source directory]
make
make check #or 'make test'
make install

ccmake
The program ccmake is similar to cmake, except instead of specifying any options through the command line (e.g. --prefix), they are set in a GUI. The GUI is text on the screen, not a pop-up window. Using ccmake is often very useful when a package has many dependencies, because the paths to the include files (header files) may not be set automatically by loading modules, in which case they will need to be specified explicitly.

mkdir build
cd build
module load cmake
ccmake [path to source directory]
[Use the GUI to set the install prefix and other environment variables.  Choose the options listed at the bottom, typically configure, then generate, then exit.]
make
make check #or 'make test'
make install

chmod u+x script.sh