/HiDALGO_FabSim3_Tutorial

Primary LanguageDockerfile

[Hidalgo] FabSim3 and MUSCLE3 installation tutorial

For Ubuntu based machines

Two different approaches are provided to install pre-requirement packages and softwares in your system. In the first approach, you can install all dependencies in your local machine and then follow all instructions during the tutorial, or used the second approach which provides a docker image with pre-installed packages.

Solution 1: Install all packages and software in your local Ubuntu based PC

  • make sure you have python > 3.0 installed in your system 
     $ python --version
 Python 3.x
    If you have python3 but it is not default, you can make it default by following instruction from this link
  • Install openssh server 
     $ sudo apt-get install openssh-client openssh-server
  • Install MPi 
     $ sudo apt-get install -y openmpi-bin
  • You ONLY need to install ruamel.yaml package, others will be installed by FabSim3. To install that python package, simply type 
     $ pip3 install ruamel.yaml
  • Additionally, for parallel FLEE, you need to install mpi4py package too 
     $ pip3 install mpi4py
  • Create a folder anywhere on your local machine. Let’s name it HiDALGO_tutorial 
     $ mkdir HiDALGO_tutorial
  • Go to HiDALGO_tutorial folder and clone FabSim3 from the GitHub repository 
     $ cd HiDALGO_tutorial
 [HiDALGO_tutorial]$ git clone https://github.com/djgroen/FabSim3.git
 [HiDALGO_tutorial]$ git clone https://github.com/djgroen/flee.git
  • To install all packages automatically and configure yml files, please go to your FabSim3 directory, and type 
     [HiDALGO_tutorial]$ cd FabSim3
 [HiDALGO_tutorial/FabSim3]$ python3 configure_fabsim.py
    After installation process, the main FabSim3 directory is added in your $PYTHONPATH and $PATH environment variable. You can find these changes on your bash profile (for linux check ~/.bashrc, and for MacOS check ~/.bash_profile)
  • To make the fabsim command available in you system, please restart the shell by opening a new terminal or just re-load your bash profile by source command 
     [HiDALGO_tutorial]$ source ~/.bashrc
  • You can test the installation, by installing FabDummy plugin and test a dummy test 
     [HiDALGO_tutorial/FabSim3]$ fabsim localhost install_plugin:FabDummy
 [HiDALGO_tutorial/FabSim3]$ fabsim localhost dummy:dummy_test

Solution 2: Using pre-configured Docker image

Make sure you have Docker installed on your PC. To install it, you can follow the instruction form : https://docs.docker.com/engine/install/ubuntu

  • Create a folder anywhere on your local machine. Let’s name it HiDALGO_tutorial 
     $ mkdir HiDALGO_tutorial
  • Go to HiDALGO_tutorial folder and clone FabSim3 from the GitHub repository 
     $ cd HiDALGO_tutorial
 [HiDALGO_tutorial]$ git clone https://github.com/djgroen/FabSim3.git
 [HiDALGO_tutorial]$ git clone https://github.com/djgroen/flee.git
  • Config yml files
    • Go to HiDALGO_tutorial/FabSim3/deploy folder
    • Make a copy of machines_user_example.yml file, and name it machines_user.yml
    • Make changes in machines_user.yml by replacing the localhost entry 
       localhost:  
 	username: "your-username"
      with 
       localhost:  
 	local_results: "/FabSim3/results"
 	local_configs: "/FabSim3/config_files"
 	username: "root"
 	flee_location: "/flee"
 	home_path_template: "/FabSim3/localhost_exe"
 	run_command: "mpirun --allow-run-as-root -np $cores"
  • Go back to HiDALGO_tutorial and download the Docker image using 
     [HiDALGO_tutorial] $ docker pull ha3546/hidalgo_fabsim3_tutorial_webinar

