karchinlab/cravatmupit repository overview

Note: The docker version of CRAVAT requires a large reference database so 200 GB of disk space will be required.

How to Install Docker and CRAVAT/MuPIT Container

Please scroll to read the installation instructions for your OS.

> Windows Installation

Installing Docker

To install Docker, please follow the guide at https://www.docker.com/docker-windows⁠.

After installing Docker, please allocate at least 4 Gb of memory to Docker VM. To do so:

1. Run docker
2. Right click on the docker icon in the system tray
3. Select settings
4. Select the "Advanced" tab
5. Change the memory slider to at least 4096 MB

How to Create the CRAVAT/MuPIT Container

Run the below (and any Docker related) command in any windows command line or powershell.

<path_to_persistent_storage>: Reference data and job results are stored outside of the container so the software can be upgraded in the future without losing results. The minimum amount of disk space to start CRAVAT and MuPIT is 250 GB and more is needed as you run jobs. On Windows by default a location in C:\Users (Windows) should be used. Otherwise see "How to Use a Location Not Under /Users as Persistent Storage" below. On Windows capitalization must match actual path and drive letter should be specified as //c/ for example //c/Users/mike/dockervol.

The first time you run the cravatmupit container, the image needs to be fetched from docker hub so you will see lots of download/pull complete messages followed by a long container id. For example:

How to Connect to CRAVAT and MuPIT

Connect to CRAVAT at http://localhost/CRAVAT⁠ and to MuPIT Interactive at http://localhost/MuPIT_Interactive⁠.

> Mac Installation

Installing Docker

To install Docker, please follow the guide at https://www.docker.com/docker-mac⁠

After installing Docker, please allocate at least 4 Gb of memory to the Docker VM.

How to Create the CRAVAT/MuPIT Container

Run the below (and any Docker related) command on Docker Quickstart Terminal.

<path_to_persistent_storage>: Reference data and job results are stored outside of the container so the software can be upgraded in the future without losing results. The minimum amount of disk space to start CRAVAT and MuPIT is 250 GB and more is needed as you run jobs. On Mac by default a location in /Users should be used. Otherwise see "How to Use a Location Not Under /Users as Persistent Storage" below.

The first time you run the cravatmupit container, the image needs to be fetched from docker hub so you will see lots of download/pull complete messages followed by a long container id. For example:

How to Connect to CRAVAT and MuPIT

Connect to CRAVAT at http://localhost/CRAVAT⁠ and to MuPIT Interactive at http://localhost/MuPIT_Interactive⁠.

Please scroll down to the section on Initial Setup of CRAVAT

> Linux Installation

Installing Docker

To install Docker, please follow the guide at https://docs.docker.com/engine/installation/ubuntulinux/⁠ for Ubuntu, or click your distro on the left menu of that page and follow instructions.

How to Create the CRAVAT/MuPIT Container

Run the below command.

<path_to_persistent_storage>: Reference data and job results are stored outside of the container so the software can be upgraded in the future without losing results. The minimum amount of disk space to start CRAVAT and MuPIT is 250 GB and more is needed as you run jobs. Any location can be used as <path_to_persistent_storage>.

By default, the container will not limit it's memory use on linux. To limit the memory used by the container use the -m flag in the docker run command. Allocating less than 4gb of memory to CRAVAT may result in errors and is not advised.

The first time you run the cravatmupit container, the image needs to be fetched from docker hub so you will see lots of download/pull complete messages followed by a long container id. For example:

How to Connect to CRAVAT and MuPIT

Connect to CRAVAT at http://localhost/CRAVAT⁠ and to MuPIT Interactive at http://localhost/MuPIT_Interactive⁠.

(If you use Docker Toolbox, follow the below steps.)

After the container is running, you can connect to CRAVAT using a browser. If docker is running on a Linux server, you just connect to that machine's IP address with the port specified in the run command above. For example:

http://10.1.10.1/CRAVAT⁠

If you are running the browser on the Linux server with docker you can connect with:

http://localhost/CRAVAT⁠

Note: the MuPIT structural mutation viewer is now integrated into the CRAVAT application but if you want to use MuPIT directly, you can access it with the URL:

http://:8888/MuPIT_Interactive/

Initial Setup of CRAVAT

CRAVAT needs to download and install reference databases, CHASM and VEST classifier files, and annotation cache files. All these are installed via a setup page in the browser which is accessible on the CRAVAT webpage to the 'admin' user. When reference data is not install, the CRAVAT website will display a message indicating that the admin user should login and install the reference data. Login in as the admin user with the initial default password of 'admin' (can be changed). Select the 'SetUp' menu option. A new screen will open up. You can then either select the 'install all necessary resources at once' button or manually install each required component. This page shows when a reference package is installed, gives the date of the data, and provides options for reinstalling or updating reference data. You may close the browser while the setup is running and reconnect to it later to check the progress. Some of the databases are very large and may take several hours to install.

