Merge pull request #75 from blakecaldwell/v1.0_docs

Update docs for release 1.0

conf.py

@@ -136,7 +136,7 @@ def readtips (d):
     if not safemkdir(dbase): sys.exit(1) # check existence of base hnn output dir
   else:
     if d['homeout']: # user home directory for output
-      dbase = os.path.join(os.path.expanduser('~'),'hnn_output') # user home directory
+      dbase = os.path.join(os.path.expanduser('~'),'hnn_out') # user home directory
       if not safemkdir(dbase): sys.exit(1) # check existence of base hnn output dir
     else: # cwd for output
       dbase = os.getcwd() # use os.getcwd instead for better compatability with NSG

installer/brown_ccv/vnc-client.md

@@ -1,6 +1,6 @@
 # Running HNN with the VNC client on Oscar
 
-1. Download the CCV VNC Client (see [VNC Client](https://web1.ccv.brown.edu/technologies/vnc))
+1. Download the CCV VNC Client (see [Oscar VNC Documentation](https://docs.ccv.brown.edu/oscar/connecting-to-oscar/vnc))
 2. Move the file CCV_VNC_2.0.3.jar to somewhere where you can access later and double click on it.
 
    * On Mac systems:
@@ -19,12 +19,9 @@
    singularity run hnn.simg
    ```
 
-6. When the HNN GUI starts up, make sure to change limit the number of cores the amount when requesting the VNC session (e.g. 4 cores)
-    * Click 'Set Parameters' -> 'Run' and change 'NumCores'
-7. You can now proceed to the tutorials at https://hnn.brown.edu/index.php/tutorials/ . Some things to note:
+6. You can now proceed to the tutorials at https://hnn.brown.edu/index.php/tutorials/ . Some things to note:
 
-   * The files within the container are visible at `/`. This allows you to access both the container filesystem and Oscar's filesystem seamlessly. If you are loading sample files for the tutorials, look in `/home/hnn_user/hnn_source_code`
-   * The "Model Visualization" feature will not work and you will receive an error in the terminal window: `ImportError: libreadline.so.6: cannot open shared object file: No such file or directory`.
+   * The files within the container are visible are integrated within Oscar's view of your director. For example, your user directory might be `/users/myuser` and the hnn_user within the container has a user directory `/home/hnn_user`. If you are loading sample files for the tutorials, look in `/home/hnn_user/hnn_source_code`. Your output from simulations will be stored in `/users/myuser/hnn_out`
 
 ## Running HNN a second time
 

installer/brown_ccv/x11-forwarding.md

@@ -39,7 +39,7 @@
 
 3. Log in using your CCV account password
 
-4. Start an interactive job with the `interact` command. Choose the number of cores for your allocations. If you have an exploratory account, you are limited to 16 cores. Anything larger will remain in the queue forever.
+4. Start an interactive job with the `interact` command. Choose the number of cores for your allocations. If you have an exploratory account, you are limited to 16 cores. You can also use a condo account to use larger allocations.
 
    ```bash
    interact -n 16
@@ -54,12 +54,9 @@
    singularity run hnn.simg
    ```
 
-6. When the HNN GUI starts up, make sure to change limit the number of cores the amount when requesting the interactive session (e.g. 16 cores)
-    * Click 'Set Parameters' -> 'Run' and change 'NumCores'
-7. You can now proceed to the tutorials at https://hnn.brown.edu/index.php/tutorials/ . Some things to note:
+6. You can now proceed to the tutorials at https://hnn.brown.edu/index.php/tutorials/ . Some things to note:
 
-   * The files within the container are visible at `/`. This allows you to access both the container filesystem and Oscar's filesystem seamlessly. If you are loading sample files for the tutorials, look in `/home/hnn_user/hnn_source_code`
-   * The "Model Visualization" feature will not work and you will receive an error in the terminal window: `ImportError: libreadline.so.6: cannot open shared object file: No such file or directory`.
+   * The files within the container are visible are integrated within Oscar's view of your director. For example, your user directory might be `/users/myuser` and the hnn_user within the container has a user directory `/home/hnn_user`. If you are loading sample files for the tutorials, look in `/home/hnn_user/hnn_source_code`. Your output from simulations will be stored in `/users/myuser/hnn_out`
 
 ## Running HNN a second time
 

installer/centos/README.md

@@ -1,16 +1,20 @@
 # Installing HNN on CentOS (Docker install)
 
 This guide describes installing HNN on CentOS using Docker. This method will automatically download the HNN Docker container image when HNN is started for the first time. If you would prefer to install HNN without Docker, please see the instructions below.
-  - Alternative: [Native install instructions (advanced users)](native_install.md)
 
-**Note: please verify that your OS supports Docker CE**
-   - CentOS 7 and later versions are supported
-   - See [OS requirements](https://docs.docker.com/install/linux/docker-ce/centos/#os-requirements)
-   - It may be possible to install older versions of docker meant for earlier CentOS versions. We recommend following the currently supported procedure from Docker, but you may find a version of Docker in the [EPEL repositories](https://fedoraproject.org/wiki/EPEL) for CentOS 6, which would would work for your OS.
+- Alternative: [Native install instructions (advanced users)](native_install.md)
+
+## Verify that your OS supports Docker CE
+
+    - CentOS 7 and later versions are supported
+    - See [OS requirements](https://docs.docker.com/install/linux/docker-ce/centos/#os-requirements)
+    - It may be possible to install older versions of docker meant for earlier CentOS versions. We recommend following the currently supported procedure from Docker, but you may find a version of Docker in the [EPEL repositories](https://fedoraproject.org/wiki/EPEL) for CentOS 6, which would would work for your OS.
 
 ## Prerequisite: install Docker
+
 1. To install docker, type the following commands in a terminal (x86_64 only). They are from [Docker's CentOS install instructions](https://docs.docker.com/install/linux/docker-ce/centos/) for installing docker-ce from Docker's official repository.
-    ```
+
+    ```bash
     # get prerequisites for docker
     sudo yum install -y yum-utils device-mapper-persistent-data lvm2
     # add the repository
@@ -23,15 +27,20 @@ This guide describes installing HNN on CentOS using Docker. This method will aut
     # verify that docker runs
     sudo docker run hello-world
     ```
+
 2. Add your user to the docker group to avoid having to run docker commands with "sudo"
-    ```
+
+    ```bash
     $ sudo usermod -a -G docker [username]
     ```
+
 3. Log out and back in (may need to reboot) for the group change to take effect
 
 ## Prerequisite: install Docker Compose
+
 Open a bash terminal and run these commands (from [Docker Compose installation](https://docs.docker.com/compose/install/)):
-  ```
+
+  ```bash
   $ bash -c 'sudo curl -L "https://github.com/docker/compose/releases/download/1.23.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose'
   $ sudo chmod +x /usr/local/bin/docker-compose
   $ docker-compose --version
@@ -40,28 +49,67 @@ Open a bash terminal and run these commands (from [Docker Compose installation](
 ## Start HNN
 
 1. Check that Docker is running properly by typing the following in a new terminal window.
-    ```
+    ```bash
     $ docker info
     ```
+
 2. Clone or download the [HNN repo](https://github.com/jonescompneurolab/hnn). If you already have a previous version of the repository, bring it up to date with the command `git pull origin master` instead of the `git clone` command below.
-    ```
+
+    ```bash
     $ git clone https://github.com/jonescompneurolab/hnn.git
     $ cd hnn/installer/docker
     ```
-3. Start the Docker container. Note: the jonescompneurolab/hnn Docker image will be downloaded from Docker Hub (about 1.5 GB). The docker-compose command can be used to manage Docker containers described in the specification file docker-compose.yml. The parameter "up" starts the containers (just one in our case) in that file and "-d" starts the docker container in the background.
+
+3. Start the Docker container. Note: the jonescompneurolab/hnn Docker image will be downloaded from Docker Hub (about 2 GB). The docker-compose command can be used to manage Docker containers described in the specification file docker-compose.yml.
+
+    ```bash
+    $ docker-compose run hnn
+    Pulling hnn (jonescompneurolab/hnn:)...
+    latest: Pulling from jonescompneurolab/hnn
+    34dce65423d3: Already exists
+    796769e96d24: Already exists
+    2a0eada9611d: Already exists
+    d6830a7cd972: Already exists
+    ddf2bf28e180: Already exists
+    77bf1279b29f: Pull complete
+    6c8ddf82616f: Pull complete
+    a991616934ba: Pull complete
+    2cece6240c19: Pull complete
+    df826e7d26b9: Pull complete
+    824d51cbc89d: Pull complete
+    0d16f27c744b: Pull complete
+    Digest: sha256:0c27e2027828d2510a8867773562bbc966c509f45c9921cc2d1973c575d327b3
+    Status: Downloaded newer image for jonescompneurolab/hnn:latest
     ```
-    $ docker-compose up -d
-    ```    
+
 4. The HNN GUI should show up. Make sure that you can run simulations by clicking the 'Run Simulation' button. This will run a simulation with the default configuration. After it completes, graphs should be displayed in the main window.
 5. You can now proceed to running the tutorials at https://hnn.brown.edu/index.php/tutorials/ . Some things to note:
-   * A directory called "hnn" exists both inside the container (at /home/hnn_user/hnn) and outside (in the directory set by step 2) that can be used to share files between the container and your host OS.
-   * If you run into problems starting the Docker container or the GUI is not displaying, please see the [Docker troubleshooting section](../docker/README.md#Troubleshooting)
-   * If you closed the HNN GUI or it is no longer running, and you would like to restart it, run the following command from the same directory set in step 2:
-      ```
-      $ docker-compose restart
-      ```
-6. **NOTE:** You may want run commands or edit files within the container. To access a command prompt in the container, use [`docker exec`](https://docs.docker.com/engine/reference/commandline/exec/) as shown below:
+   - A directory called "hnn_out" exists both inside the container (at /home/hnn_user/hnn_out) and outside (in the directory set by step 2) that can be used to share files between the container and your host OS.
+   - The HNN repository with sample data and parameter files exists at /home/hnn_user/hnn_source_code.
+   - If you run into problems starting the Docker container or the GUI is not displaying, please see the [Docker troubleshooting section](../docker/README.md#Troubleshooting)
+
+## Updgrading to a new version of HNN
+
+1. Verify Docker is still running. To confirm that Docker is running properly, typing `docker info` should return a bunch of output, but no errors.
+
+    ```bash
+    $ docker info
+    ```
+
+2. Open a terminal window
+
+    ```bash
+    $ cd hnn/installer/docker
+    $ docker-compose up --no-start
+    Recreating docker_hnn_1 ... done
+    $ docker-compose run hnn
     ```
+
+## Editing files within HNN container
+
+You may want run commands or edit files within the container. To access a command shell in the container, start the container using `docker-compose run hnn` in one terminal window and open another terminal to use [`docker exec`](https://docs.docker.com/engine/reference/commandline/exec/) as shown below:
+
+    ```bash
     $ docker exec -ti docker_hnn_1 bash
     hnn_user@054ba0c64625:/home/hnn_user$
     ```
@@ -70,20 +118,22 @@ Open a bash terminal and run these commands (from [Docker Compose installation](
 
 ## Uninstalling HNN
 
-1. If you want to just remove the container and 1.5 GB HNN image, run these commands from a terminal window:
-    ```
+1. If you want to just remove the container and 2 GB HNN image, run these commands from a terminal window:
+
+    ```bash
     $ docker rm -f docker_hnn_1
     $ docker rmi jonescompneurolab/hnn
     ```
+
 2. To continue and remove Docker, follow these instructions from [Uninstall Docker CE](https://docs.docker.com/install/linux/docker-ce/centos/#uninstall-docker-ce)
-    ```
+
+    ```bash
     $ sudo yum remove docker-ce
     $ sudo rm -rf /var/lib/docker
     ```
 
-
 # Troubleshooting
 
 If you run into other issues with the installation, please [open an issue on our GitHub](https://github.com/jonescompneurolab/hnn/issues). Our team monitors these issues and will be able to suggest possible fixes.
 
-For other HNN software issues, please visit the [HNN bulletin board](https://www.neuron.yale.edu/phpBB/viewforum.php?f=46)
+For other HNN software issues, please visit the [HNN bulletin board](https://www.neuron.yale.edu/phpBB/viewforum.php?f=46)

installer/docker/README.md

@@ -8,22 +8,26 @@ This directory contains files for building the HNN container and using docker-co
 
 ## Pulling the prebuilt Docker container from Docker Hub
 The newest version of HNN is available as a prebuilt container posted on Docker Hub, which can be used instead of building the container and all of its prerequisites (NEURON) from scratch.
-```
+```bash
 docker pull jonescompneurolab/hnn
 ```
 
 ## Building HNN container from this directory
-```
+
+The CACHEBUST argument reuses the docker cache up to the point where new HNN source code is included (container will always include latest source code).
+
+```bash
 cd hnn/installer/docker
-docker build --tag jonescompneurolab/hnn .
+docker build --tag jonescompneurolab/hnn --build-arg CACHEBUST=$(date +%s) .
 ```
 
 ## Running HNN container without docker-compose
 Using docker-compose is the preferred way to run HNN containers, because it sets needed environment variables and defines volumes automatically. However, if docker-compose is not available or the user wants to modify docker run arguments, the following command Replicates behavior by docker-compose:
-```
+
+```bash
 # Set DISPLAY for Mac and Windows
 export DOCKER_DISPLAY=host.docker.internal:0
-# For docker toolbox only 
+# For docker toolbox only
 export DOCKER_DISPLAY=192.168.99.1:0
 # For Linux
 export DOCKER_DISPLAY=:0

installer/docker/start_hnn.sh

@@ -15,7 +15,7 @@ function retry_hnn {
     return 1
   else
     echo "HNN GUI stopped by user. Restart container to open again"
-    return 0
+    exit 0
   fi
 }
 
@@ -33,7 +33,7 @@ python3 hnn.py
 if [[ "$?" -eq "0" ]]; then
   # HNN quit gracefully
   echo "HNN GUI stopped by user. Restart container to open again"
-  sleep infinity
+  exit 0
 fi
 
 done=
@@ -42,10 +42,6 @@ XHOST=${DISPLAY%:0}
 for PORT in 0 1 2 3 4; do
   for XHOST in $XHOST 192.168.99.1 192.168.65.2 ""; do
     retry_hnn $XHOST $PORT
-    if [[ "$?" -eq "0" ]]; then
-      # HNN quit gracefully
-      sleep infinity
-    fi
   done
 done