jonescompneurolab / hnn

The Human Neocortical Neurosolver (HNN) is a software tool that gives researchers/clinicians the ability to develop/test hypotheses on circuit mechanisms underlying EEG/MEG data.
http://hnn.brown.edu
Other
80 stars 25 forks source link

build: update dockerfile #337

Closed jashlu closed 11 months ago

jashlu commented 1 year ago

Prereqs for MacOS

Prereqs for Windows

Starting up HNN-application for MacOS

Starting up HNN-application for Windows

jasmainak commented 1 year ago

Let us know when this is ready @jashlu ! Looks good so far

rythorpe commented 1 year ago

A few high-level questions:

  1. I noticed that you specified VS Code is a prereq for Windows. Is this necessary?
  2. Have you tested that a simulation runs correctly after loading the GUI? I only ask because we've run into weird dependency issues before, particularly with MPI.
jashlu commented 1 year ago

A few high-level questions:

  1. I noticed that you specified VS Code is a prereq for Windows. Is this necessary?
  2. Have you tested that a simulation runs correctly after loading the GUI? I only ask because we've run into weird dependency issues before, particularly with MPI.

@rythorpe Hi Ryan, thanks for the comments, 1. Definitely not, I just found it easier to use vscode's terminal to access wsl and run the script, I can adjust the instructions to make this a recommendation instead.

  1. As for the simulations, I haven't had experience using the app, are there any instructions you could reference for running a simulation on the HNN app? More than happy to try it out. Thank you
rythorpe commented 1 year ago

@rythorpe Hi Ryan, thanks for the comments, 1. Definitely not, I just found it easier to use vscode's terminal to access wsl and run the script, I can adjust the instructions to make this a recommendation instead.

The vast majority of our Windows users (particularly for the GUI) know very little about programming and generally will not know how to access terminal or what vscode even is. Some of this is unavoidable, but if there's anyway we can simplify the dependencies and installation process here, that would be preferable.

IDK if you've seen this yet, but here's our old installation documentation. It might be helpful even if it's just to compare between what the process used to look like and what it will be after this PR.

  1. As for the simulations, I haven't had experience using the app, are there any instructions you could reference for running a simulation on the HNN app? More than happy to try it out. Thank you

You should be able to run the default simulation by clicking "Run Simulation" near the top of the GUI window. A small text box should appear as the simulation is running and will disappear as soon as the simulation is complete. If you want more details, here's an in-depth tutorial that describes how to use the GUI. It's pretty lengthy, so we can also schedule a quick Zoom call if you want a real-time demo or wish to chat futher.

jashlu commented 1 year ago

@rythorpe Hi Ryan, thanks for the comments, 1. Definitely not, I just found it easier to use vscode's terminal to access wsl and run the script, I can adjust the instructions to make this a recommendation instead.

The vast majority of our Windows users (particularly for the GUI) know very little about programming and generally will not know how to access terminal or what vscode even is. Some of this is unavoidable, but if there's anyway we can simplify the dependencies and installation process here, that would be preferable.

IDK if you've seen this yet, but here's our old installation documentation. It might be helpful even if it's just to compare between what the process used to look like and what it will be after this PR.

  1. As for the simulations, I haven't had experience using the app, are there any instructions you could reference for running a simulation on the HNN app? More than happy to try it out. Thank you

You should be able to run the default simulation by clicking "Run Simulation" near the top of the GUI window. A small text box should appear as the simulation is running and will disappear as soon as the simulation is complete. If you want more details, here's an in-depth tutorial that describes how to use the GUI. It's pretty lengthy, so we can also schedule a quick Zoom call if you want a real-time demo or wish to chat futher.

Thanks for the resources, i'll go ahead focus first on running the default simulation, to make sure there are no further problems. I will get back to you all if I run into any problems or any questions. If everything is fine, I will simplify the installation process next. Thanks!

jashlu commented 1 year ago

Recording 2023-11-03 130119.zip

Hi @rythorpe @jasmainak I have a screen recording here of me testing a sample simulation. Seems to be running without any problems, let me know what you think! I am free to chat if you want to go over it, or discuss anything else. Thanks!

Also please let me know what your preferred mode of communication is, I can do email, slack, github, or anything else

rythorpe commented 12 months ago

After a brief discussion with @stephanie-r-jones today, we realized that we should be updating the docker file for our pre-hnn-core branch, not master. Apologies @jashlu for not clarifying this sooner.

A little more context: the last major development changes to master included the integration of hnn-core, which effectively added hnn-core as a dependency. The version we want to maintain installation capabilities for, however, is the maintenance branch pinned right before this integration, which is more stable.

jashlu commented 12 months ago

After a brief discussion with @stephanie-r-jones today, we realized that we should be updating the docker file for our pre-hnn-core branch, not master. Apologies @jashlu for not clarifying this sooner.

A little more context: the last major development changes to master included the integration of hnn-core, which effectively added hnn-core as a dependency. The version we want to maintain installation capabilities for, however, is the maintenance branch pinned right before this integration, which is more stable.

@rythorpe I see, thanks for letting me know. I'll try migrating the changes i made for this dockerfile to the pre-hnn-core branch and see how far I can get.

Additionally, as I am working on simplifying the installation process, I envision that users will still have to go through cloning the repository so that they can run the hnn_docker.sh script. No need for VScode, but I do need that script to run the simulation. What do you think of that?