Note: If permission is denied, use sudo docker pull ha3546/hidalgo_fabsim3_tutorial_webinar

  • Create a new file, named hidalgo_fabsim3_tutorial.sh, and fill it with 
     	#!/bin/bash
 	
 	docker run --rm \  
 	-v $PWD/flee:/flee \  
 	-v $PWD/FabSim3:/FabSim3 \  
 	-e USER=$USER -e USERID=$UID --hostname HiDALGO \  
 	-ti ha3546/hidalgo_fabsim3_tutorial_webinar
  • Make that file executable 
     [HiDALGO_tutorial] $ chmod +x hidalgo_fabsim3_tutorial.sh
  • Now, you should be able to log-in to the docker image by 
     [HiDALGO_tutorial] $ ./hidalgo_fabsim3_tutorial.sh
 [HiDALGO FabSim3 tutorial] /FabSim3 $
  • You can test the installation, by installing FabDummy plugin and test a dummy test 
     [HiDALGO FabSim3 tutorial] /FabSim3 $ fabsim localhost install_plugin:FabDummy
 [HiDALGO FabSim3 tutorial] /FabSim3 $ fabsim localhost dummy:dummy_test

For MacOSX based machines

Two different approaches are provided to install pre-requirement softwares and packages in your system. In first approach, you can install all dependencies in your local machine and then follow all instructions during the tutorial, or used the second approach which provides a docker image with pre-installed packages

Solution 1: Install all packages and software in your local MacOSX based machines

  • make sure yomakeu have python > 3.0 installed in your system 
     $ python --version
 Python 3.x
    If you have python3, but it is not default, on your system, please make it default python. For example, you can follow instructions from this link, or do a search on the internet :)
  • Enable SSH login on macOS
    • OS X comes with sshd, you only need to enable it in System Preferences, under Sharing by clicking on Remote Login:

  • Download and install MPI on your Mac : https://www.open-mpi.org/. Alternatively, you can install it with Homebrew. Once Homeebrew is installed, you only need to run the following commands and open-mpi will be installed 
     $ brew update
 $ brew install open-mpi
  • Create a folder anywhere on your local machine. Let’s name it HiDALGO_tutorial 
     $ mkdir HiDALGO_tutorial
  • You ONLY need to install ruamel.yaml package, others will be installed by FabSim3. To install that python package, simply type 
     $ pip3 install ruamel.yaml
  • Additionally, for parallel FLEE, you need to install mpi4py package too 
     $ pip3 install mpi4py
  • Create a folder anywhere on your local machine. Let’s name it HiDALGO_tutorial 
     $ mkdir HiDALGO_tutorial
  • Go to HiDALGO_tutorial folder and clone FabSim3 from the GitHub repository 
     $ cd HiDALGO_tutorial
 [HiDALGO_tutorial]$ git clone https://github.com/djgroen/FabSim3.git
 [HiDALGO_tutorial]$ git clone https://github.com/djgroen/flee.git
  • To install all packages automatically and configure yml files, please go to your FabSim3 directory, and type 
     [HiDALGO_tutorial]$ cd FabSim3
 [HiDALGO_tutorial/FabSim3]$ python3 configure_fabsim.py
    After installation process, the main FabSim3 directory is added in your $PYTHONPATH and $PATH environment variable. You can find these changes on your bash profile (for linux check ~/.bashrc, and for MacOS check ~/.bash_profile)
  • To make the fabsim command available in you system, please restart the shell by opening a new terminal or just re-load your bash profile by source command 
     [HiDALGO_tutorial]$ source ~/.bash_profile
  • You can test the installation, by installing FabDummy plugin and test a dummy test 
     [HiDALGO_tutorial/FabSim3]$ fabsim localhost install_plugin:FabDummy
 [HiDALGO_tutorial/FabSim3]$ fabsim localhost dummy:dummy_test

Solution 2: Using pre-configured Docker image

Make sure you have Docker installed on Mac machine. To install it, you can follow the institution form this website : https://docs.docker.com/docker-for-mac/install/.

For Windows based machines

The suggested approach is installing Ubuntu in a VirtualBox VM. and follow the Ubuntu based machine instructions.