[MRG]: DOC: Final install instructions

[asoplata]

This updates the documented HNN-original installation methods for most
platforms to a newer version based on
#337 . This is necessary because:

1. The most recent install instructions found on the official HNN website
   https://hnn.brown.edu/installation-instructions/
   provide only either a link to build: update dockerfile #337 or, in Oscar's case, a separate set
   of instructions. However, these webpages on the official HNN website
   will soon be deleted, since we will soon be doing a comprehensive
   overhaul of the HNN websites. Once this happens, the only guidance that
   users will receive about installation will need to be present on the
   README of the repository here
   https://github.com/jonescompneurolab/hnn .

2. The Installation page indicated on the README of the repository
   https://github.com/jonescompneurolab/hnn
   does NOT include the install guidance from build: update dockerfile #337. This PR takes the old
   pre-existing instructions for each platform, moves them into respective
   subdirectories such as 2021_instructions (the last year they were
   updated), and then updates most of the instructions for each platform to
   match build: update dockerfile #337.

I successfully tested the updated install versions for brown_ccv, mac,
ubuntu, and windows, and was able to get them all working using the
provided instructions. For the Mac and Windows instructions, I built off of
jonescompneurolab/hnn-tutorials#4

This also adds a disclaimer at the top of every install page that
redirects users to HNN-Core. Even people in the lab have still been
getting confused about which install instructions are for which
version (original HNN or HNN-Core), so that should be cleared up now.

[asoplata]

If would like to make changes to the text, feel free to modify the branch in this PR.

[dylansdaniels]

Plan is to test this before new front-end website release later this summer

[ntolley]

Summary of trying to install on Linux Mint 21.2 Cinnamon

1. curl returned an empty file for hnn.tar.gz however wget worked fine
2. The tar ... -C hnn_source_code flag gave this error:

tar -x --strip-components 1 -f hnn.tar.gz -C hnn_source_code
tar: hnn_source_code: Cannot open: No such file or directory
tar: Error is not recoverable: exiting now

To get around this I manually made a hnn_source_code folder, moved hnn.tar.gz inside and unzipped the file without the -C hnn_source_code flag

3. The pip install gave the following warning:

This became important later as these functions were needed for the make step. The solution was to run:

export PATH="/home/ntolley/.local/bin:$PATH"

Another note is that if you get an error when running make with these commands on the PATH, you have to completely clear the folder and unzip hnn.tar.gz for a fresh start. Otherwise the command will throw an error.

[dylansdaniels]

On Mac, I was running into some errors with the ports for Docker. Essentially, the logic for extracting the port from a string was written for an older version of Docker, where only the IPv4 was returned as a string. But newer versions of Docker return both IPv4 and IPv6. The fix for me was to replace:

    if [[ $? -ne "0" ]]; then
      echo "*failed*" >> "$LOGFILE"
      echo "failed to run ${__command[@]}" >> "$LOGFILE"
      return 1
    fi

    __ssh_port=$(echo $__port_string| cut -d':' -f 2)
    re='^[0-9]+$'
    if ! [[ $__ssh_port =~ $re ]] ; then
      echo "*failed*" >> "$LOGFILE"
      echo "failed to get a port number from \"$__ssh_port\"" >> "$LOGFILE"
      return 1
    fi
    echo "done" >> "$LOGFILE"

with:

    __ssh_port=$(echo "$__port_string" | tr -d '\r' | tail -n1 | awk -F':' '{print $NF}' | tr -d '[:space:]')

    re='^[0-9]+$'
    if [[ -z "$__ssh_port" ]] || ! [[ "$__ssh_port" =~ $re ]]; then
      echo "*failed*" >> "$LOGFILE"
      echo "failed to get a valid port number from \"${__port_string}\"" >> "$LOGFILE"
      return 1
    fi

in the get_container_port function of docker_functions.sh

[asoplata]

Added a commit with Dylan's fix for the Mac install, including documentation of the bug. There is no more work expected to be needed for the new Mac install description. The change to the script was also tested and worked successfully on Windows as well.

[asoplata]

Hey @ntolley I believe the latest commit solves all the issues you discovered. It does the following:

1. Re: curl: it wasn't working before probably because curl was not told to follow redirects, which it needs to since Github stores stuff on raw.githubusercontent.com instead of the more user-accessible repo names like I used. I don't know why I kept that line in there if it wasn't working. The new arguments -sOL fix this, save it into a file of the same name, and also silence log output.

2. Re: tar: yeah, I also don't understand why it was that way, since it is not working for me either. The new commit replaces that option with --one-top-level=hnn_source_code which does the same thing, but actually works. Note that this option is only present in the GNU version of tar, which is used on most Linuxes, but not Mac or BSDs.

3. Re:pip install: The --user option has been dropped. This appears to be the flag that was installing some (but maybe not all?) python packages into ~/.local. However, I don't think that flag is necessary. Deleting my Python package installs in ~/.local and then installing the python packages without --user seems to work and run Original HNN fine for me.

Can you please test the new commands to ensure that they work? Note that you probably need to go in to your ~/.local directory and delete any of the previous Python packages installed at the "user-level".

[asoplata]

@ntolley Would you mind re-visiting this? The Linux instructions were updated and should now work for you, I tested them on Kubuntu. Once the Linux instructions are done, we should be good to go.

[ntolley]

Perfect! That completely fixed it on my end

[ntolley]

Great work @asoplata!! Just tested this in a fresh conda enviornment on my Linux Mint build. No issues with the install and a test simulation ran with no hiccups.