Scribd
Upload
10 views4 pages

Docker Image Installation Guide for MacOS

This document provides detailed instructions for installing and using a Docker image named 'cu_docker_v1.2.tar', which contains a pre-configured Ubuntu 24.04 environment for bioinformatics. It includes steps for loading the image, creating and running a container, and managing files within the container, primarily aimed at users with Apple Silicon ARM processors on MacOS. Additional commands and troubleshooting tips are also provided for effective usage of Docker.

Uploaded by

Sajad
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
10 views4 pages

Docker Image Installation Guide for MacOS

This document provides detailed instructions for installing and using a Docker image named 'cu_docker_v1.2.tar', which contains a pre-configured Ubuntu 24.04 environment for bioinformatics. It includes steps for loading the image, creating and running a container, and managing files within the container, primarily aimed at users with Apple Silicon ARM processors on MacOS. Additional commands and troubleshooting tips are also provided for effective usage of Docker.

Uploaded by

Sajad
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

Instructions for installing and using your Docker image

1. General
Check the md5 verification code:
MD5 (cu_docker_v1.[Link]) = f0e18012acefece3c1643bee4d4cbb65

In the course folder you will find a virtualization environment packaged as a Docker container
named ‘cu_docker_v1.[Link] and encoding the image ‘cu_docker_v1.2:latest’, which has been
pre-configured with the Ubuntu 24.04 operating system and the bioinformatics software used in
this course. Docker is a platform that allows packaging and distributing software in ‘containers’,
which ensures that everyone is using the same version of the software regardless of their
computer's operating system or architecture.

This Docker image and guide were primarily designed for computers with Apple Silicon ARM
processors running the MacOS operating system. Students using other systems may still be able
to use the image, albeit some steps below may differ depending on their operating system.

2. Installation and first time use


This section outlines the steps to operate the Docker virtualization environment. You can refer
to the ‘Details’ section below for a listing and details of operations and commands.

Set up the docker environment


1. Install Docker. Download and install the correct version for your platform (n.b., this guide
was created for Apple computers with an ARM processor and running MacOS).
2. Open a terminal. We will refer to this as the ‘local’ or ‘docker’ terminal. Your ‘docker
<command>’ commands will be executed from this terminal, or otherwise you can open
a new terminal.
3. Load the docker image using ‘docker load’.
4. Create a container, as an instance of the docker image for your individual use, using
‘docker run’. Your container is now active and running.
5. At any point, you can check on the docker images and containers active on your
computer with ‘docker images’ and ‘docker ps’.

Run the container


6. Open a new terminal in which you will run the container for your workflows. We will
refer to this as the ‘container’ terminal.
7. In the ‘container’ terminal, start a new bash session using ‘docker exec’. This will change
the prompt and will create a virtual immersion into the container’s operating system and
file system.
8. Copy the project files to the container file system, using ‘docker cp’ from the ‘docker’
terminal.
9. Create a directory in the container where you will run your projects, for instance ‘mkdir
/home/projects’ .
10. Run your bioinformatics workflow at the container’s prompt. All needed software has
been installed.
11. (Optional) You can stop the container at the end of your session, using ‘docker stop’
from the ‘docker terminal.

On subsequent uses
12. (Optional) If you stopped your container, restart it using ‘docker start’ from any terminal.
(This becomes the ‘docker’ terminal.)
13. Follow steps 6-10 above to start a container session (‘docker exec’), copy any necessary
files (‘docker cp’) and run your workflow.
14. (Optional) You can stop the container at the end of your session, using ‘docker stop’
from the ‘docker’ terminal.

On your last use


15. Stop your container, if running, using ‘docker stop’ from any terminal.
16. Check on your active images and containers using ‘docker images’ and ‘docker ps -a’.
17. Remove the container using ‘docker rm’, and the image if you wish, with ‘docker image
rm’.

3. Details
Installing Docker on MacOS
1. Visit the Docker website at [Link]
2. Click on the "Download for Mac - Apple Chip" button.
3. This will download a `.dmg` file. Once the download is complete, open this file.
4. Drag the [Link] to your Applications folder.
5. Navigate to your Applications folder and double-click on [Link] to open it. You may
be asked to enter your password.
6. Docker will now start. You will know it is ready when you see a whale icon in your menu
bar and a message saying "Docker Desktop is running."

Opening a Terminal on MacOS


You will use the Docker container from a Terminal window on your Mac.
1. Open Finder.
2. Navigate to Applications > Utilities.
3. Double-click on Terminal.
You should see a window with a prompt, where you can start typing commands.

Running the Docker Container and Listing of Docker commands

1. Loading the Docker Image


Load the Docker image from the provided ‘cu_docker_v1.[Link]’ file. Use the following command,
replacing `<path to image tar file>` with the actual path to the tar file on your computer:
% docker load -i <path to image tar file>/ cu_docker_v1.[Link]
This will load the ‘cu_docker_v1.[Link]:latest’ image encoded in the image tar file.

2. Checking your Docker Images


