-
Notifications
You must be signed in to change notification settings - Fork 25
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
add vcxsrv script #341
Open
jashlu
wants to merge
17
commits into
jonescompneurolab:master
Choose a base branch
from
jashlu:add_vcxsrv_script
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
add vcxsrv script #341
Changes from 16 commits
Commits
Show all changes
17 commits
Select commit
Hold shift + click to select a range
039779f
add vcxsrv script
jashlu 80f08d9
Update README
jashlu 862fe3e
update script
jashlu bfab4a8
add screenshots
jashlu 6394148
fix text
jashlu 6401db9
another round of edits for README
jashlu 4dbc205
Update README.md
jashlu 328ebaa
Update README.md
jashlu 61a23fd
Update installer/docker/README.md
jashlu af8cfa0
Update installer/docker/README.md
jashlu 1cefaa0
Update README.md
jashlu c9a182a
Update installer/README.md
jashlu c9afb8c
Update installer/README.md
jashlu 3160c65
Update scripts/configure_vcxsrv.sh
jashlu de68a6c
Update README.md
jashlu a57063c
Update README.md
jashlu 64761ba
Update README.md
jashlu File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,17 +1,5 @@ | ||
| # HNN Installation | ||
|
|
||
| This directory contains instructions and files supporting installation of HNN on supported platforms. Click on the link below corresponding to your operating system: | ||
| HNN is currently supported on Docker. Please refer to the link below for more information on installing HNN on either Mac or Windows. | ||
|
|
||
| * [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) | ||
| [Docker](docker) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,81 +1,107 @@ | ||
| # HNN Docker Container | ||
|
|
||
| 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. | ||
| ## Windows Installation Process | ||
|
|
||
| ## Pulling the prebuilt Docker container from Docker Hub | ||
| ### 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 | ||
| ``` | ||
|  | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
| Linux container (built from release branches): | ||
|  | ||
|
|
||
| ```bash | ||
| docker pull jonescompneurolab/hnn | ||
| ``` | ||
| 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 | ||
|
|
||
| Linux container (built from master): | ||
| 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. | ||
|
|
||
|  | ||
|
|
||
| ```bash | ||
| docker pull jonescompneurolab/hnn:master | ||
| ``` | ||
| 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. | ||
|
|
||
|  | ||
|
|
||
| Windows container: | ||
|
|
||
| ```bash | ||
| docker pull jonescompneurolab/hnn:win64 | ||
| ``` | ||
|
|
||
| ## Building HNN container | ||
| ### 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. | ||
|
|
||
|  | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
|  | ||
|
|
||
| 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' | ||
| 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. | ||
|
|
||
| ```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: | ||
| ### 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'. | ||
|
|
||
| ```bash | ||
| docker build --tag jonescompneurolab/hnn:win64 -f installer/windows/Dockerfile installer/docker | ||
| ``` | ||
|  | ||
|
|
||
| ## Starting HNN container | ||
| 5. Select "Start no client" and click 'Next'. | ||
|
|
||
| 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 | ||
| ``` | ||
| 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. | ||
|
|
||
| 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. | ||
| ### 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. | ||
| ``` | ||
| 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 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. | ||
|  | ||
|
|
||
| 5. Now run the following command to start up the HNN GUI. | ||
| ``` | ||
| ./hnn_docker.sh start | ||
| ``` | ||
|
|
||
| Using SSH can be controlled by the environment variable USE_SSH | ||
| Your terminal should display the following messages if it successfully started up the HNN GUI. | ||
|
|
||
| ### 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 | ||
| ``` | ||
| The resulting HNN GUI on initial startup. | ||
|
|
||
| * 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 '' | ||
| ### Troubleshooting | ||
| If you run into the following error while running `./hnn_docker.sh start` | ||
|
|
||
| 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 | ||
| ``` | ||
| ` | ||
| 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` | ||
|
|
||
| * Commands should be run from the HNN source code directory | ||
| ` | ||
| 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. | ||
hollandjg marked this conversation as resolved.
Show resolved
Hide resolved
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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!" |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there a way to manually specify WSL2?
I think this is installed by default now but we've run into a few folks that had WSL1 and couldn't install docker
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just for clarification, are u saying folks who already had WSL1 before attempting this installation process were having errors installing docker? Like you said,
wsl --installshould by default install WSL2 so users who are following this tutorial, starting from scratch, should have WSL2 installed.I could add some additional instructions here on how to upgrade from WSL1 to WSL2 if that helps (and mention that WSL2 is required over WSL1)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perhaps we could just say something like:
Note: if WSL is already installed on your computer, please ensure it is WSL2 . WSL1 is incompatible with Docker install.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sounds good, i'll add that in