Merge pull request #172 from blakecaldwell/linux_docker_troubleshooting

Linux docker troubleshooting

installer/centos/README.md

@@ -64,10 +64,10 @@ Open a bash terminal and run these commands (from [Docker Compose installation](
     ```
 
 3. 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.
-    * If the GUI doesn't show up, check the [Docker troubleshooting section](../docker/troubleshooting.md) (also links the bottom of this page)
+    - If the GUI doesn't show up, check the [Docker troubleshooting section](../docker/troubleshooting.md) (also links the bottom of this page). It may be necessary to run the `xhost +local:docker` command to open up permissions to display the GUI on your local machine.
 4. You can now proceed to running the tutorials at [https://hnn.brown.edu/index.php/tutorials/](https://hnn.brown.edu/index.php/tutorials/) . Some things to note:
-   * 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
+    - 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
 5. To quit HNN and shut down container, first press 'Quit' within the GUI. Then run `./hnn_docker.sh stop`.
 
     ```bash

installer/centos/centos7-installer.sh

@@ -22,16 +22,16 @@ cd $startdir && \
     mkdir nrn && \
     cd nrn && \
     git clone https://github.com/neuronsimulator/nrn src && \
-    cd /home/hnn_user/nrn/src && \
+    cd $startdir/nrn/src && \
     ./build.sh && \
     ./configure --with-nrnpython=python3 --with-paranrn --disable-rx3d \
       --without-iv --without-nrnoc-x11 --with-mpi \
-      --prefix=/home/hnn_user/nrn/build && \
+      --prefix=$startdir/nrn/build && \
     make -j4 && \
     make install -j4 && \
     cd src/nrnpython && \
     python3 setup.py install --user && \
-    cd /home/hnn_user/nrn/ && \
+    cd $startdir/nrn/ && \
     rm -rf src && \
     sudo yum clean all
 

installer/centos/native_install.md

@@ -1,18 +1,27 @@
 # HNN native install (CentOS)
 
 The scripts below can be used to install HNN and its prerequisites. However, there is a greater possibility that your base environment will not be compatible with the script and installation might require additional troubleshooting. Thus, we do not recommend this method. For the recommended Docker-based installation, please see the instructions below.
-  - Alternative: [Docker install instructions](README.md)
+
+- Alternative: [Docker install instructions](README.md)
 
 See the scripts in this directory:
-* CentOS 6: [centos6-installer.sh](centos6-installer.sh)
-* CentOS 7: [centos7-installer.sh](centos7-installer.sh)
-  ```
+
+- CentOS 7: [centos7-installer.sh](centos7-installer.sh)
+
+  ```bash
   chmod +x ./centos7-installer.sh
   ./centos7-installer.sh
   ```
 
-# Troubleshooting
+- CentOS 6 (no longer maintained): [centos6-installer.sh](centos6-installer.sh)
+
+  ```bash
+  chmod +x ./centos6-installer.sh
+  ./centos6-installer.sh
+  ```
+
+## 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/troubleshooting.md

@@ -4,77 +4,62 @@ Common problems that one might encounter running the HNN docker container are li
 
 Make sure to check the log hnn_docker.log for more verbose error messages that will hint at which of the sections to go to below.
 
-* [Failed to start HNN on any X port](#xdisplay)
+* [Failed to start HNN (No GUI)](#xdisplay)
 * [Starting HNN fails with 'Drive has not been shared'](#shared)
 * [This computer doesn't have VT-x/AMD-v enabled](#vtx)
 * [Image operating system linux cannot be used on this platform](#image)
 
-# Failed to start HNN
+## Failed to start HNN (No GUI)
 
 Output from `./docker_hnn.sh start`:
 
 ```none
-Starting HNN... failed to start HNN. Please see hnn_docker.log for more details
+Starting HNN... failed
+Please see hnn_docker.log for more details
 ```
 
-Check the contents of `hnn_docker.log` to determine which of the following issue applies
+Check the contents of `hnn_docker.log`. Most likely, they will be something similar to below:
 
-<a name="xdisplay"/>
-
-## Failed to start HNN on any X port
-
-`hnn_docker.log` contents:
 ```none
-Starting HNN GUI...
-No protocol specified
-qt.qpa.xcb: could not connect to display localhost:0
-qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
-This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.
-
-Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, wayland-egl, wayland, wayland-xcomposite-egl, wayland-xcomposite-glx, webgl, xcb.
-
-/home/hnn_user/start_hnn.sh: line 41:   147 Aborted                 python3 hnn.py
-
-...[more output]...
-
-Failed to start HNN on any X port
-Connection to localhost closed.
+Creating hnn_container ... done
+Attaching to hnn_container
+hnn_container | Starting HNN GUI...
+hnn_container | No protocol specified
+hnn_container | qt.qpa.xcb: could not connect to display :0
+hnn_container | qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
+hnn_container | This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.
+hnn_container |
+hnn_container | Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, wayland-egl, wayland, wayland-xcomposite-egl, wayland-xcomposite-glx, webgl, xcb.
+hnn_container |
 ```
 
-macOS only: try forcing a restart of the container:
+The important line for troubleshooting is the next line and will look something like this:
 
-```bash
-./hnn_docker.sh -r start
-```
-
-Then try to start HNN manually: 
-```bash
-docker exec -ti hnn_container bash
+```none
+hnn_container | /home/hnn_user/start_hnn.sh: line 41:   147 Aborted                 python3 hnn.py
 ```
 
-Try starting HNN manually:
+OR
 
-```bash
-python3 hnn.py
+```none
+hnn_container | /home/hnn_user/start_hnn.sh: line 45:    12 Aborted                 (core dumped) python3 hnn.py
 ```
 
-If that doesn't work, troubleshooting steps diverge for each operating system.
+Troubleshooting steps diverge for each operating system.
 
 * Mac/Windows
 
-    1. Check that the X server is started (VcXsrv for Windows and XQuartz for Mac).
+    1. Check that the X server is started (VcXsrv for Windows and XQuartz for Mac) and verify that it works with other applications, such as with ssh X-forwarding, if possible.
 
 * Linux
 
     1. Try explicitly giving the docker container authentication for display on the X server
 
         ```bash
         xhost +local:docker
-        cd hnn/installer/docker
-        docker-compose restart
         ```
 
-If issues persist, please include output from the above commands in a new [GitHub issue](https://github.com/jonescompneurolab/hnn/issues)
+If issues persist, we'd greatly appreciate it if you would report the issue on our [GitHub Issues](https://github.com/jonescompneurolab/hnn/issues). Please include output from hnn_docker.log and the above commands
 
 <a name="shared"/>
 
@@ -89,16 +74,17 @@ ERROR: for hnn_container  Cannot create container for service hnn: b'Drive has n
 
 ERROR: for hnn  Cannot create container for service hnn: b'Drive has not been shared'
 ```
+
 This will happen when starting the HNN container for the first time on Windows. When it is starting, there will be a prompt in the lower-right asking you to share the drive C:. Rerun the script to see the prompt again
 
 <a name="vtx"/>
 
-# This computer doesn't have VT-x/AMD-v enabled
+## This computer doesn't have VT-x/AMD-v enabled
 
 [MetaCell documentation link](https://github.com/MetaCell/NetPyNE-UI/wiki/Docker-installation#problem-this-computer-doesnt-have-vt-xamd-v-enabled)
 
 <a name="image"/>
 
-# Image operating system linux cannot be used on this platform
+## Image operating system linux cannot be used on this platform
 
 [MetaCell documentation link](https://github.com/MetaCell/NetPyNE-UI/wiki/Docker-installation#problem-image-operating-system-linux-cannot-be-used-on-this-platform)

installer/ubuntu/README.md

@@ -63,7 +63,7 @@ Open a bash terminal and run these commands (from [Docker Compose installation](
     ```
 
 3. 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.
-    * If the GUI doesn't show up, check the [Docker troubleshooting section](../docker/troubleshooting.md) (also links the bottom of this page)
+    * If the GUI doesn't show up, check the [Docker troubleshooting section](../docker/troubleshooting.md) (also links the bottom of this page). It may be necessary to run the `xhost +local:docker` command to open up permissions to display the GUI on your local machine.
 4. You can now proceed to running the tutorials at [https://hnn.brown.edu/index.php/tutorials/](https://hnn.brown.edu/index.php/tutorials/) . Some things to note:
    * 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

installer/ubuntu/installer.sh

@@ -20,16 +20,16 @@ cd $startdir && \
     mkdir nrn && \
     cd nrn && \
     git clone https://github.com/neuronsimulator/nrn src && \
-    cd /home/hnn_user/nrn/src && \
+    cd $startdir/nrn/src && \
     ./build.sh && \
     ./configure --with-nrnpython=python3 --with-paranrn --disable-rx3d \
       --without-iv --without-nrnoc-x11 --with-mpi \
-      --prefix=/home/hnn_user/nrn/build && \
+      --prefix=$startdir/nrn/build && \
     make -j4 && \
     make install -j4 && \
     cd src/nrnpython && \
     python3 setup.py install --user && \
-    cd /home/hnn_user/nrn/ && \
+    cd $startdir/nrn/ && \
     rm -rf src && \
     sudo apt-get -y remove --purge bison flex python3-dev zlib1g-dev python && \
     sudo apt-get autoremove -y --purge && \