Do not stop the container while reference data is being installed. If the container is restarted, you need to go back to the setup page and click the 'install all needed resources' button. It will only install packages that were not previously successfully installed.

If you want to receive email notifications of completed jobs, you need to configure the email server information on the setup page. This is not required.

How to Start and Stop the CRAVAT/MuPIT Container

To stop the docker container, run

To restart the cravat mupit software, for example after a computer restart, you don't need to do the run command, just go into the docker quickstart terminal and type:

How to Use CRAVAT

You cannot submit jobs as 'admin' so you will need to create at least one normal login for job submission. You should login when submitting a job so that you have access to job status messages and interactive results when jobs complete. Please refer to CRAVAT's Help page at http://www.cravat.us/help.jsp⁠ for complete information on submitting jobs and reviewing results. The help page also contains information on interacting with CRAVAT from automated programs or Galaxy.

How to Use MuPIT

Please refer to MuPIT's Help page at http://mupit.icm.jhu.edu/Help.html⁠ for complete information on using MuPIT interactively or linking to MuPIT.

How to Upgrade to a new version of CRAVAT

The version of CRAVAT that you are currently running is displayed in red letters on the main CRAVAT webpage. If you look at the tags in Docker hub, you can see if a new version of the software is available. Because reference data and job results are stored outside of the container, you can upgrade without loosing the results of previous analysis.

To stop the docker container, run

Remove the old container:

To get the latest software run:

To run the new image:

If there have been changes to reference databases, you will be instructed to login as admin and go to the setup page to install updated databases.

How to Make CRAVAT and MuPIT Accessible by Other Computers in a local network

>Linux

Generally on Linux machines, docker will attempt to make automatic updates to the firewall to allow all computers to connect to the container. CRAVAT should be available from any computer on the local network.

http:///CRAVAT

>Windows or Mac

1. Open the program "VirtualBox" in your computer.
2. Find the Docker's image on the VirtualBox. Usually, its name on the list of VirtualBox machines is "default".
3. Open "Settings" for the Docker machine.
4. Click "Network" tab.
5. Among "Adapter" tabs, find the tab that has "Attached to: NAT".
6. Click "Port Forwarding".
7. Click "+" icon on the upper right corner.
8. Type the following information: "tomcat" for Name, "TCP" for Protocol, blank for "Host IP", 80 for "Host Port", blank for "Guest IP", and 8888 for "Guest Port".
9. Click "Ok".
10. Click "Ok".
11. Open the incoming port 80 on your computer. If you use Windows, an example instruction is at http://wiki.mcneel.com/zoo/window7firewall⁠ (use port number 8888 and rule name other than "HTTP"). If you use Mac, an example instruction is at "How to open a specific port in OS X firewall" section on http://www.macworld.co.uk/how-to/mac-software/how-open-specific-ports-in-os-x-1010-firewall-3616405/⁠. If you use Linux, an example instruction is at http://www.tixati.com/optimize/open-ports-linux.html⁠.
12. Find the IP address of your computer with CRAVAT/MuPIT. On Windows, you can use "ipconfig". On Mac, you can use "ifconfig |grep inet".
13. Other computers in your LAN can now access CRAVAT and MuPIT in your computer using http://<IP found in step 12>/CRAVAT and http://<IP found in step 12>/MuPIT_Interactive.

How to Use a Location Not Under /Users as Persistent Storage in a Windows and Mac System

If you are running on a Windows or Mac and don’t have enough disk space in C:\Users (Windows) and /Users (Mac) and you want the CRAVAT/MuPIT Docker container to use storage space on a different internal/external drive, then follow these instructions to make the disk accessible to Docker.

1. Open VirtualBox application.
2. In VirtualBox, select the Docker host image (in most cases the image's name is "default") and click "Settings".
3. In the Settings window, click "Shared Folders" on the left. Then, click a folder icon with a plus sign at the right side of the window, and enter the path to the directory that you want to use as CRAVAT and MuPIT's persistent storage space and a name for that space, for example "dockervolume". Check "Auto-mount" and "Make Permanent".
4. Get on the Docker host.

1. Make a folder to mount your computer's folder on.

1. Mount your computer's folder and give it the right permissions.

1. Run Dockerized CRAVAT MuPIT using the mount location in the Docker host.