Merge pull request #78 from BiAPoL/elephant-installation-windows

Add new blog post about Elephant installation on windows

docs/_toc.yml

@@ -7,6 +7,7 @@ parts:
 - caption: Blog Posts
   chapters:
   # Add new chapters here (recent first)
+  - file: stefan_hahmann/elephant_server_installation_windows/readme
   - file: stefan_hahmann/github_desktop_jupyter_notebook/readme
   - file: johannes_mueller/qtdesigner_and_magicgui/Readme
   - file: mara_lampert/getting_started_with_mambaforge_and_python/readme

docs/intro.md

@@ -12,41 +12,19 @@ If you have feedback or suggestions, if spotted a typo, broken link or misleadin
 
 ### [Running bio image analysis workflows on your machine](stefan_hahmann/github_desktop_jupyter_notebook/readme)
 
+<small>[Stefan Hahmann](stefan_hahmann/readme), April 24th, 2024</small><br>
+<img src="images/elephant-logo.png" width="100" align="right"><p>ELEPHANT is a platform for 3D cell tracking, based on incremental and interactive deep learning. This post will show you how to install the ELEPHANT server component on a Windows machine.</p>
+
 <small>[Stefan Hahmann](stefan_hahmann/readme), December 21st, 2023</small><br>
 <img src="images/jupyter_logo.png" width="100" align="right"><p>Jupyter Notebooks may be used to run bio image analysis workflows on your machine with your own data. They are a great tool to share workflows with others. This post will show you how to run workflows that have been shared via GitHub. </p>
 
