Main to ag-dev

INSTALLATION.md

@@ -2,7 +2,7 @@
 
 We provide both a locally installable **desktop application** and a **cloud-based application**.
 
-The [NiChart cloud application](https://neuroimagingchart.com/portal), hosted via Amazon Web Services (AWS), deploys scalable infrastructure which hosts the *NiChart* tools as a standard web application accessible via the user’s web browser. **No install needed**, but it requires you to upload your data to the cloud-based NiChart server for us to process it. We do not access or use your data for any other purpose than to run your requested processing and/or provide support to you, and we regularly delete user data after inactivity. However, we recognize that data privacy agreements and related concerns may nevertheless restrict use of the cloud application. If that applies to you, we suggest that you install the desktop application. Below we provide detailed installation instructions.
+The [NiChart cloud application](https://neuroimagingchart.com/portal), hosted via Amazon Web Services (AWS), deploys scalable infrastructure which hosts the *NiChart* tools as a standard web application accessible via the user’s web browser. **No installation is needed**, but it requires you to upload your data to the cloud-based NiChart server for us to process it. We do not access or use your data for any other purpose than to run your requested processing and/or provide support to you, and we regularly delete user data after inactivity. However, we recognize that data privacy agreements and related concerns may nevertheless restrict use of the cloud application. If that applies to you, we suggest that you install the desktop application. Below we provide detailed installation instructions.
 
 In particular, if you don't have a GPU on your device, the cloud application is probably the easiest way for you to use the NiChart tools.
 
@@ -17,53 +17,70 @@ Windows users will likely need to first [install the Windows Subsystem for Linux
 
 On Windows, Docker is distributed as "Docker Desktop", an application which manages Docker on your system. 
 
-### Docker-based Installation
-
 #### Getting started
 
-First, if you're on Windows, open Docker Desktop. You can do this from the start/search menu or by clicking the Desktop shortcut if you selected that during installation. You should go into the settings using the gear icon on the top right, go to "General", and enable the settings "Use the WSL 2 based engine" and "Expose daemon on tcp://localhost:2375 without TLS" if they aren't already enabled (they might require you to restart). You should also see a green indicator on the bottom left which says "Engine running". If it's yellow, you need to wait for the service to start. Otherwise, you may need to troubleshoot your installation. 
+First, open Docker Desktop. You can do this from the start/search menu or by clicking the Desktop shortcut if you selected that during installation.
+
+You should go into the settings using the gear icon on the top right, go to "General", and enable the settings "Use the WSL 2 based engine" and "Expose daemon on tcp://localhost:2375 without TLS" if they aren't already enabled. Then go to the "Resources" tab and disable Resource Saver if it is enabled. You will probably need to restart after this to make sure all changes take effect. 
+
+When you return, you should also see a green indicator on the bottom left which says "Engine running". If it's yellow or says something else, you need to wait for the service to start. Otherwise, you may need to troubleshoot your Docker installation before continuing. 
 
 #### Choose a path to store results
 
-In this installation, NiChart runs inside a container, which is isolated from the rest of your computer to improve security. To have data persist across sessions, you need to designate a location on your computer to store this data. ****
+In this installation, NiChart runs inside a container, which is isolated from the rest of your computer to improve security. To have data persist across sessions, you need to designate a location on your computer to store this data.
 
 First, identify a path you want to use. In this demo we'll use "C:/Users/NiChart_Developer/Desktop/DEMODATA", but yours will vary as you can choose any folder you like. On Windows, you can navigate to a folder, then click "copy path" in the file explorer to get your path.
 
 **Please make sure that the path you use does not already contain important data**. NiChart will not try to delete existing data, but it is good practice to select a new, empty folder.
 
 Write down your path (for example, copy & paste it into Notepad).
 
-Now, in your path text, replace "C:/"with "/mnt/c/". You can do the same for any other drive letter, so "D:/" becomes "/mnt/d". In our example, we end up with "/mnt/c/Users/NiChart_Developer/Desktop/DEMODATA". 
+#### Download the installer
+Make sure you are connected to the internet in order to download the application.
 
-Write down this converted path as we will use it later. 
+Go to https://github.com/CBICA/NiChart_Project/blob/main/installers/install_nichart_docker_windows.ps1 and download the file (Doable with either the three dots icon on the top-right -> Download, or the separate Download button a litte below that.
 
-#### Running the installer
+Open up the file explorer to find where you downloaded this file. Hold Shift and right click in that folder. You should see "Open PowerShell window here". Click that option.
 
-Make sure you are connected to the internet in order to download the application. Then, open a terminal.
-
-(On Windows, search "terminal", open the application that looks like a black box with a white ">_" in it. At the top of the window that appears will be a tab indicating Windows Powershell.
-Click the down arrow next to that tab to expand your terminal options, and select Ubuntu (or, if you changed the default distribution, select whichever distribution you selected while installing WSL).
-A new terminal will open in a different color and you should see something like "root@username:~#". Stay on this tab for the rest of the instructions.)
+#### Running the installer
 
-Run the following commands to download the installer and make it runnable:
+Make sure the PowerShell terminal from the last step is open.
 
+Then run this command, **making sure to replace** DATA_DIR with the data path you chose earlier:
 ```
-wget https://raw.githubusercontent.com/CBICA/NiChart_Project/main/installers/install_nichart_docker_linux.sh.sh
-chmod +x install_nichart_docker_linux.sh
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install_nichart_docker_windows.ps1 DATA_DIR --distro Ubuntu
 ```
+(Note that if you chose a different distribution for your WSL installation, you can designate that with --distro in the command above. Just replace "Ubuntu" with whatever you chose.)
 
-Then run this command, **making sure to replace** /path/to/data with the data path you chose earlier:
-```
-./install_nichart_docker_linux.sh /path/to/data
-```
+This command might take a while to finish while it downloads the NiChart tools.
+
+#### Running the application
 
-In our example, the command becomes `./install_nichart_docker_linux.sh /mnt/c/Users/NiChart_Developer/Desktop/DEMODATA`.
+To start NiChart, double-click the NiChart shortcut which the installer created on your desktop. It should launch your browser automatically. If not, open your browser and go to http://localhost:8501 . If you see the NiChart survey, NiChart is successfully installed.
 
-This command might take a while to finish.
+#### Updating
+
+To update NiChart, just run the installer again the same way you ran it above and the newest NiChart components will be installed. 
+
+To save space, you may want to clean up your Docker images to remove older tool versions. For more information on managing Docker images, see the [Docker image docs](https://docs.docker.com/reference/cli/docker/image/).
+
+## Linux Instructions
+
+You will need to install Docker first and restart to make sure services are running properly.
+
+First identify a data path where you want to persist NiChart data. We'll call that ${DATA_DIR}.
+
+You will want to download and run the linux installer script. To do this, cd to your desired install directory and run the below. (Remember to set ${DATA_DIR} or replace it with your desired path.)
+
+```
+wget https://raw.githubusercontent.com/CBICA/NiChart_Project/main/installers/install_nichart_docker_linux.sh
+chmod +x install_nichart_docker_linux.sh
+./install_nichart_docker_linux.sh ${DATA_DIR}
+```
 
 #### Running the application
 
-To test that NiChart is installed correctly, run the following command.
+Run the script run_nichart.sh that the installer created in the same directory:
 
 ```
 ./run_nichart.sh
@@ -72,23 +89,15 @@ To test that NiChart is installed correctly, run the following command.
 This will start the NiChart server on your machine which you can then access from your web browser.
 When you start the server, a few links will appear, including a localhost one: http://localhost:8501 
 
-You can click that link or copy-paste it into a browser to access the local NiChart server. If you see the front page, congratulations! NiChart is installed.
-
-The NiChart server will automatically stop when you close that terminal window.
-
-Whenever you want to run NiChart again, either:
+You can click that link or copy-paste it into a browser to access the local NiChart server. If you see the survey page, congratulations! NiChart is succesfully installed.
 
-1. Open up the Ubuntu terminal as described above and run the same command. Then open your browser and go to http://localhost:8501.
+To stop the NiChart server, run "docker stop nichart_server". 
 
-2. Click the desktop shortcut if you made one (see below).
+#### Updating
 
-#### Creating a Windows desktop shortcut (Optional)
-This optional step creates a shortcut on the Windows desktop to NiChart.
+To update NiChart, just download and re-run the latest installer.
 
-
-
-## Linux Instructions
-Linux instructions are quite similar to the Windows instructions, except that there is no need for WSL and no need to convert the path specially. All commands will need to be run from the terminal and there is no Docker Desktop configuration.
+To save space, you may want to clean up your Docker images to remove older tool versions. For more information on managing Docker images, see the [Docker image docs](https://docs.docker.com/reference/cli/docker/image/).
 
 # Can't use Docker?
-We aim to soon provide compatibility with Singularity/Apptainer runtimes for users in computing environments where Docker is disallowed. Please check in regularly for updates.
+We aim to soon provide compatibility with Singularity/Apptainer runtimes for users in computing environments where Docker is disallowed or where other related policies prevent running NiChart due to required privileges. Please check in regularly for updates.

installers/install_nichart_docker_linux.sh

@@ -77,7 +77,7 @@ APP_URL_DEFAULT="http://localhost:8501/"
 
 CONTAINER_NAME="nichart_server"
 
-RUN_ARGS=(--rm -it --name "${CONTAINER_NAME}")
+RUN_ARGS=(--rm -d --name "${CONTAINER_NAME}")
 RUN_ARGS+=(--privileged -p 8501:8501 -v /usr/bin/docker:/usr/bin/docker -v /var/run/docker.sock:/var/run/docker.sock)
 RUN_ARGS+=(-v "${DATA_DIR}:/app/output_folder:rw")
 
@@ -95,7 +95,6 @@ is_wsl() {
 }
 
 open_browser() {
-  local url="$1"
   if is_wsl; then
     # Use Windows PowerShell to open the default browser from WSL
     if command -v powershell.exe >/dev/null 2>&1; then
@@ -112,6 +111,22 @@ open_browser() {
   fi
 }
 
+CONTAINER_NAME="nichart_server"
+
+container_running() {
+  docker ps --format '{{.Names}}' --filter "name=^/${CONTAINER_NAME}$" | grep -qx "${CONTAINER_NAME}"
+}
+
+container_exists() {
+  docker ps -a --format '{{.Names}}' --filter "name=^/${CONTAINER_NAME}$" | grep -qx "${CONTAINER_NAME}"
+}
+
+if container_running; then
+  echo "[Run] Container '${CONTAINER_NAME}' already running; opening browser."
+  open_browser
+  exit 0
+fi
+
 msg "Running command: docker run ${RUN_ARGS[@]} ${APP_IMAGE} ${APP_CMD[@]} $@"
 # Start container
 msg "Starting container '${CONTAINER_NAME}' from image '${APP_IMAGE}'..."

installers/install_nichart_docker_windows.ps1

@@ -30,23 +30,19 @@ function Assert-WSLPresent {
 }
 
 function Get-DefaultDistro {
-  # 'wsl -l -v' marks default with a '*'
   $out = & $script:wslExe -l -v 2>$null
-  if ($LASTEXITCODE -ne 0 -or -not $out) {
-    # fallback: 'wsl -l' may include '(Default)'
-    $out = & $script:wslExe -l 2>$null
-  }
-  if (-not $out) { Fail "Unable to query WSL distros. Is WSL installed and initialized?" }
+  if (-not $out) { $out = & $script:wslExe -l 2>$null }
+  if (-not $out) { Fail "Unable to query WSL distros." }
+
+  # Look for the line that starts with '* '
   foreach ($line in $out) {
-    if ($line -match '^\*?\s*([^\s].*?)(\s+\(Default\))?\s+(\d+)?' -or
-        $line -match '^\*\s+(.+)$') {
-      $name = $Matches[1]
-      if ($line -like '*Default*' -or $line -like '*`**') { return $name.Trim() }
+    if ($line -match '^\*\s+(.+?)(\s{2,}|\s+\d+|\s+\(Default\)|$)') {
+      return $Matches[1].Trim()
     }
   }
-  # If no marker found, pick the first non-header line from `wsl -l -q`
+  # Fallback: first non-empty from -q
   $q = & $script:wslExe -l -q 2>$null | Where-Object { $_ -and $_.Trim() -ne '' }
-  if (-not $q) { Fail "No WSL distributions found. Install a distro from the Store and retry." }
+  if (-not $q) { Fail "No WSL distributions found." }
   return $q[0].Trim()
 }
 
@@ -81,31 +77,36 @@ Write-Host "Windows path: $DataPath"
 Write-Host "WSL path:     $wslDataPath"
 
 # Where app/script will live inside WSL
-$AppDir         = "/home/\$USER/NiChart"
+$AppDir         = "/home/NiChart"
 $RunScriptPath  = "$AppDir/run_nichart.sh"
 $InstallLogPath = "$AppDir/install.log"
 
 # Compose the bash payload to run inside the distro
-$bashBody = @"
+$bashBody = @'
 set -euo pipefail
 
 # Example: prepare app dir and a tiny demo run script if it doesn't exist
-mkdir -p "$AppDir"
+mkdir -p "{APPDIR}"
 
 # Persist the provided data path for your app to read later
-printf '%s\n' "$wslDataPath" > "$AppDir/DATA_PATH"
+printf '%s\n' "{WPATH}" > "{APPDIR}/DATA_PATH"
 
 ### INSTALL STEPS ###
 # Get current installer from NiChart_Project and run it
-cd "$AppDir"
+cd "{APPDIR}"
 wget https://raw.githubusercontent.com/CBICA/NiChart_Project/main/installers/install_nichart_docker_linux.sh
 chmod +x install_nichart_docker_linux.sh
-./install_nichart_docker_linux.sh "$wslDataPath"
+./install_nichart_docker_linux.sh "{WPATH}"
+rm -f ./install_nichart_docker_linux.sh
 chmod +x run_nichart.sh
 ######################
 
-echo "\$(date -Is) Install completed. Data path: $wslDataPath" >> "$InstallLogPath"
-"@
+echo "$(date -Is) Install completed. Data path: {WPATH}" >> "{APPDIR}/install.log"
+'@
+
+$bashBody = $bashBody.
+  Replace('{APPDIR}', $AppDir).
+  Replace('{WPATH}',  $wslDataPath)
 
 # Invoke bash -lc "<payload>" in the chosen distro
 Write-Host "Running installer steps inside WSL..."
@@ -124,6 +125,20 @@ switch ($LASTEXITCODE) {
 
 # Create a Windows shortcut on the Desktop that launches the WSL script
 $desktop = [Environment]::GetFolderPath('Desktop')
+
+$iconUrl = "https://raw.githubusercontent.com/CBICA/NiChart_Project/refs/heads/main/resources/images/nichart1.ico"
+$iconPath = Join-Path $env:LOCALAPPDATA "NiChart/nichart.ico"
+
+
+New-Item -ItemType Directory -Path (Split-Path $iconPath) -Force | Out-Null
+
+try {
+    Invoke-WebRequest -Uri $iconUrl -OutFile $iconPath -UseBasicParsing
+} catch {
+    Write-Warning "Could not download icon from $iconUrl. Shortcut will use default WSL icon."
+    $iconPath = "$env:SystemRoot\System32\wsl.exe"  # fallback
+}
+
 $shortcutName = "NiChart.lnk"
 $shortcutPath = Join-Path $desktop $shortcutName
 
@@ -145,7 +160,7 @@ $shortcut.Arguments = ($argList -join ' ')
 $shortcut.WorkingDirectory = $desktop
 $shortcut.WindowStyle = 1
 $shortcut.Description = "Launch NiChart inside $selectedDistro"
-$shortcut.IconLocation = "$env:SystemRoot\System32\wsl.exe,0"
+$shortcut.IconLocation = "$iconPath"
 $shortcut.Save()
 
 if (-not (Test-Path $shortcutPath)) { Fail "Failed to create shortcut at $shortcutPath." }