comgsi/docker

A light-weighted GSI/EnKF-focused Docker Container (comgsi/docker) is available to community users.

This is a brief guide on how to run GSI/EnKF tutorial cases using this comgsi/docker container.

-----------------------------------------------------------
1. ** Prerequisites **
-----------------------------------------------------------

   You must have the "docker" software installed on you computer.
   Please visit https://www.docker.com on to download and install docker.
   
   We don't have resources to support the installation of the "docker" sofware.
   Please seek helps from the Docker community on this issue.

   However, here we share some installation experiences on some platforms and hope they helps in some ways:

  (1). For MAC users, just download "docker" from its official website and install it.
       You will need Administrator privildage to install docker on MAC.

  (2). For Debian/Ubuntu based Linux systems (recent releases), run the following command:

      curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
      sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
      sudo apt-get update
      apt-cache policy docker-ce
      sudo apt-get install -y docker-ce

  Note1: if curl is not avaialbe, use wget instead as follows:
      wget https://download.docker.com/linux/ubuntu/gpg; cat gpg | apt-key add -

  Note2: You will need System Administrator priviledge to install docker.

  (3). For Windows users, it is highly remmended to install VirtualBox, and then setup an Ubuntu-based virtual machine
using VirtualBox. In this Ubuntu-based virtual machine, you can install docker following the above step (2).
 
       Download VirtualBox at: https://www.virtualbox.org
       Download a pre-built XUbuntu virtual machine image at: https://www.osboxes.org/xubuntu/

  Note:
   -- Per our experiences, docker running inside VirtualBox has much better performance and user experiences than running
Docker on Windows directly. 
   -- We only tested this on Windows 10.

-----------------------------------------------------------
2. ** Get and run comgsi/docker **
-----------------------------------------------------------

  (1) On you computer, create a directory for running GSI/EnKF in docker, e.g:

        mkdir GSI-Docker; cd GSI-Docker

    Be sure you have enough free space in this directory (10GB is preferred) 

  (2) Obtain the comgsi/docker image:
    
      There are two methods to get the comgsi/docker image:
       a. run the command "docker pull comgsi/docker"
         docker will download comgsi/docker from hub.docker.com automatically. 
         The comgsi/docker container is 695MB in size.
         If you download speed from hub.docker.com is too slow, consider the method b

       b. download comgsi_docker.tar.gz (262MB) from DTC website
         then "gunzip comgsi_docker.tar.gz"
         and then "docker load -i comgsi_docker.tar"

  (3) start the comgsi/docker:

   First, run the following command to generate a run script "rungsidocker":

     echo 'docker run -h GSI_Docker -v "$(pwd)":/tutorial -ti --rm comgsi/docker' > rungsidocker; chmod +x rungsidocker

   Now, you can just type "./rungsidocker" to start the comgsi/docker each time

  (4) Once the comgsi/docker is started sucessfully, you will be in the docker and see outputs similar as:

     comgsi@GSI_Docker:/tutorial$

    NOTE1: This /tutorail is a mapping of the directory under your host system where you execute the "rungsidocker" command.
     This mapping enables you to access files inside docker from your host system and your works will not disappear
     after you exit the docker.

    NOTE2: Three directories build/ case_data/ run/ will be created automatically under /tutorial.

  (5) Lauch more shells of comgsi/docker:
      This step is not required, but very helpful if you want to open two or more shells of comgsi/docker.
      
      -- open a new shell window in your host system (NOT in docker), type "docker ps". This lists all running containers.
      You will get outputs similar as follows:

 CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
f278376baef3        comgsi/docker       "/bin/bash"         12 minutes ago      Up 12 minutes                           suspicious_snyder

      -- Now you know that the comgsi/docker container ID is: f278376baef3, type:

          docker exec -it f278376baef3 bash

       and you are now in a new shell of comgsi/docker

-----------------------------------------------------------
3. ** run GSI/EnKF in comgsi/docker **
-----------------------------------------------------------

  All the following steps are done in the shell of the comgsi/docker container.

  (1) Download the GSI/EnKF release tarball from the DTC website and move it to the directory created in step 2.1:

  (2) In the docker, at the /tutorial directory, you should be able to "ls comGSIv3.7_EnKFv1.3.tar.gz" now

     tar xvfz comGSIv3.7_EnKFv1.3.tar.gz

  (2) Compile GSI/EnKF

      cd build
      cmake ../comGSIv3.7_EnKFv1.3
      make

Depends on your host computer, it takes up to 10~20 minutes to complete the compiling.

If you don't want to compile from source codes, you can skip step (2) and download pre-compiled
executables from DTC website:
  
      wget http://dtcenter.org/com-GSI/MPMC/precompiled.tar.gz
      tar xvfz precompiled.tar.gz
 
  (3) Link executables into run/

      cd ../run
      ln -sf ../build/bin/gsi.x . 
      ln -sf ../build/bin/enkf_wrf.x . 

  (4) Now you can run all tutorial cases under the run/ directory following instructions on the DTC website
      NOTE1: You can download all case data into /tutorial/case_data directory
      NOTE2: On the comgsi/docker, you can run executables in MPI mode if it is assigned multiple cores
               e.g.:   mpirun -n 2 run.case03-conv.ksh


For any questions, contact us at gsi-help@ucar.edu.


                                                    by Guoqing Ge, 2018/9/20