Running OMFIT with Docker

Personal OMFIT installations can be run as a docker image. Docker is a software technology that provides operating-system-level virtualization also known as “containers”. The omfit Docker image provides a currated environment in which OMFIT can run independently of the underlying operating system. Please note that the omfit docker image does not come with the OMFIT source code itself, instead it just provides the environment in which OMFIT can run.

Note

  • When docker is installed, you will need to grant Docker root permissions to access your filesystem system.
  • On the first launch, it will take some time to download the omfit Docker image.
  • All scripts rely on having the $OMFIT_ROOT$ environmental variable properly set on the host system.

Linux

  1. Download, install, and run Docker for Linux
  2. Add the user that will be running OMFIT to the docker group
sudo usermod -aG docker $USER
  1. Restart docker
sudo service docker restart
  1. Log out and log back in so group membership is re-evaluated
  2. Start OMFIT with the Linux OMFIT docker script:
$OMFIT_ROOT/bin/omfit_docker_linux.sh

OSX

  1. Download, install, and run Docker for OSX >=10.10.3 or OSX <10.10.3
  2. Download and install Xquartz
  3. Create an alias for your loopback network device: sudo ifconfig lo0 alias 192.168.123.123
  4. Start XQuartz, then go to XQuartz->Preferences, click the “security” tab, and then check the box for “Allow connections from network clients”. You might need to log out and log back in after this.
  5. Start OMFIT with the OSX OMFIT docker script:
$OMFIT_ROOT/bin/omfit_docker_osx.sh

Windows

To date, Docker is the only way to run OMFIT under a Windows environment. The current version of Docker is only available for Windows systems using Windows 10 Hyper-V, which restricts the operating systems to “Windows 10 Enterprise”, “Windows 10 Professional” and “Windows 10 Education”. Should you have “Windows 10 Home”, it can be upgraded to “Windows 10 Professional” via Settings->Update and Security->Activation

  1. Download, install, and run Docker for Windows
  2. Install Cygwin. Make sure to select the xinit package as well as the xhost package during setup to install.
  3. In the cygwin shell, type (you can find your machine’s ip with the ipconfig command):
export DISPLAY=[your-machine's-ip]:0.0
  1. To start your X11 server, in the cygwin shell type:
startxwin -- -listen tcp &
  1. To add your own computer to the X11 access control list, in the terminal type:
xhost + [your machine's ip]
  1. Open the windows cmd, type:
SET IP_ADDRESS=[your-machine's-ip]
%OMFIT_ROOT%\bin\omfit_docker_windows.bat

OMFIT Core Docker image

In addition to the full OMFIT environment, there exists a docker image with only the dependencies needed to run the core OMFIT framework. Using this image will result in a smaller download, which can save time and bandwidth. The full OMFIT Docker image uses this image as a base to reduce incremental download time after updates occur. When making OMFIT framework changes, it would be advisable to test against this image to make sure a dependency doesn’t need to be moved from optional to core. To run the OMFIT Core image:

  1. Edit $OMFIT_ROOT/bin/omfit_docker_version_tag and replace omfit/omfit with omfit/omfit_core, leaving the version number untouched.
  2. Run the desired Docker start script as described previously in the document.