jashlu commented 12 months ago

@rythorpe Hi, I've tested the updated dockerfile you see in this PR in the maint/pre-hnn-core branch and the results are the same, the gui is able to start. Please let me know if that is all, then I will make a PR for maint/pre-hnn-core

jashlu commented 12 months ago

Windows Installation Process

Part 1

  1. Open command Prompt

  2. Run the following command to install Windows Subsystem for Linux (WSL)

    wsl --install

    image

  3. Once the installation is done, you will see that an Ubuntu application is also downloaded. This can be found in Settings > Apps > Installed apps or simply by searching Ubuntu in the Windows search bar. image

  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

  6. Then open up the Ubuntu application that was installed alongside WSL.

  7. The very first time you open this application up, you will see instructions prompting you to create a new UNIX username and password. Afterwards, it will show you an installation successful message. image

Part 2

  1. Please install Docker Desktop https://docs.docker.com/desktop/wsl/#download

  2. Once installed, 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

  4. Next, click on Resources > WSL Integration

  5. Inside here, make sure that all Ubuntu options are toggled. Then press apply & restart. image

  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

  1. Please install Vcxsrv https://sourceforge.net/projects/vcxsrv/

  2. Run the installer, choosing "C:\Program Files\VcXsrv" as the destination folder.

  3. Start the XLaunch desktop app from the VcXsrv folder in the start menu.

  4. Choose "Multiple windows". Choose '0' for the "Display number". Click 'Next'.

  5. Select "Start no client" and click 'Next'.

  6. Important: under "Extra settings" make sure that "Disable access control" is checked.

  7. For the following step, you will need the IP address of your local machine. To find it, open up Settings > Network & internet > Wi-Fi > Hardware properties and look for IPv4 address: image

  8. Now open up the ubuntu application terminal and run the following commands. Comments above each command help to provide additional details. Original source of instructions comes from https://sourceforge.net/p/vcxsrv/wiki/VcXsrv%20%26%20Win10/.

    
    # in the following command, replace the NN.NN.NN.NN with the IPv4 addess that you've obtained in the previous step. 
    export DISPLAY=NN.NN.NN.NN:0

you can ignore any errors that arise from running the following command.

sudo apt install -y xauth coreutils gawk gnome-terminal

running the following command should display nothing, to show you that you do not have credentials set up yet.

xauth list

run the following command, with {some-pass-phrase} replaced by any phrase. Ex. hnn-app

magiccookie=$(echo '{some-pass-phrase}'|tr -d '\n\r'|md5sum|gawk '{print $1}')

run the following

xauth add "$DISPLAY" . "$magiccookie"

running this command again, you will see that something shows up, displaying the new credentials you have set up.

xauth list

run the following commands

userprofile=$(wslpath $(/mnt/c/Windows/System32/cmd.exe /C "echo %USERPROFILE%" | tr -d '\r\n')) cp ~/.Xauthority "$userprofile


**Part 4**
1. Open up a new Ubuntu terminal application. 
2. We will now download the code that will run the program to start up the GUI. 
3. Run this command to create a copy of the source code in your computer.

Git clone https://github.com/jonescompneurolab/hnn.git

4. Run the following command to navigate to inside the repository in your Ubuntu terminal. 

cd hnn

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)

**Part 4 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. 
jashlu commented 12 months ago

@rythorpe Hi, please let me know what you think of the updated installation process, thanks

rythorpe commented 12 months ago

This is very thorough @jashlu, thank you! I don't have a Windows machine to test this on at the moment, but I think we should move forward and create follow-up issues should they arise. @jasmainak @ntolley wdyt? On a slightly broader note, I worry this installation process will be too complicated for the average Windows user. Perhaps we can discuss this in our next HNN meeting and decide if maintaining/promoting a Docker installation method with will give us what we need.

jashlu commented 12 months ago

This is very thorough @jashlu, thank you! I don't have a Windows machine to test this on at the moment, but I think we should move forward and create follow-up issues should they arise. @jasmainak @ntolley wdyt? On a slightly broader note, I worry this installation process will be too complicated for the average Windows user. Perhaps we can discuss this in our next HNN meeting and decide if maintaining/promoting a Docker installation method with will give us what we need.

Sounds good, look forward to hearing from you guys! Cheers

ntolley commented 11 months ago

Thanks @jashlu for this work! Agree with @rythorpe the typical user might have trouble with this install process. Might just be unavoidable with using docker/WSL but we should discuss if it's possible to streamline any further.

jasmainak commented 11 months ago

please go ahead and merge @ntolley @rythorpe if you guys are happy ... I let you take care of this!

rythorpe commented 11 months ago

Done! Thanks @jashlu!

jashlu commented 11 months ago

Thank you guys!

dylansdaniels commented 9 months ago

I was able to get this working on Windows.

A couple of notes here:

  1. Weirdly "~/.Xauthority" "${userprofile}/." did not work for me - I had to specify the path to .Xauthority directly (cp "/home/dylansdaniels/.Xauthority" "${userprofile}/.")
  2. The first time I did this, I mis-specified the IP address, missing the ":0" at the end of "DISPLAY=NN.NN.NN.NN:0" in part 3 -> we might want to highlight that more, as I feel like it's an easy thing to miss
  3. the instructions in update-pre-hnn-core reference the configure_vcxsrv.sh file. However, the instructions also have you clone / work from the master branch, which doesn't have that file so far as I can tell?