INSTALL

Git is now the approved distribution and installation mechanism. 'hpc-collab.tgz' references should be skipped.

----
1. a. Create a work directory, usually $HOME/hpc-collab
   b. $ cd $HOME/hpc-collab
   If not in this directory, update bin/setpath.{c}sh with the installation root. [(7) below]

2. a. Set up initial space.
        $ mkdir hpc-collab/tarballs (if you have space for 20+Gb centos repo, ~10Gb repos tarball)
        $ mkdir /scratch/tarballs; ln -s /scratch/tarballs hpc-collab/tarballs
   This directory name is expected by the Makefile
   This directory is also used for the expansion of the source repositories, as a second disk.
   If running low on space, make this a symlink to an alternate partition with more space.
   Point this symlink wherever your local system has sufficient scratch space.
   b. Make sure that Virtualbox doesn't overrun your HOME partition space.
        $ mkdir /scratch/Virtualbox\ VMs
        $ ln -s /scratch/Virtualbox\ VMs ${HOME}/VirtualBox\ VMs

---- ---- ----
Skip to item #7:

3. [OBSOLETE] This item is only included for reference. The Makefile performs this action, as needed.
   a. Download repos.tgz, repos.cksum
      This only needs to be done once, or occasionally when there's a major CentOS version upgrade.
    For convenience, here's one: 
      repos.tgz:   https://drive.google.com/open?id=1pMM79r_UiEQDv6GmZZQ_AxssxQl9rei-
      repos.cksum: https://drive.google.com/open?id=1F_jSe0dZHXG3Rl8L3QtjHN55EoHpVIT9
   b. [OBSOLETE] Download hpc-collab.tgz, hpc-collab.cksum

4. [OBSOLETE] Put these into the tarballs directory
      mv *.tgz tarballs

5. [OBSOLETE] Compare checksums of the tarballs:
      ex. "cksum repos.tgz; cat repos.cksum", "cksum hpc-collab.tgz; cat hpc-collab.cksum"

6. [OBSOLETE] Untar vc.tgz:
      cd hpc-collab
      tar -xzvf tarballs/hpc-collab.tgz
   which would create, for example, the vc subdirectory.
---- ---- ---- ----

7. Whichever shell you prefer:
     a. bash/zsh/ksh: export PATH=vc/cfg/provision/bin:${PATH} or ". ./bin/setpath.sh"
     b. [t]csh: setenv path=(vc/cfg/provision/bin $path) or "source ./bin/setpath.csh"
     This will be a modulefile, but isn't yet.

8. Check prerequisities:
       make prereq [This is not required, but can be informational.]
   The storage space checker needs work.

9. Add your in-cluster userid, and home directory if needed, to the cluster.
   See: clusters/vc/common/provision/useradd/README

9. Construct the cluster:
      $ up
   or more verbosely:
      $ make [help | show | up | pkg | ...]
   This will trigger construction of the virtual cluster nodes, with dependencies.
   The Makefile codifies dependencies so that the full cluster can be brought up or down with, for example,
     'make up' or 'make unprovision'
   This is less convenient then using the aliases that setpath create because the aliases have the relevant
   Makefile paths.

   The argument to make ("show", "up", "provision", <nodename>) can also be used as an alias. That is,
   "vcfs" is equivalent to "make vcfs". Nodename abbreviations have punctuation shortcuts.



### ### state transitions ### ###
#
# these are not mutually exclusive,
#  - a provisioned node may be powered off
#  - an up node may be partially provisioned, the provision.sh script did not complete successfully 
#  - provisioned means that the provision.sh script completed successfully
# to be usable, a node must be in PROVISIONED state
#
#                                     ⬐ ─────────────────────── [unprovision.sh] ⟵ ─────────────────────── ↰
#                                     ↓                                                                    ↑
# NONEXISTENT ─── "vagrant up" ─── → RUNNING ─── [provision.sh] ── → PROVISIONED ─── vagrant halt ─── → POWEROFF
#     ↑                ↑ ⬑ ──────────────────────────────────────────── ⬑ ──── [already provisioned] ⟵ ─── ↲ 
#     ↑                ⬑ ────────────────────── [unprovision.sh] ────────────── UNPROVISION ⟵ ──────────── ↲ 
#     ⬑ ─────────────────────────────────────── "vagrant destroy" ──────────────────────────────────────── ↲ 
#
### ### state transitions ### ###