View a list of all the images you have on your computer, along with the image ID, repository
name, tag, creation time, and size. If you have just loaded a new image, it will appear at the top
of the list:
% docker images

3. Creating and running the Docker Container


Once the ‘cu_docker_v1.[Link]:latest’ image is loaded, create and start a new container from it.
Use the following command, replacing `<name of the container>` with a name of your choice
(e.g., ‘myexams’):
% docker run -it --name <name of the container> cu_docker_v1.[Link]:latest

4. Checking your Docker Container


View a list of all the containers you have running on your computer:
% docker ps -a

5. Starting (and re-starting) the Docker Container


If your container was stopped, you can re-start it using the following command, replacing
`<name of the container>` with the name of your container (e.g., ‘myexams’ above):
% docker start <name of the container>

6. Working within the Docker Container


To interact with the container in order to run your workflows, open a bash shell inside the
container:
% docker exec -it <name of the container> /bin/bash
Then run your bioinformatics commands at the prompt.

7. Stopping the Docker Container


When desired, for instance at the end of a session or at the end of the course, stop the
container using the following command:
% docker stop <name of the container>

8. Copying Files to and from the Docker Container


Copy files to and from the container using the `docker cp` command. We recommend that you
copy the provided project data files in your container’s ‘/media’ folder, but you can choose a
different location. To copy a file from your local machine to the container:
% docker cp <path to local file> <name of the container>:<path in container>

To copy a file from the container to your local machine:


% docker cp <name of the container>:<path in container> <path to local destination>

NOTE: Remember to replace the placeholders (`<...>`) in the commands with the actual values.
For example, if the name of your container is `myexams`, you would use `docker exec -it
myexams /bin/bash` to access it.

For more information on docker commands, run ‘docker --help’ or visit [Link] .

Additional credits: Zitong He

Common questions

Powered by AI

Directories within the Docker container are essential for organizing and managing files related to bioinformatics workflows. Creating specific directories, such as `/home/projects`, helps in structuring the workflows, making it easy to locate and use the necessary input files and store outputs systematically. This organization aids in reproducibility and efficiency, particularly in complex analyses common in bioinformatics .

Initial checks involve verifying that Docker is properly installed and running, indicated by the presence of the Docker whale icon in the system menu bar and the message "Docker Desktop is running". Additionally, executing `docker images` and `docker ps -a` will confirm the availability of required images and provide a list of active containers, ensuring the environment is set up for use .

Using `docker exec` is preferable to `docker attach` because it allows users to run new processes inside a running container without interfering with the container's primary process. This command also facilitates opening multiple terminal sessions into the same container, which is particularly useful for executing complex or numerous bioinformatics commands. In contrast, `docker attach` connects to the container's main process, risking the termination of the container if the process is inadvertently ended .

Running Docker on non-Apple ARM processor systems may involve different installation steps and commands specific to the operating systems compared to those for Apple Silicon ARM processors. While the general concept of using `docker load`, `docker run`, and `docker exec` remains the same, system-specific differences such as package installation methods may vary. The document notes that students may still use the Docker image but acknowledges possible variations and lacks OS-specific guidance beyond MacOS .

To install Docker on MacOS with an Apple Silicon ARM processor, you should first visit the Docker website and download the appropriate version by clicking on "Download for Mac - Apple Chip". This will download a `.dmg` file. After the download, open the `.dmg` file and drag the Docker.app into your Applications folder. Then, navigate to the Applications folder and double-click on Docker.app to open it. You might need to enter your password. Docker will start when you see a whale icon in your menu bar along with a message stating "Docker Desktop is running" .

To verify the integrity of the Docker image file, check the MD5 verification code provided. Compare the MD5 checksum of the downloaded image file `cu_docker_v1.2.tar` with the given verification code `MD5 (cu_docker_v1.2.tar) = f0e18012acefece3c1643bee4d4cbb65`. Use a tool to generate the MD5 hash of your file and ensure it matches the expected one, confirming the file's integrity .

Docker achieves software consistency across different operating systems and architectures by packaging software into containers that come with their environment configurations. This means that the docker container runs everything the exact same way regardless of the host system's architecture or operating system. Thus, users interact with the same versions of software irrespective of their system .

Copying files to and from a Docker container is necessary because it allows users to transfer data files needed for analysis and to retrieve results or modified files back to the local file system. Workflow execution often requires inputs in the form of data files, scripts, or parameters, and the resulting outputs may need to be stored outside the container. Commands such as `docker cp <path to local file> <name of the container>:<path in container>` and vice versa facilitate this process .

To stop a Docker container, use the command `docker stop <name of the container>`. After stopping the container, you can remove it with `docker rm <name of the container>`. If you wish to remove the Docker image as well, use `docker image rm <image name>` .

To run a Docker container, first load it using the command `docker load -i <path to image tar file>/cu_docker_v1.2.tar`. Then, create and start a new container with `docker run -it --name <name of the container> cu_docker_v1.2.tar:latest`. Interact with the container using `docker exec -it <name of the container> /bin/bash` to open a bash shell inside it, allowing you to execute bioinformatics workflows .

You might also like