granek/orthomcl repository overview

• DONE Quick Start ** Install Docker
  1. See installation instructions for [[https://docs.docker.com/installation/mac/][Mac⁠]], [[https://docs.docker.com/installation/windows/][Windows⁠]], [[https://docs.docker.com/installation/][etc⁠]]
  2. On Mac and Windows, launch "Docker Quickstart Terminal". All subsequent commands will be run in the terminal launched by "Docker Quickstart Terminal". Notes: On other operating systems, the docker daemon may run automatically after installation. Also, on other operating systems, you may need to use the command sudo docker instead of just docker.

** Download Run Script Download the run script [[https://raw.githubusercontent.com/granek/OrthoMCL-docker/master/run_orthomcl.sh][run_orthomcl.sh⁠]] (e.g. right click on the link and select "Save Link As ...") ** Run the script Within the Docker terminal run bash run_orthomcl.sh to launch the OrthoMCL container. You should now have a bash shell in the OrthoMCL container that looks something like this:

#+BEGIN_SRC sh root@a74d15695ca9:/# #+END_SRC ** Generate OrthoMCL Configuration File Download the config generation script into your docker container, and run it with the following commands within your docker container: #+BEGIN_SRC sh wget https://raw.githubusercontent.com/granek/OrthoMCL-docker/master/test_run/create_config.sh⁠ bash create_config.sh > orthomcl.config #+END_SRC This should generate the config file orthomcl.config in the current directory in your docker container. ** Install the schema into MySQL database Run it with the following command within your docker container to set up the database: #+BEGIN_SRC sh orthomclInstallSchema orthomcl.config #+END_SRC

• OrthoMCL Docker Details ** One-time Use Download the run script [[https://raw.githubusercontent.com/granek/OrthoMCL-docker/master/run_orthomcl_oneshot.sh][run_orthomcl_oneshot.sh⁠]]. Run this script within the Docker terminal run bash run_orthomcl_oneshot.sh to launch the OrthoMCL container. This script cleans up after itself, which means that your session is completely obliterated once you exit. If you might want to resume your session, see Multi-time Use below. ** Multi-time Use If you expect to want to use OrthoMCL in several different sessions, you will want to run bash run_orthomcl.sh. When you want to get out of your OrthoMCL session, but want to resume it later (technically this is detaching), use the "escape sequence" Ctrl-p + Ctrl-q. This leaves the container running. To resume your orthomcl session use the command docker attach orthomcl-run within your "Docker Quickstart Terminal". Note that when you attach the shell will not print a prompt right away, just hit the enter/return key to get a prompt.

  Accidentally did exit in your OrthoMCL session? Don't worry, just run docker start orthomcl-run before docker attach orthomcl-run.

⁠docker exec -ti orthomcl-run bash

⁠This is roughly equivalent to logging back into a server by ssh, after logging out.

*** Cleanup When Done Once you are completely done with OrthoMCL, you might want to get rid of the containers: #+BEGIN_SRC sh docker stop orthomcl-mysql docker rm orthomcl-run orthomcl-mysql #+END_SRC ** Accessing files on the host computer A Docker container is almost completely isolated from the host computer that it is running on. This prevents the container from doing nasty things to your computer, but also makes it a bit more difficult to interact with files that are residing on your computer. A simple way around this limitation is to mount a directory from the host computer into the Docker container. When you run bash run_orthomcl.sh, the directory that you run it from (the "working directory") will automatically be mounted within the OrthoMCL container at the mountpoint /host_dir. This means that you can read and write files that are in that directory. Try the following within your OrthoMCL container: #+BEGIN_SRC sh ls /host_dir echo "I am writing this from the future ... a docker container" > /host_dir/test_output.txt #+END_SRC

If you want to mount a different directory, just supply this as a full path when you run the orthomcl script bash run_orthomcl.sh FULL_PATH_TO_DATA, and that directory will be mounted at /host_dir instead ** OrthoMCL Configuration File The github repo contains a script for automatically generating an OrthoMCL configuration file. There are two ways to generate the configuration file. *** From repo If you cloned the repo from github, and started things up by running the run_orthomcl.sh (or run_orthomcl_oneshot.sh) script in the repo directory, you can generate the configuration file by running the following command within your docker container: #+BEGIN_SRC sh bash /host_dir/test_run/create_config.sh > orthomcl.config #+END_SRC

This should generate the config file in the current directory in your docker container. You can check this by running the following within your docker container: #+BEGIN_SRC sh cat orthomcl.config #+END_SRC

If it worked, the second line should be the following (but probably with a different IP address): #+BEGIN_SRC sh dbConnectString=dbi:mysql:orthomcl:172.17.0.40:3306 #+END_SRC *** Download script You can also download the config generation script into your docker container, and run it with the following commands within your docker container: #+BEGIN_SRC sh wget https://raw.githubusercontent.com/granek/OrthoMCL-docker/master/test_run/create_config.sh⁠ bash create_config.sh > orthomcl.config #+END_SRC This should generate the config file in the current directory in your docker container. You can check this by running the following within your docker container: #+BEGIN_SRC sh cat orthomcl.config #+END_SRC

If it worked, the second line should be the following (but probably with a different IP address): #+BEGIN_SRC sh dbConnectString=dbi:mysql:orthomcl:172.17.0.40:3306 #+END_SRC ** OrthoMCL Image *** Download OrthoMCL Image The OrthoMCL image is automatically downloaded from Docker Hub by the run_orthomcl.sh script, but you can manually download it with the command docker pull granek/orthomcl. *** Manual build of the OrthoMCL Image If you want to build the OrthoMCL image instead of pulling it from Docker Hub, download [[https://raw.githubusercontent.com/granek/OrthoMCL-docker/master/Dockerfile][Dockerfile⁠]] (or pull this repo), then run docker build -t orthomcl within the directory containing Dockerfile.