+<small>[Johannes Soltwedel](johannes_mueller/readme), Mai 12th, 2023</small><br>
+<img src="images/qt_logo.png" width="100" align="right"><p>This blog post will give you a quick introduction on how to combine two great tools for the creation of graphical user interfaces in napari: The [Qt Designer](https://doc.qt.io/qt-6/qtdesigner-manual.html) and [magicgui](https://pyapp-kit.github.io/magicgui/). </p>
+
 ### [Getting started with Miniforge and Python](mara_lampert/getting_started_with_mambaforge_and_python/readme)
 <small>[Mara Lampert](mara_lampert/readme), January 26th, 2023</small><br>
 <img src="images/mamba_logo.png" width="100" align="right"><p>This post will help you to get started with Python using Miniforge. More precisely, you will learn how to install Miniforge, how to create and use conda environments and know about some very important packages. </p>
 
-### [Using GPU-accelerated image processing on the TUD HPC cluster](till_korten/devbio-napari_cluster/readme)
-<small>[Till Korten](till_korten/readme), Oct 21st, 2022</small><br>
-<img src="images/2290861_computer_laptop_network_notebook_share_icon.png" width="100" align="right"><p>The High Performance Computing cluster at the compute center (ZIH) of the TU Dresden provides a lot of computational resources including GPU support, which we can use for analyzing data in the life-sciences.</p>
-
-### [Setting up GPU-accelerated image processing on the TUD HPC cluster](till_korten/devbio-napari_cluster_setup/readme)
-<small>[Till Korten](till_korten/readme), July 29th, 2022</small><br>
-<img src="images/2290861_computer_laptop_network_notebook_share_icon.png" width="100" align="right"><p>The High Performance Computing cluster at the compute center (ZIH) of the TU Dresden provides a lot of computational resources including GPU support, which we can use for analyzing data in the life-sciences.</p>
-
-### [Running Deep-learning Scripts in the BiA-PoL Omero Server](marcelo_zoccoler/omero_scripts/readme)
-<small>[Marcelo Zoccoler](marcelo_zoccoler/readme), May 2nd, 2022</small><br>
-<img src="images/ome-logomark.png" width="99" align="right"><p>This blog post explains how to run omero scripts in the BiA-PoL omero server. In this example, we execute a script on the server that runs a 2D [Stardist](https://github.com/stardist/stardist) model on a sample image.<p>
-
-
-### [Mini-Sabbatical Experience at Bia-PoL](marcelo_zoccoler/mini_sabbatical_rike/Readme)
-<small>Friederike Kessel, February 28th, 2022</small><br>
-<img src="images/2290861_computer_laptop_network_notebook_share_icon.png" width="100" align="right"><p>This is a blog post about the personal experience of Rike, a post-doc who had just finished her PhD at the University Clinic in Dresden. She spent a two weeks training period at BiA-PoL working with image analysis.</p>
-
-
-### [Getting started with Python and Anaconda](johannes_mueller/anaconda_getting_started/Readme)
-<small>[Johannes Müller](johannes_mueller/Readme), January 26th, 2022</small><br>
-<img src="images/python_logo.png" width="100" align="right"><p>This post will help you to get started with using Python. More specifically, it will help you set up Anaconda environments which can be used to control installed packages effectively.</p>
-
-
-### [GUIs: Creating graphical user interfaces with/for Python, Part IV](marcelo_zoccoler/entry_user_interf4/Readme)
-<small>[Marcelo Zoccoler](marcelo_zoccoler/readme), [Johannes Müller](/johannes_mueller/Readme), December 15th, 2021</small><br>
-<img src="images/napari_logo.png"  width="100" align="right"><p>Last part of this series, this post will teach you how to turn your napari GUI/widget into a napari plugin and publish it on Pypi, so everyone can access it, install it and benefit from your contribution.</p>
-
-
 Find more blog posts on the left sidebar.
 Enjoy reading!
 

docs/stefan_hahmann/elephant_server_installation_windows/readme.md

@@ -0,0 +1,183 @@
+# Installation of Elephant Server on Windows
+
+[Stefan Hahmann](../readme.md), April 24th 2024
+[Johannes Soltwedel](../../johannes_mueller/Readme.md), April 24th 2024
+
+## Introduction
+
+![fiji.png](images/fiji.png)
+![mastodon.png](images/mastodon.png)
+![elephant-logo.png](images/elephant-logo.png)
+
+[ELEPHANT](https://elephant-track.github.io/#/v0.5/) is a platform for 3D cell tracking, based on incremental and interactive deep learning.
+It implements a client-server architecture. The client application is implemented by extending [Fiji](https://imagej.net/software/fiji/downloads)/[Mastodon](https://mastodon.readthedocs.io/en/latest/), providing a user interface for annotation, proofreading and visualization.
+The server is built as a web application that serves deep learning-based algorithms.
+
+Before installing Elephant on a powerful workstation or server, you may wish to try it out locally on your machine. This blog post will show you how you can do so, if you are using a Windows machine.
+
+## Prerequisites
+
+### Docker Desktop
+
+![docker-logo-blue.png](images/docker-logo-blue.png)
+
+[Docker Desktop](https://www.docker.com/products/docker-desktop) is a tool that allows you to run Docker containers on your local machine. 
+Docker containers are lightweight, standalone, executable packages of software that include everything needed to run an application: code, runtime, system tools, system libraries and settings. 
+Docker Desktop is available for Windows and Mac. You can download it [here](https://www.docker.com/products/docker-desktop).
+Please make sure that you have installed and started Docker Desktop before proceeding. You will need to sign in to Docker Desktop with your Docker account.
+
+### Windows Subsystem for Linux (WSL)
+
+![Windows_Subsystem_for_Linux_logo.png](images/Windows_Subsystem_for_Linux_logo.png)
+
+[Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/) is a compatibility layer for running Linux binary executables natively on Windows machines.
+It allows you to run a Linux distribution on your Windows machine.
+You can install WSL by following the instructions [here](https://docs.microsoft.com/en-us/windows/wsl/install).
+
+Open a console (press `Windows button`, type `cmd` and press `Enter`) and run the following command to install WSL:
+
+```console
+wsl --install
+```
+
+This will install the latest version of WSL and Ubuntu as the current default WSL distribution on your machine. By the time of writing this blog post, the default distribution is Ubuntu 22.04 LTS.
+You can check the installation success, if you open a Linux terminal by pressing `Windows button`, typing `wsl` and pressing `Enter`.
+
+You should also check, if the version number of WSL is 2. You can do this by running the following command in the console:
+
+```console
+wsl -l -v
+```
+Expected output:
+![wsl_l_v.png](images/wsl_l_v.png)
+
+If the version number of the Ubuntu distribution is not 2, you can upgrade it by running the following command in the Linux terminal:
+
+```console
+wsl --set-version Ubuntu-22.04 2
+```
+
+Do also check the WSL integration in Docker Desktop by opening Docker Desktop and navigating to `Settings` > `Resources` > `WSL Integration`. 
+Make sure that the checkbox for the Ubuntu distribution is checked:
+![docker-wsl-integration.PNG](images/docker-wsl-integration.png)
+
+To check if Docker is running correctly with the WSL, you can run the following command from the console:
+
+```console
+docker run hello-world
+```
+Expected output:
+![docker-hello-world.png](images/docker-hello-world.png)
+
+### Elephant Installation Files
+
+Download the Elephant installation files from the [Elephant GitHub repository](https://github.com/elephant-track/elephant-server/archive/refs/heads/main.zip). Unzip the files to a folder on your local machine, e.g. `C:\elephant-server`.
+
+Open a console (press `Windows button`, type `cmd` and press `Enter`) and navigate to the folder where you have unzipped the Elephant installation files.
+Start `wsl` by typing `wsl` and pressing `Enter`.
+
+![start-wsl.png](images/start-wsl.png)
+
+You can check, if the correct Linux distribution is running:
+```console
+hostnamectl
+```
+Expected output:
+![hostnamectl.png](images/hostnamectl.png)
+
+### GPU Support for machines with Nvidia GPUs
+
+![nvidia.png](images/nvidia.png)
+
+If you have a machine with an Nvidia GPU, you can use the GPU to accelerate the deep learning algorithms in Elephant.
+You need to install the official Nvidia driver for your GPU. You can download the driver from the [Nvidia website](https://www.nvidia.com/Download/index.aspx).
+Furthermore, you need to install CUDA. You can download CUDA from the [Nvidia website](https://developer.nvidia.com/cuda-downloads).
+
+## Creating the Elephant Server
+
+Open a console (press `Windows button`, type `cmd` and press `Enter`) and navigate to the folder where you have unzipped the Elephant installation files.
+Start `wsl` by typing `wsl` and pressing `Enter`.
+
+Build the Elephant Docker image by running the following command (it may take some time to download the required files):
+Including `sudo` may not be required on every machine.
+
+```console
+sudo make build
+```
+If you get an error message that docker is not found, you can try to install docker inside WSL.
+
+```console
+sudo snap install docker
+```
+
+If you get an error message that make is not found, you can try to install make inside WSL.
+
+```console
+sudo apt install make
+```
+
+If the `make build` command fails, you can try to pull the image from the Docker Hub by running the following command:
+
+```console
+docker pull stefanhahmann/elephant-server:0.5.6
+```
+
+This will download the image from the Docker Hub, which may take some time depending on your internet connection.
+The version on Docker Hub may not be the latest version of Elephant, but you can use it, if building the image fails.
+Check [Docker Hub](https://hub.docker.com/r/stefanhahmann/elephant-server) for the Elephant server image.
+
+```console
+docker pull stefanhahmann/elephant-server:0.5.6
+```
+
+## Starting the Elephant Server
+
+Make sure that Docker Desktop is running.
+
+Open a console (press `Windows button`, type `cmd` and press `Enter`) and navigate to the folder where you have unzipped the Elephant installation files.
+Start `wsl` by typing `wsl` and pressing `Enter`.
+
+Set the environment variable `ELEPHANT_NVIDIA_GID` to `0` by running the following command:
+
+```console
+set ELEPHANT_NVIDIA_GID=0
+```
+
+You can now start the Elephant server by running the following command:
+Again, including `sudo` may not be required on every machine.
+```console
+sudo make launch
+```
+
+You can check if the server is running by opening a browser and navigating to [http://localhost:8080/](http://localhost:8080/).
+You should see the Elephant server interface:
+![elephant-server-interface.png](images/elephant-server-interface.png)
+
+You can now open a Mastodon project in Fiji, which brings up the client connected to the Elephant server:
+![elephant-control-panel.png](images/elephant-control-panel.png)
+
+`*` By the time writing this blog post, there was a known issue with the Nvidia GPU support on WSL2. 
+You may need to update the Nvidia driver to the latest version, after the [issue](https://github.com/microsoft/WSL/issues/11277) has been resolved in order to use the GPU for acceleration.
+
+## Stopping the Elephant Server
+
+You can stop the Elephant server by running the following command:
+```console
+sudo make stop
+```
+
+## Move Docker to another drive
+
+You may want to move the Docker installation to another drive, if you have limited space on your system drive.
+You can do so with the following steps. Make sure you have stopped Docker Desktop.
+The following example moves the Docker installation to the `D:` drive. It is assumed you have an empty folder `D:\docker`.
+
+The whole process may take some time, depending on the size of the Docker installation.
+
+```console
+wsl --shutdown
+wsl --export docker-desktop-data d:\docker\docker-desktop-data.tar
+wsl --unregister docker-desktop-data
+wsl --import docker-desktop-data d:\docker\data d:\docker\docker-desktop-data.tar --version 2
+```
+