From 039779fe38422f6e81865147cb94cd8eb57dd8e4 Mon Sep 17 00:00:00 2001 From: Joshua Date: Wed, 29 Nov 2023 16:10:11 -0500 Subject: [PATCH 01/17] add vcxsrv script --- scripts/configure_vcxsrv.sh | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 scripts/configure_vcxsrv.sh diff --git a/scripts/configure_vcxsrv.sh b/scripts/configure_vcxsrv.sh new file mode 100644 index 00000000..6af8eb24 --- /dev/null +++ b/scripts/configure_vcxsrv.sh @@ -0,0 +1,32 @@ +#!/bin/bash + +# Determine IPv4 address +echo "Finding IPv4 Address..." +HostIPv4Address=$(ip route show default | awk '/default/ {print $3}') + +# Replace the following line with the obtained IPv4 address +export DISPLAY=$IPv4Address:0 + + +# Check if credentials are set up +xauth list + +# Set up magiccookie +echo "Creating magiccookie with IPv4 Address ..." +passPhrase="hnn-app" +magiccookie=$(echo "hnn-cookie" | tr -d '\n\r' | md5sum | awk '{print $1}') + +# Add credentials +echo "Adding magiccookie credentials to X Server..." +xauth add "$DISPLAY" . "$magiccookie" + +# Display new credentials +echo "Display new credentials below..." +xauth list + +# Copy .Xauthority to Windows user profile +echo "Copying credentials to Windows user profile..." +userprofile=$(wslpath $(/mnt/c/Windows/System32/cmd.exe /C "echo %USERPROFILE%" | tr -d '\r\n')) +cp ~/.Xauthority "$userprofile" + +echo "Done setting up X server credentials!" \ No newline at end of file From 80f08d92d4e70bcd6d8fe94c65d402f100356338 Mon Sep 17 00:00:00 2001 From: Joshua Date: Wed, 29 Nov 2023 17:11:32 -0500 Subject: [PATCH 02/17] Update README --- installer/README.md | 9 +++ installer/docker/README.md | 109 +++++++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) diff --git a/installer/README.md b/installer/README.md index cf99bb98..1ded04e8 100644 --- a/installer/README.md +++ b/installer/README.md @@ -1,5 +1,14 @@ # HNN Installation +### UPDATED: 11/29/2023 +Currently, HNN is only supported on Docker. Please refer to the link below for more information on installing HNN on either Mac or Windows. + +[Docker](docker) + +___________________________________________________________________ + +** The following is deprectated ** + This directory contains instructions and files supporting installation of HNN on supported platforms. Click on the link below corresponding to your operating system: * [Windows](windows) diff --git a/installer/docker/README.md b/installer/docker/README.md index 701a8cfc..522298e3 100644 --- a/installer/docker/README.md +++ b/installer/docker/README.md @@ -1,5 +1,114 @@ # HNN Docker Container +### ** UPDATED Instructions: 11/29/2023 ** + +### Windows Installation Process + +## Part 1 Install WSL +1. Open the Command Prompt application. Can be found by searching `Command Prompt` in the Windows search bar. +2. Paste the following command to install Windows Subsystem for Linux (WSL) +``` +wsl --install +``` +![image](https://github.com/jonescompneurolab/hnn/assets/34087669/f94c9ea6-1459-4082-8a01-af69d115368c) + +3. Once the installation is completed, you will see that an `Ubuntu` application is also downloaded. This can be found in `Settings > Apps > Installed apps` or by searching `Ubuntu` in the Windows search bar. +![image](https://github.com/jonescompneurolab/hnn/assets/34087669/aa1635db-ccd7-4989-bdbd-7f89f5493225) + +4. Once WSL is installed, navigate to the Windows Start Menu and in the search bar, look up `Turn Windows Features on or off` and click on it + +5. Go down the list until you see Windows Subsystem for Linux, and check the box so that it is enabled. Click ok so the changes can be applied. +![image](https://github.com/jonescompneurolab/hnn/assets/34087669/d9c9580f-2082-4ac8-bdee-ca599e9b2da1) + +6. Then open up the Ubuntu application that was mentioned in Step 3. +7. The very first time you open up this application, you will be instructed to create a new UNIX username and password. If dont correctly, it will show you an `installation successful!` message. +![image](https://github.com/jonescompneurolab/hnn/assets/34087669/d6e26399-804d-4780-a451-492c1ccdf81f) + + + +## Part 2 Install Docker +1. Please install Docker Desktop from this link https://docs.docker.com/desktop/wsl/#download +2. Once installed, click on the newly added Docker icon to open up the Docker Desktop application. +3. Navigate to Settings, and click on General. Make sure that `Use the WSL 2 Based Engine` is checked. +![image](https://github.com/jonescompneurolab/hnn/assets/34087669/84d0078a-ba4f-478c-8af1-e7771ba896b3) + +4. Next, click on Resources > WSL Integration +5. Inside here, make sure that all Ubuntu options are toggled. Then press apply & restart. +![image](https://github.com/jonescompneurolab/hnn/assets/34087669/d01a0c14-37b2-456a-b7d8-3ed3bdd5283c) + +6. To check if Docker is correctly installed, you can open up the Ubuntu terminal (application) and type `docker --version` this should display the version and build number of the software installed. + + +## Part 3 Install Vcxsrv +1. Please install Vcxsrv https://sourceforge.net/projects/vcxsrv/ +2. Run the installer, choosing "C:\Program Files\VcXsrv" as the destination folder. +3. A new icon named XLaunch should now appear on your computer. Click on the icon to continue with the installation steps. +4. Choose "Multiple windows". Choose '0' for the "Display number". Click 'Next'. +![image]() +5. Select "Start no client" and click 'Next'. +![Alt text]() +6. Please make sure "Disable access control" is checked and click 'Next'. This will take you to the final page where you can press 'Finish' to finish the installation. +![Alt text]() + + +## Part 4 Configure and Run HNN Application +1. Open up a new Ubuntu terminal application, referenced in Step 3 of Part 1. +2. We will now download the source code that starts up the GUI. Paste this command to create a copy of the source code on your computer. +``` +git clone https://github.com/jonescompneurolab/hnn.git +``` +3. Paste the following command to navigate to inside the project in your Ubuntu terminal. +``` +cd hnn +``` +4. Before we can start up the application, an additional step is required. We have to set up the right configurations for Vcxsrv (downloaded in Step 3) before we can start up the HNN interface. To do so, please paste the following command in the terminal to run the `configure_vcxsrv.sh` script which will handle the configurations for you. +``` +./scripts/configure_vcxsrv.sh +``` +A successful run of the `configure_vcxsrv.sh` script should output the following logs. +![Alt text]() + +5. Run the following command to start up the hnn GUI. +``` +./hnn_docker.sh start +``` + +Your terminal should show the following logs if it successfully starts up the hnn GUI. +![image](https://github.com/jonescompneurolab/hnn/assets/34087669/2e5942cb-100f-44cf-9c6f-fdee72576844) + +The resulting hnn GUI on initial startup. +![image](https://github.com/jonescompneurolab/hnn/assets/34087669/cb6f404c-d6df-45ef-ab80-cf85e293bf8b) + + +## Troubleshooting +If you run into the following error while running `./hnn_docker.sh start` + +` + docker-machine could not be found. +` +- Please make sure you have gone over the previous steps for installing the docker desktop. +- If this error persists, please try closing and restarting the docker desktop application. + +If you run into the following error while running `./hnn_docker.sh start` + +` +xuath: (argv):1: couldn't query Security extension on display “:0” +` +- Please double check that you have gone through the steps in Part 3 to configure the magic cookie credentials required for the VcXsrv server to accept connections. + + + + + + + +### ** END OF UPDATED INSTALLATION STEPS ** + +_______________________________________________________________________ + + +** The following is deprectated ** + This directory contains files for building the HNN Docker container. The container itself is running the Ubuntu 18.04 Linux distribution, but can run on any operating system assuming that [Docker](https://www.docker.com/) is installed. ## Pulling the prebuilt Docker container from Docker Hub From 862fe3e208b35b96d4003fbcd69febb8ca679d2b Mon Sep 17 00:00:00 2001 From: Joshua Date: Thu, 30 Nov 2023 10:49:24 -0500 Subject: [PATCH 03/17] update script --- scripts/configure_vcxsrv.sh | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 scripts/configure_vcxsrv.sh diff --git a/scripts/configure_vcxsrv.sh b/scripts/configure_vcxsrv.sh old mode 100644 new mode 100755 From bfab4a8d8952ae645f827e28d9ff9f4b2d069912 Mon Sep 17 00:00:00 2001 From: Joshua Date: Thu, 30 Nov 2023 10:55:04 -0500 Subject: [PATCH 04/17] add screenshots --- installer/docker/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/installer/docker/README.md b/installer/docker/README.md index 522298e3..5365568b 100644 --- a/installer/docker/README.md +++ b/installer/docker/README.md @@ -44,11 +44,13 @@ wsl --install 2. Run the installer, choosing "C:\Program Files\VcXsrv" as the destination folder. 3. A new icon named XLaunch should now appear on your computer. Click on the icon to continue with the installation steps. 4. Choose "Multiple windows". Choose '0' for the "Display number". Click 'Next'. -![image]() +![Screenshot 2023-11-29 163402](https://github.com/jonescompneurolab/hnn/assets/34087669/89bcad1a-56fd-4026-a718-ea3c81b8554d) + 5. Select "Start no client" and click 'Next'. -![Alt text]() +![Screenshot 2023-11-29 164111](https://github.com/jonescompneurolab/hnn/assets/34087669/57ba748c-6a05-424d-aa7b-8afcc7f9b917) + 6. Please make sure "Disable access control" is checked and click 'Next'. This will take you to the final page where you can press 'Finish' to finish the installation. -![Alt text]() +![Screenshot 2023-11-29 163550](https://github.com/jonescompneurolab/hnn/assets/34087669/d4c7341b-1b00-4721-b49d-79b5dd081047) ## Part 4 Configure and Run HNN Application From 639414813ab7f338bbf39fb3a088b2d31c2f0a34 Mon Sep 17 00:00:00 2001 From: Joshua Date: Thu, 30 Nov 2023 11:22:03 -0500 Subject: [PATCH 05/17] fix text --- installer/docker/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/installer/docker/README.md b/installer/docker/README.md index 5365568b..a1cdcb4d 100644 --- a/installer/docker/README.md +++ b/installer/docker/README.md @@ -70,15 +70,15 @@ cd hnn A successful run of the `configure_vcxsrv.sh` script should output the following logs. ![Alt text]() -5. Run the following command to start up the hnn GUI. +5. Run the following command to start up the HNN GUI. ``` ./hnn_docker.sh start ``` -Your terminal should show the following logs if it successfully starts up the hnn GUI. +Your terminal should display the following messages if it successfully started up the HNN GUI. ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/2e5942cb-100f-44cf-9c6f-fdee72576844) -The resulting hnn GUI on initial startup. +The resulting HNN GUI on initial startup. ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/cb6f404c-d6df-45ef-ab80-cf85e293bf8b) @@ -94,7 +94,7 @@ If you run into the following error while running `./hnn_docker.sh start` If you run into the following error while running `./hnn_docker.sh start` ` -xuath: (argv):1: couldn't query Security extension on display “:0” +xauth: (argv):1: couldn't query Security extension on display “:0” ` - Please double check that you have gone through the steps in Part 3 to configure the magic cookie credentials required for the VcXsrv server to accept connections. From 6401db9c38096b9d7a5cd1b7e18d3e4d02cf2958 Mon Sep 17 00:00:00 2001 From: Joshua Date: Thu, 30 Nov 2023 11:48:22 -0500 Subject: [PATCH 06/17] another round of edits for README --- installer/docker/README.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/installer/docker/README.md b/installer/docker/README.md index a1cdcb4d..5ddb1025 100644 --- a/installer/docker/README.md +++ b/installer/docker/README.md @@ -12,7 +12,7 @@ wsl --install ``` ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/f94c9ea6-1459-4082-8a01-af69d115368c) -3. Once the installation is completed, you will see that an `Ubuntu` application is also downloaded. This can be found in `Settings > Apps > Installed apps` or by searching `Ubuntu` in the Windows search bar. +3. Once the installation is completed, you will see that an `Ubuntu` application is also downloaded. This can be found in `Settings > Apps > Installed apps` or by searching `Ubuntu` in the Windows search bar. Please take note of this as it will be important later on in this installation. ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/aa1635db-ccd7-4989-bdbd-7f89f5493225) 4. Once WSL is installed, navigate to the Windows Start Menu and in the search bar, look up `Turn Windows Features on or off` and click on it @@ -21,35 +21,36 @@ wsl --install ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/d9c9580f-2082-4ac8-bdee-ca599e9b2da1) 6. Then open up the Ubuntu application that was mentioned in Step 3. -7. The very first time you open up this application, you will be instructed to create a new UNIX username and password. If dont correctly, it will show you an `installation successful!` message. +7. The very first time you open up this application, you will be instructed to create a new UNIX username and password. If done correctly, it will show an `installation successful!` message. ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/d6e26399-804d-4780-a451-492c1ccdf81f) ## Part 2 Install Docker -1. Please install Docker Desktop from this link https://docs.docker.com/desktop/wsl/#download -2. Once installed, click on the newly added Docker icon to open up the Docker Desktop application. -3. Navigate to Settings, and click on General. Make sure that `Use the WSL 2 Based Engine` is checked. +1. Please install Docker Desktop from this link https://docs.docker.com/desktop/install/windows-install/ +2. Once installed, click on the newly added Docker Desktop icon on your computer to open up the application. +3. Press on the Settings Icon in the navigation bar to navigate to the Settings. Once ther, click on the General tab. Make sure that `Use the WSL 2 Based Engine` is checked as shown in the screenshot below. ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/84d0078a-ba4f-478c-8af1-e7771ba896b3) -4. Next, click on Resources > WSL Integration +4. Next, click on the Resources tab on the left and navigate to `WSL Integration`` 5. Inside here, make sure that all Ubuntu options are toggled. Then press apply & restart. ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/d01a0c14-37b2-456a-b7d8-3ed3bdd5283c) -6. To check if Docker is correctly installed, you can open up the Ubuntu terminal (application) and type `docker --version` this should display the version and build number of the software installed. +6. To check if Docker is correctly installed, you can open up the Ubuntu terminal (application) and type `docker --version`, If done correctly, a version and build number of the software installed should be fed back. ## Part 3 Install Vcxsrv 1. Please install Vcxsrv https://sourceforge.net/projects/vcxsrv/ -2. Run the installer, choosing "C:\Program Files\VcXsrv" as the destination folder. -3. A new icon named XLaunch should now appear on your computer. Click on the icon to continue with the installation steps. -4. Choose "Multiple windows". Choose '0' for the "Display number". Click 'Next'. +2. Run the installer, choosing `C:\Program Files\VcXsrv` as the destination folder. +3. A new icon named `XLaunch` should now appear on your computer. Click on the icon to open up the application and continue with the installation steps. +4. Choose "Multiple windows" for `Select display settings`. Choose '0' for the "Display number". Click 'Next'. + ![Screenshot 2023-11-29 163402](https://github.com/jonescompneurolab/hnn/assets/34087669/89bcad1a-56fd-4026-a718-ea3c81b8554d) 5. Select "Start no client" and click 'Next'. ![Screenshot 2023-11-29 164111](https://github.com/jonescompneurolab/hnn/assets/34087669/57ba748c-6a05-424d-aa7b-8afcc7f9b917) -6. Please make sure "Disable access control" is checked and click 'Next'. This will take you to the final page where you can press 'Finish' to finish the installation. +6. Please make sure "Disable access control" is checked and click 'Next'. This will take you to the final page where you can press 'Finish' to complete the installation. ![Screenshot 2023-11-29 163550](https://github.com/jonescompneurolab/hnn/assets/34087669/d4c7341b-1b00-4721-b49d-79b5dd081047) @@ -63,14 +64,14 @@ git clone https://github.com/jonescompneurolab/hnn.git ``` cd hnn ``` -4. Before we can start up the application, an additional step is required. We have to set up the right configurations for Vcxsrv (downloaded in Step 3) before we can start up the HNN interface. To do so, please paste the following command in the terminal to run the `configure_vcxsrv.sh` script which will handle the configurations for you. +4. Before we can start up the application, an additional step is required. We have to set up the right configurations for Vcxsrv (downloaded in Part 3) before we can start up the HNN interface. To do so, please paste the following command in the terminal to run the `configure_vcxsrv.sh` script which will automatically handle the configurations for you. ``` ./scripts/configure_vcxsrv.sh ``` A successful run of the `configure_vcxsrv.sh` script should output the following logs. -![Alt text]() +![Screenshot 2023-11-29 165651](https://github.com/jonescompneurolab/hnn/assets/34087669/5c41c8f5-2e4e-48c6-b32a-1de2cebdd7b9) -5. Run the following command to start up the HNN GUI. +5. Now run the following command to start up the HNN GUI. ``` ./hnn_docker.sh start ``` @@ -96,8 +97,7 @@ If you run into the following error while running `./hnn_docker.sh start` ` xauth: (argv):1: couldn't query Security extension on display “:0” ` -- Please double check that you have gone through the steps in Part 3 to configure the magic cookie credentials required for the VcXsrv server to accept connections. - +- Please double check that you have gone through the steps in Part 3 to correctly set up the Vcxsrv server. Also check that you have successfully ran the `configure_vcxsrv.sh` script from the previous Step 4 of this Part 4 of the installation. From 4dbc20523b654501556ea2d9083fb8ddb1068d11 Mon Sep 17 00:00:00 2001 From: Josh Lu Date: Thu, 30 Nov 2023 12:05:45 -0500 Subject: [PATCH 07/17] Update README.md --- installer/docker/README.md | 45 +++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/installer/docker/README.md b/installer/docker/README.md index 5ddb1025..17394f32 100644 --- a/installer/docker/README.md +++ b/installer/docker/README.md @@ -13,44 +13,51 @@ wsl --install ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/f94c9ea6-1459-4082-8a01-af69d115368c) 3. Once the installation is completed, you will see that an `Ubuntu` application is also downloaded. This can be found in `Settings > Apps > Installed apps` or by searching `Ubuntu` in the Windows search bar. Please take note of this as it will be important later on in this installation. + ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/aa1635db-ccd7-4989-bdbd-7f89f5493225) -4. Once WSL is installed, navigate to the Windows Start Menu and in the search bar, look up `Turn Windows Features on or off` and click on it +5. Once WSL is installed, navigate to the Windows Start Menu and in the search bar, look up `Turn Windows Features on or off` and click on it -5. Go down the list until you see Windows Subsystem for Linux, and check the box so that it is enabled. Click ok so the changes can be applied. +6. Go down the list until you see Windows Subsystem for Linux, and check the box so that it is enabled. Click OK so the changes can be applied. + ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/d9c9580f-2082-4ac8-bdee-ca599e9b2da1) -6. Then open up the Ubuntu application that was mentioned in Step 3. -7. The very first time you open up this application, you will be instructed to create a new UNIX username and password. If done correctly, it will show an `installation successful!` message. +8. Then open up the Ubuntu application that was mentioned in Step 3. +9. The very first time you open up this application, you will be instructed to create a new UNIX username and password. If done correctly, it will show an `installation successful!` message. + ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/d6e26399-804d-4780-a451-492c1ccdf81f) ## Part 2 Install Docker 1. Please install Docker Desktop from this link https://docs.docker.com/desktop/install/windows-install/ -2. Once installed, click on the newly added Docker Desktop icon on your computer to open up the application. -3. Press on the Settings Icon in the navigation bar to navigate to the Settings. Once ther, click on the General tab. Make sure that `Use the WSL 2 Based Engine` is checked as shown in the screenshot below. +2. Once installed, click on the newly added Docker Desktop icon on your computer to open up the application. +3. Press on the Settings Icon in the navigation bar to navigate to the Settings. Once there, click on the General tab. Make sure that `Use the WSL 2 Based Engine` is checked as shown in the screenshot below. + ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/84d0078a-ba4f-478c-8af1-e7771ba896b3) -4. Next, click on the Resources tab on the left and navigate to `WSL Integration`` -5. Inside here, make sure that all Ubuntu options are toggled. Then press apply & restart. +5. Next, click on the Resources tab on the left and navigate to `WSL Integration` +6. Inside here, make sure that all Ubuntu options are toggled. Then press apply & restart. + ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/d01a0c14-37b2-456a-b7d8-3ed3bdd5283c) -6. To check if Docker is correctly installed, you can open up the Ubuntu terminal (application) and type `docker --version`, If done correctly, a version and build number of the software installed should be fed back. +8. To check if Docker is correctly installed, you can open up the Ubuntu terminal (application) and type `docker --version`, If done correctly, a version and build number of the software installed should be fed back. ## Part 3 Install Vcxsrv 1. Please install Vcxsrv https://sourceforge.net/projects/vcxsrv/ 2. Run the installer, choosing `C:\Program Files\VcXsrv` as the destination folder. -3. A new icon named `XLaunch` should now appear on your computer. Click on the icon to open up the application and continue with the installation steps. -4. Choose "Multiple windows" for `Select display settings`. Choose '0' for the "Display number". Click 'Next'. +3. A new icon named `XLaunch` should now appear on your computer. Click on the icon to open up the application and continue with the installation steps. +4. Choose "Multiple windows" for `Select display settings`. Choose '0' for the `Display number`. Click 'Next'. ![Screenshot 2023-11-29 163402](https://github.com/jonescompneurolab/hnn/assets/34087669/89bcad1a-56fd-4026-a718-ea3c81b8554d) 5. Select "Start no client" and click 'Next'. + ![Screenshot 2023-11-29 164111](https://github.com/jonescompneurolab/hnn/assets/34087669/57ba748c-6a05-424d-aa7b-8afcc7f9b917) -6. Please make sure "Disable access control" is checked and click 'Next'. This will take you to the final page where you can press 'Finish' to complete the installation. +7. Please make sure "Disable access control" is checked and click 'Next'. This will take you to the final page where you can press 'Finish' to complete the installation. + ![Screenshot 2023-11-29 163550](https://github.com/jonescompneurolab/hnn/assets/34087669/d4c7341b-1b00-4721-b49d-79b5dd081047) @@ -60,7 +67,7 @@ wsl --install ``` git clone https://github.com/jonescompneurolab/hnn.git ``` -3. Paste the following command to navigate to inside the project in your Ubuntu terminal. +3. Paste the following command to navigate to inside the project in your Ubuntu terminal. ``` cd hnn ``` @@ -68,7 +75,7 @@ cd hnn ``` ./scripts/configure_vcxsrv.sh ``` -A successful run of the `configure_vcxsrv.sh` script should output the following logs. +A successful run of the `configure_vcxsrv.sh` script should output the following logs. ![Screenshot 2023-11-29 165651](https://github.com/jonescompneurolab/hnn/assets/34087669/5c41c8f5-2e4e-48c6-b32a-1de2cebdd7b9) 5. Now run the following command to start up the HNN GUI. @@ -77,20 +84,22 @@ A successful run of the `configure_vcxsrv.sh` script should output the following ``` Your terminal should display the following messages if it successfully started up the HNN GUI. + ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/2e5942cb-100f-44cf-9c6f-fdee72576844) The resulting HNN GUI on initial startup. + ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/cb6f404c-d6df-45ef-ab80-cf85e293bf8b) ## Troubleshooting -If you run into the following error while running `./hnn_docker.sh start` +If you run into the following error while running `./hnn_docker.sh start` ` - docker-machine could not be found. +docker-machine could not be found. ` -- Please make sure you have gone over the previous steps for installing the docker desktop. -- If this error persists, please try closing and restarting the docker desktop application. +- Please make sure you have gone over the previous steps for installing the docker desktop. +- If this error persists, please try closing and restarting the docker desktop application. If you run into the following error while running `./hnn_docker.sh start` From 328ebaad20f05244e05b0ae0f01cc1348003787c Mon Sep 17 00:00:00 2001 From: Josh Lu Date: Thu, 30 Nov 2023 12:23:50 -0500 Subject: [PATCH 08/17] Update README.md --- installer/docker/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/installer/docker/README.md b/installer/docker/README.md index 17394f32..495c6738 100644 --- a/installer/docker/README.md +++ b/installer/docker/README.md @@ -118,7 +118,7 @@ xauth: (argv):1: couldn't query Security extension on display “:0” _______________________________________________________________________ -** The following is deprectated ** +** The following is deprecated ** This directory contains files for building the HNN Docker container. The container itself is running the Ubuntu 18.04 Linux distribution, but can run on any operating system assuming that [Docker](https://www.docker.com/) is installed. From 61a23fd8933e46f6d7183b9490e3a6ce2d7df936 Mon Sep 17 00:00:00 2001 From: Josh Lu Date: Fri, 1 Dec 2023 14:10:32 -0500 Subject: [PATCH 09/17] Update installer/docker/README.md Co-authored-by: Nicholas Tolley <55253912+ntolley@users.noreply.github.com> --- installer/docker/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/installer/docker/README.md b/installer/docker/README.md index 495c6738..7687d46e 100644 --- a/installer/docker/README.md +++ b/installer/docker/README.md @@ -62,7 +62,7 @@ wsl --install ## Part 4 Configure and Run HNN Application -1. Open up a new Ubuntu terminal application, referenced in Step 3 of Part 1. +1. Open up a new Ubuntu terminal application, referenced in Step 3 of Part 1. (Note: ensure that the Ubuntu terminal is being used and not the Windows Powershell) 2. We will now download the source code that starts up the GUI. Paste this command to create a copy of the source code on your computer. ``` git clone https://github.com/jonescompneurolab/hnn.git From af8cfa088c72de1c5dcc8366c96e0a1f571df939 Mon Sep 17 00:00:00 2001 From: Josh Lu Date: Wed, 6 Dec 2023 15:03:24 -0500 Subject: [PATCH 10/17] Update installer/docker/README.md Co-authored-by: John Gerrard Holland --- installer/docker/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/installer/docker/README.md b/installer/docker/README.md index 7687d46e..da4ba977 100644 --- a/installer/docker/README.md +++ b/installer/docker/README.md @@ -118,8 +118,6 @@ xauth: (argv):1: couldn't query Security extension on display “:0” _______________________________________________________________________ -** The following is deprecated ** - This directory contains files for building the HNN Docker container. The container itself is running the Ubuntu 18.04 Linux distribution, but can run on any operating system assuming that [Docker](https://www.docker.com/) is installed. ## Pulling the prebuilt Docker container from Docker Hub From 1cefaa09f042a3e2ba343dc51b88420b4c4b081f Mon Sep 17 00:00:00 2001 From: Josh Lu Date: Wed, 6 Dec 2023 15:04:17 -0500 Subject: [PATCH 11/17] Update README.md --- installer/docker/README.md | 84 -------------------------------------- 1 file changed, 84 deletions(-) diff --git a/installer/docker/README.md b/installer/docker/README.md index da4ba977..722b1048 100644 --- a/installer/docker/README.md +++ b/installer/docker/README.md @@ -1,7 +1,5 @@ # HNN Docker Container -### ** UPDATED Instructions: 11/29/2023 ** - ### Windows Installation Process ## Part 1 Install WSL @@ -109,88 +107,6 @@ xauth: (argv):1: couldn't query Security extension on display “:0” - Please double check that you have gone through the steps in Part 3 to correctly set up the Vcxsrv server. Also check that you have successfully ran the `configure_vcxsrv.sh` script from the previous Step 4 of this Part 4 of the installation. - - - - -### ** END OF UPDATED INSTALLATION STEPS ** - -_______________________________________________________________________ - - -This directory contains files for building the HNN Docker container. The container itself is running the Ubuntu 18.04 Linux distribution, but can run on any operating system assuming that [Docker](https://www.docker.com/) is installed. - -## 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. - -Linux container (built from release branches): - -```bash -docker pull jonescompneurolab/hnn -``` - -Linux container (built from master): - -```bash -docker pull jonescompneurolab/hnn:master -``` - -Windows container: - -```bash -docker pull jonescompneurolab/hnn:win64 -``` - -## Building HNN container - -The BUILD_DATE argument is important to build the container with the latest HNN source code. Without it, the build will reuse the docker build cache, which may have been with an old code version. - -Optional arguments are SOURCE_BRANCH and SOURCE_REPO. If they are not specified, the image will be build from source at 'https://github.com/jonescompneurolab/hnn' on branch 'master' - -```bash -docker build --tag jonescompneurolab/hnn --build-arg SOURCE_BRANCH=master --build-arg SOURCE_REPO="https://github.com/jonescompneurolab/hnn" --build-arg BUILD_DATE=$(date +%s) installer/docker -``` - -The windows container container can be built with the following command: - -```bash -docker build --tag jonescompneurolab/hnn:win64 -f installer/windows/Dockerfile installer/docker -``` - -## Starting HNN container - -The container is designed to be run from the `hnn_docker.sh` script, but in general, the following scheme will work for Linux/mac: - -```bash -docker run -d -v "$HOME/hnn_out":"$HOME/hnn_out" --env XAUTHORITY=/tmp/.Xauthority --env SYSTEM_USER_DIR="$HOME" --name hnn_container jonescompneurolab/hnn -``` - -This will start the container in the background. In order to start the HNN GUI, the start_hnn.sh script must be run inside the container: - -## Running HNN with Docker - -We recommend using the `hnn_docker.sh` script which includes checks for directory permissions, creating the necessary files, and adding the appropriate options for each host OS. The commands below give an outline of the process. - -Using SSH can be controlled by the environment variable USE_SSH - -### Without SSH (only recommended for Linux) - -```bash -export USE_SSH=0 -docker exec --env SYSTEM_USER_DIR="$HOME" --env DISPLAY=":0" -u "$(id -u)" hnn_container /home/hnn_user/start_hnn.sh -``` - -* In order to access the hnn_out volume, the command is run as the current user on the host OS. For Windows container, the user hnn_user should be used (-u option can be omitted). - -### Using SSH (stable X server connection) - -```bash -export USE_SSH=1 -SSH_PRIVKEY="installer/docker/id_rsa_hnn" -ssh-keygen -f "$SSH_PRIVKEY" -t rsa -N '' - -export DISPLAY=127.0.0.1:0 export XAUTHORITY=/tmp/.Xauthority export SYSTEM_USER_DIR="$HOME" ssh -o SendEnv=DISPLAY -o SendEnv=XAUTHORITY -o SendEnv=SYSTEM_USER_DIR -o SendEnv=TRAVIS_TESTING -o PasswordAuthentication=no -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -v -i "SSH_PRIVKEY" -R 6000:127.0.0.1:6000 hnn_user@localhost -p 32791 From c9a182a7963e921d2db646a321f4bfabc4ceb2a4 Mon Sep 17 00:00:00 2001 From: Josh Lu Date: Wed, 6 Dec 2023 15:06:09 -0500 Subject: [PATCH 12/17] Update installer/README.md Co-authored-by: John Gerrard Holland --- installer/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/installer/README.md b/installer/README.md index 1ded04e8..00f14974 100644 --- a/installer/README.md +++ b/installer/README.md @@ -1,11 +1,9 @@ # HNN Installation -### UPDATED: 11/29/2023 Currently, HNN is only supported on Docker. Please refer to the link below for more information on installing HNN on either Mac or Windows. [Docker](docker) -___________________________________________________________________ ** The following is deprectated ** From c9afb8c993d131f937b5a03cea2576679617aca4 Mon Sep 17 00:00:00 2001 From: Josh Lu Date: Wed, 6 Dec 2023 15:06:38 -0500 Subject: [PATCH 13/17] Update installer/README.md Co-authored-by: John Gerrard Holland --- installer/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/installer/README.md b/installer/README.md index 00f14974..d8da9eef 100644 --- a/installer/README.md +++ b/installer/README.md @@ -5,8 +5,6 @@ Currently, HNN is only supported on Docker. Please refer to the link below for m [Docker](docker) -** The following is deprectated ** - This directory contains instructions and files supporting installation of HNN on supported platforms. Click on the link below corresponding to your operating system: * [Windows](windows) From 3160c650daf81af701dcdccb3cec9f4c267e6a84 Mon Sep 17 00:00:00 2001 From: Josh Lu Date: Wed, 6 Dec 2023 15:09:06 -0500 Subject: [PATCH 14/17] Update scripts/configure_vcxsrv.sh Co-authored-by: John Gerrard Holland --- scripts/configure_vcxsrv.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/configure_vcxsrv.sh b/scripts/configure_vcxsrv.sh index 6af8eb24..583d3d33 100755 --- a/scripts/configure_vcxsrv.sh +++ b/scripts/configure_vcxsrv.sh @@ -27,6 +27,6 @@ xauth list # Copy .Xauthority to Windows user profile echo "Copying credentials to Windows user profile..." userprofile=$(wslpath $(/mnt/c/Windows/System32/cmd.exe /C "echo %USERPROFILE%" | tr -d '\r\n')) -cp ~/.Xauthority "$userprofile" +cp "~/.Xauthority" "${userprofile}/." echo "Done setting up X server credentials!" \ No newline at end of file From de68a6c87c8f2e9dcfcfd02f40f26830f5b7057e Mon Sep 17 00:00:00 2001 From: Josh Lu Date: Wed, 6 Dec 2023 15:11:57 -0500 Subject: [PATCH 15/17] Update README.md --- installer/README.md | 19 +------------------ 1 file changed, 1 insertion(+), 18 deletions(-) diff --git a/installer/README.md b/installer/README.md index d8da9eef..ddfaca7b 100644 --- a/installer/README.md +++ b/installer/README.md @@ -1,22 +1,5 @@ # HNN Installation -Currently, HNN is only supported on Docker. Please refer to the link below for more information on installing HNN on either Mac or Windows. +HNN is currently supported on Docker. Please refer to the link below for more information on installing HNN on either Mac or Windows. [Docker](docker) - - -This directory contains instructions and files supporting installation of HNN on supported platforms. Click on the link below corresponding to your operating system: - -* [Windows](windows) -* [Mac](mac) -* [Ubuntu](ubuntu) -* [CentOS](centos) - -HNN also works on cloud and HPC environments: - -* [Amazon Web Services](aws) -* [Oscar (for Brown students, staff, faculty)](brown_ccv) - -If you are running into problems with the instructions given for your machine, we recommend using the VirtualBox VM with HNN pre-installed: - -* [HNN VirtualBox install instructions](virtualbox) From a57063cb48a01c7f5afaf89cf6235c25625395a0 Mon Sep 17 00:00:00 2001 From: Josh Lu Date: Wed, 6 Dec 2023 15:15:36 -0500 Subject: [PATCH 16/17] Update README.md --- installer/docker/README.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/installer/docker/README.md b/installer/docker/README.md index 722b1048..931504e7 100644 --- a/installer/docker/README.md +++ b/installer/docker/README.md @@ -1,8 +1,8 @@ # HNN Docker Container -### Windows Installation Process +## Windows Installation Process -## Part 1 Install WSL +### Part 1 Install WSL 1. Open the Command Prompt application. Can be found by searching `Command Prompt` in the Windows search bar. 2. Paste the following command to install Windows Subsystem for Linux (WSL) ``` @@ -27,7 +27,7 @@ wsl --install -## Part 2 Install Docker +### Part 2 Install Docker 1. Please install Docker Desktop from this link https://docs.docker.com/desktop/install/windows-install/ 2. Once installed, click on the newly added Docker Desktop icon on your computer to open up the application. 3. Press on the Settings Icon in the navigation bar to navigate to the Settings. Once there, click on the General tab. Make sure that `Use the WSL 2 Based Engine` is checked as shown in the screenshot below. @@ -42,7 +42,7 @@ wsl --install 8. To check if Docker is correctly installed, you can open up the Ubuntu terminal (application) and type `docker --version`, If done correctly, a version and build number of the software installed should be fed back. -## Part 3 Install Vcxsrv +### Part 3 Install Vcxsrv 1. Please install Vcxsrv https://sourceforge.net/projects/vcxsrv/ 2. Run the installer, choosing `C:\Program Files\VcXsrv` as the destination folder. 3. A new icon named `XLaunch` should now appear on your computer. Click on the icon to open up the application and continue with the installation steps. @@ -59,7 +59,7 @@ wsl --install ![Screenshot 2023-11-29 163550](https://github.com/jonescompneurolab/hnn/assets/34087669/d4c7341b-1b00-4721-b49d-79b5dd081047) -## Part 4 Configure and Run HNN Application +### Part 4 Configure and Run HNN Application 1. Open up a new Ubuntu terminal application, referenced in Step 3 of Part 1. (Note: ensure that the Ubuntu terminal is being used and not the Windows Powershell) 2. We will now download the source code that starts up the GUI. Paste this command to create a copy of the source code on your computer. ``` @@ -90,7 +90,7 @@ The resulting HNN GUI on initial startup. ![image](https://github.com/jonescompneurolab/hnn/assets/34087669/cb6f404c-d6df-45ef-ab80-cf85e293bf8b) -## Troubleshooting +### Troubleshooting If you run into the following error while running `./hnn_docker.sh start` ` @@ -105,11 +105,3 @@ If you run into the following error while running `./hnn_docker.sh start` xauth: (argv):1: couldn't query Security extension on display “:0” ` - Please double check that you have gone through the steps in Part 3 to correctly set up the Vcxsrv server. Also check that you have successfully ran the `configure_vcxsrv.sh` script from the previous Step 4 of this Part 4 of the installation. - - -export XAUTHORITY=/tmp/.Xauthority -export SYSTEM_USER_DIR="$HOME" -ssh -o SendEnv=DISPLAY -o SendEnv=XAUTHORITY -o SendEnv=SYSTEM_USER_DIR -o SendEnv=TRAVIS_TESTING -o PasswordAuthentication=no -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -v -i "SSH_PRIVKEY" -R 6000:127.0.0.1:6000 hnn_user@localhost -p 32791 -``` - -* Commands should be run from the HNN source code directory From 64761ba320293777578e4cd3ce40e21f229c0964 Mon Sep 17 00:00:00 2001 From: Josh Lu Date: Fri, 8 Dec 2023 13:47:50 -0500 Subject: [PATCH 17/17] Update README.md --- installer/docker/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/installer/docker/README.md b/installer/docker/README.md index 931504e7..c0dbd5dd 100644 --- a/installer/docker/README.md +++ b/installer/docker/README.md @@ -5,6 +5,8 @@ ### Part 1 Install WSL 1. Open the Command Prompt application. Can be found by searching `Command Prompt` in the Windows search bar. 2. Paste the following command to install Windows Subsystem for Linux (WSL) + +_Note: if WSL is already installed on your computer, please ensure it is WSL2 . WSL1 is incompatible with Docker install._ ``` wsl --install ```