Docker Installation

Docker-based installation

Docker is a platform which allows you to run software in the form of lightweight "containers". GLUE can be installed in the form of Docker containers. We would recommend this route in most circumstances as it offers a quick and less error-prone set-up. Also, GLUE will be isolated from other software on the computer and the operation of GLUE should generally be more predictable.

• Install Docker
• Familiarise yourself with some Docker concepts
• How Docker-based GLUE works
• Set up a gluetools-mysql container
• Set up a gluetools container
• Hints and tips for Docker-based GLUE
• Next steps

Install Docker

Docker Engine Community Edition is the software that manages Docker containers. It is available for Mac OSX, Windows and various Linux distributions. GLUE has been tested on Docker Engine version 18.06.

Familiarise yourself with some Docker concepts

If you are unfamiliar with Docker, you need to learn a few basic concepts. We would recommend at least reading through chapters 1 and 2 of the Get Started with Docker guide.

How Docker-based GLUE works

GLUE is packaged into two Docker images. The cvrbioinformatics/gluetools-mysql image provides the MySQL database which GLUE will use and some scripts for updating it. A container based on this image provides GLUE with its persistent database storage, and runs in the background as a daemon.

The cvrbioinformatics/gluetools image provides the GLUE engine software itself plus its 3rd-party dependencies such as RAxML and MAFFT. Containers based on this image will be run in a transient way, each time a GLUE interactive session is run.

Set up a gluetools-mysql container

Pull the cvrbioinformatics/gluetools-mysql image from Docker Hub:

$ docker pull cvrbioinformatics/gluetools-mysql:latest

Start a container called gluetools-mysql based on this image:

$ docker run --detach --name gluetools-mysql cvrbioinformatics/gluetools-mysql:latest

The container was started in detached mode, it runs in the background as a daemon.

Set up a gluetools container

Pull the cvrbioinformatics/gluetools image from Docker Hub:

$ docker pull cvrbioinformatics/gluetools:latest

Start a container called gluetools based on this image, linking it to the gluetools-mysql container.

$ docker run --rm -it --name gluetools --link gluetools-mysql cvrbioinformatics/gluetools:latest

This will start an interactive GLUE session within the new container:

GLUE Version 1.1.113 Copyright (C) 2018 The University of Glasgow This program comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it under certain conditions. For details see GNU Affero General Public License v3: http://www.gnu.org/licenses/

Mode path: / Option load-save-path: /opt/gluetools/projects/exampleProject GLUE> ...

When the interactive session completes, the container will be removed (via the --rm option).

Hints and tips for Docker-based GLUE

• Starting and stopping the gluetools-mysql container

  The gluetools-mysql container contains the GLUE database which you normally want to keep in place from one GLUE interactive session to the next. When you restart your computer this container will be in a "stopped" state. To start it again use:

  $ docker start gluetools-mysql
  
  

  You can stop it with:

  $ docker stop gluetools-mysql
  
  

  If you remove this container, your database contents will be lost.

• Install a pre-built GLUE dataset in the gluetools-mysql container

  While the gluetools-mysql container is running, you can install various pre-built GLUE projects. For example, the latest NCBI-HCV-GLUE project build can be installed using this command:

  $ docker exec gluetools-mysql installGlueProject.sh ncbi_hcv_glue
  
  

Note

This command will wipe any previous data from the database.

• Wipe the database in the gluetools-mysql container

  You can wipe the GLUE database using this command:

  $ docker exec gluetools-mysql glueWipeDatabase.sh
  
  

• Volume mapping

  Each Docker container has its own isolated file system, so by default files outside the container cannot be accessed by GLUE. Since the gluetools container is transient, its file system will be removed at the end of the GLUE session.

  If you want GLUE to read your own project data from a directory outside the container or save any file output, add the --volume option to the docker run command for the gluetools container. This maps a directory outside the container (i.e. on the host filesystem) to a path within container filesystem. For example, if you use

  --volume /home/fred/my_glue_project:/opt/gluetools/projects/my_glue_project
  
  

  then the directory /home/fred/my_glue_project will be readable/writable inside the container at /opt/gluetools/projects/my_glue_project. Multiple directories can be mapped with this option.

• Working directory

  The working directory for the gluetools container defaults to the example project directory. However this can be overridden by adding the following option to the docker run command:

  $ --workdir /opt/gluetools/projects/my_glue_project
  
  

• Use .gluerc and .glue_history files from the host file system

  These files store your GLUE console preferences and command history. You may want to use .gluerc and .glue_history files from the host file system rather than the container file system. To do this, map your home directory using a --volume option in the docker run command:

  --volume /home/fred:/home/fred
  
  

  Then also add this --env option to the docker run command:

  --env _JAVA_OPTIONS=-Duser.home=/home/fred
  
  

• Run bash in the container

  You can run an interactive bash session rather than a GLUE session in the container by simply adding /bin/bash to the end of the docker run command.

  $ docker run --rm -it --name gluetools --link gluetools-mysql cvrbioinformatics/gluetools:latest /bin/bash
  
  

Next steps

If you are new to GLUE we strongly recommend building the example GLUE project as the next step. The example project directory is included within the container file system.

---