Basic Instructions - subject to major changes

Docker

There will be multiple Dockerfiles in cloud/Dockerfiles to support various
container compositions. Please consult each Dockerfile to determine which
one is dresired for your situation.

Vagrant (deprecating in favor of Docker)

Assumption: You're on a Linux or MacOS as the HOST machine and in a terminal
window. You also have access to the `git` utility.  These instructions do not
apply to Windows, which is not supported here at this time (thought Vagrant
and Virtual Box certainly do support Windows). We may add Windows instructions
at a later time, but the general steps should still conceptually work.

1. install VirtualBox onto your local laptop or workstation

  https://virtualbox.org

2. install Vagrant onto your local laptop or workstation

  https://www.vagrantup.com

3. ON HOST machine (laptop):

  % cd $HOME
  % git clone https://github.com/jasonfleming/asgs.git
  % cd $HOME/asgs/cloud/bento-ubuntu-18.10
  % git checkout master 
  % vagrant up
  % vagrant ssh              # this will place you on the virtual machine as user "vagrant"

NOTE: "bento" refers to official Vagrant base images found at

  https://app.vagrantup.com/bento

in this case we're using the image available at

  https://app.vagrantup.com/bento/boxes/ubuntu-18.10

4. ON GUEST machine (vm), initialize ASGS on the virtual machine, download
   and build padcirc, adcirc, adcprep, adcpost, padcswan, and adcswan

  $ bash $HOME/init-asgs.sh # this file is in $HOME (compiles all Fortran in ./asgs, perlbrew, and latest perl [a, b]

"init-asgs.sh" will checkout the asgs git repository into $HOME, change
into $HOME/asgs, the run 'cloud/general/asgs-brew.pl'. This script builds
all Fortran utilities, installs a local version of Perl, and installs the
required Python modules. As a final step, it tries to compile adcirc/swan
using the libraries/wrappers (openmpi) that are build in previous steps.
This last part is interactive at this time of the directory is not found,

$HOME/adcirc-cg/work

It asks if you'd like to checkout adcirc-cg from Github. If you type 'n'
or 'N', the script ends (saying the last step to build adcirc failed). If
you type 'y' or 'Y', it attempt to checkout adcirc-cg from Github. See [c]
if you plan to do this since it requires that you have permissions to read
this private repository.

5. Assuming asgs-brew.pl was allowed to progress through a successful
adcirc/swan build (however you aquired the source), the final step installs
a very handy script called "asgsh", or the "ASGS Shell". It is just a
bash shell that is started with the environment that asgs-brew.pl has created
and some handy custom commands to make testing and setting up operational
ASGS instances more convenient. This script is put in $HOME/opt/bin/asgsh,
and it is autogenerated by asgs-brew.pl. See [d] for more information.

Foot Notes:

[a] NOTE: init-adcirc.sh pulls down asgs from GitHub (no credentials,
required), it also attempts to pull down adcirc-cg but it requires your
GitHub username/password AND access to the adcirc-cg repo.

[b] NOTE: the script used to install perlbrew, then to use perlbrew to
install the version of Perl we want is a little flaky. Feedback on the user
experience will help make it more robust.

[c] NOTE: the adcirc-cg repository is private and owned by the adcirc github
"organization". If you do not have access to it or the adcirc source code,
please contact the representatives listed at https:/adcirc.org.

[d] See the ASGS Shell README for more information, README.asgsh.

More Information

Vagrant is a nice utility that allows one to manage headless virtual machines
on their laptops or work stations. Most use VirtualBox as the VM hypervisor,
but it supports a variety of platforms. It works by starting with a vanilla
base image (e.g., bento-ubuntu-18.10) and provides a configuration file
(Vagrantfile) where a user can define how they want the virtual machine
provisioned (set up).

The purpose of providing a set of Vagrant provisioning scripts inside of
this repo is to create a starting point for anyone wanting to run or develop
ASGS locally. In the future it might be the basis for provisioning on actual
cloud infrastructures (which Vagrant does support).

Have fun!