unifem/cht-desktop repository overview

⁠Docker Image for Testing Conjugate Heat Transfer

This Docker image provides the Ubuntu 17.10 environment with X Windows with Overture and FEniCS for testing conjugate heat transfer. The X Windows will display in your web browser in full-screen mode. You can use this Docker image on 64-bit Linux, Mac or Windows. It allows you to use the same programming environment regardless which OS you are running on your laptop or desktop.

⁠Preparation

Before you start, you need to first install Python and Docker on your computer by following the steps below.

⁠Installing Python

If you use Linux or Mac, Python is most likely already installed on your computer, so you can skip this step.

If you use Windows, you need to install Python if you have not yet done so. The easiest way is to install Miniconda, which you can download at https://repo.continuum.io/miniconda/Miniconda3-latest-Windows-x86_64.exe⁠. During installation, make sure you check the option to make Miniconda the system's default Python.

⁠Installing Docker

Download the Docker Community Edition for free at https://www.docker.com/community-edition#/download⁠ and then run the installer. Note that you need administrator's privilege to install Docker. After installation, make sure you launch Docker before proceeding to the next step.

Notes for Windows Users

1. Docker only supports 64-bit Windows 10 Pro or higher. If you have Windows 8 or Windows 10 Home, you need to upgrade your Windows operating system before installing Docker.
2. After installing Docker, you may need to restart your computer to enable virtualization and Microsoft Hyper-V. Note that you may also need to change the BIOS of your computer to enable hardware virtualization if it was not yet enabled.
3. For security reasons, do not use Docker in the Administrator account, even if you are the sole user on the computer. For Docker version 17.06 or later, your Windows account must be a member of the local group “docker-users” for you to run Docker. To add your account to the group, you need to log into an Administrator account and run Computer Management. Open up Local Users and Groups, select Groups, right click on docker-users in the list, and then click on Add to Group... to add your username to the group.
4. If you previously installed VMWare or VirtualBox on your Windows computer, they might conflict with Docker. You may get an error message stating that virtualization must be enabled when starting Docker, even though virtualization was already enabled. To resolve the issue, go to Windows Features in the Control Panel, disable Hyper-V and then re-enable it.
5. When you use Docker for the first time, you must change its settings to make the C drive shared. To do this, right-click the Docker icon in the system tray, and then click on Settings.... Go to Shared Drives tab and check the C drive.
6. Docker for Windows saves the images and data volumes in a shared public folder C:\Users\Public\Documents\Hyper-V\Virtual Hard Disks\MobyLinuxVM.vhdx. This is a major security risk because all your images and data can be accessed and modified by other Docker users on the same computer. If you are using a shared Windows computer, make sure you create a private folder such as C:\Users\YourUserName\Documents\Hyper-V\Virtual Hard Disks and then go to Advanced tab in Docker Settings, and change the Image and Volume VHD Location to this folder.

Notes for Mac Users

1. Docker Version 17.06.0-ce has a bug⁠ that causes Docker to restart when your computer wakes up from sleep and when your network settings change. As a workaround, change the Proxies setting in Docker's preferences to "No Proxy".
2. On Mac, the clock in Docker would lag when your computer goes to sleep and then wakes up. You can resolve this issue either by restarting Docker after waking up or by installing sync-docker-time⁠.

Notes for Linux Users

• After you install Docker, make sure you add yourself to the Docker group by running the command:

sudo adduser $USER docker

Then, log out and log back in before you can use Docker.

⁠Running the Docker Image as Jupyter-Notebook Server

To run the Docker image, first download the script cht_jupyter.py⁠ and save it to the working directory where you will store your codes and data. You can download the script using command line: On Windows, start Windows PowerShell, use the cd command to change to the working directory where you will store your codes and data, and then run the following command:

curl https://raw.githubusercontent.com/unifem/cht-overture-fem/master/cht_jupyter.py -outfile cht_jupyter.py

On Linux or Mac, start a terminal, use the cd command to change to the working directory, and then run the following command:

curl -s -O https://raw.githubusercontent.com/unifem/cht-overture-fem/master/cht_jupyter.py

After downloading the script, you can start the Docker image using the command

python cht_jupyter.py -p

This will download and run the Docker image and then launch your default web browser to show the desktop environment. The -p option is optional, and it instructs the Python script to pull and update the image to the latest version. The work directory by default will be mapped to the current working directory on your host.

For additional command-line options, use the command

python cht_jupyter.py -h

To run the simple test example, open the file simpleExample/simpleEample.ipynb in Jupyter Notebook.

⁠Stopping the Docker Image

To stop the Docker image, press Ctrl-C twice in the terminal (or Windows PowerShell on Windows) on your host computer where you started the Docker image, and close the tab for the desktop in your web browser.

⁠Tips and Tricks

• By default, Docker uses two CPU cores and 2GB of memory on Mac and Windows. If you want to run large jobs, you can increase the amount of memory or the number of cores dedicated to Docker. Just click on the Docker icon in the system tray, select Settings (or Preferences for Mac) and then select the Advanced tab to adjust the settings.