3.2 Using existing images
3.2.1 Getting started
Run the following in the terminal:
docker images
The docker images
command lists the Docker images that you have on your computer.
Now run the following:
docker pull hello-world
Run docker images
again: now you see the “hello-world” image listed!
docker pull
imports by default an image from Docker Hub.
We will see in more details the docker images
and docker run
commands, but let’s first explore the Docker images repositories.
3.2.2 Explore Docker Hub
Images can be stored locally or shared in a registry.
Docker hub is the main public registry for Docker images.
Let’s search the keyword ubuntu:
You can also search existing Docker images with the docker search
command.
Example: let’s look for images that have the keyword blast in their name or description.
docker search blast
Too many results? You can apply some filters:
- Minimum number of stars:
docker search blast --filter stars=5
- The image is an official build:
docker search blast --filter is-official=true
- The image is an automated build:
docker search blast --filter is-automated=true
# Apply one filter
docker search blast --filter stars=2
# Apply more than one filter
docker search blast --filter is-automated=true --filter stars=2
https://vsupalov.com/docker-latest-tag/ to read more about the latest tag
HANDS-ON
Use docker search
to find a Docker image for the keyword ubuntu
. Using the filters, answer the following questions:
- How many images are official builds?
- How many images have 3 or more stars?
- How many images are official builds AND have 3 or more stars?
- What is the NAME of the image with the highest number of stars?
Answer
# Official builds
docker search ubuntu --filter is-official=true
# 3 or more stars
docker search ubuntu --filter stars=3
# Both filters
docker search ubuntu --filter is-official=true --filter stars=3
3.2.3 docker pull: import an image
Say we are now interested in the ubuntu
image from Docker Hub. We can retrieve it with docker pull
.
- By default, we get the latest image / latest release.
docker pull ubuntu
- You can choose the version of Ubuntu you are fetching; for that, check different tags on the website (latest is also a tag):
Note:
docker search
doesn’t allow to search for tags.
Let’s get the Ubuntu image with tag 18.04 (version 18.04 of Ubuntu = bionic):
docker pull ubuntu:18.04
Where is the image now?
As we have seen before, you can run docker images
in the terminal to see a list of the most recently created images. The command docker images
gives you information about:
- Repository.
- Tag.
- Unique image ID (Digest).
- Creation date.
- Image size.
Notice that for some images, such as Ubuntu, the same version tag hosts several Unique Image IDs (Digest). Each ID corresponds to a build for a specific Operating System or Architecture. Docker clients automatically retrieves the suitable one when using docker pull. If the OS/Architecture from the client is not present, an error is raised.
IMPORTANT: Digest ID present in Docker hub is NOT the same (or a shortened version) of the Image ID you can see when doing docker images. Details: https://stackoverflow.com/questions/56364643/whats-the-difference-between-a-docker-images-image-id-and-its-digestHANDS-ON
- Run command
docker images
. How many images do you get? - Pull the version 2.2.31 of the
biocontainers/blast
image- What is the size of the
blast
image you just pulled?
- What is the size of the
- How many images do you get if you run
docker images --all
? What are these images? Check documentation for help.
Answer
# Pull the blast image
docker pull biocontainers/blast:2.2.31
# Run `docker images --all`
docker images --all # intermediate images.
3.2.4 docker run: run image, i.e. start a container
Now we want to use what is inside the image.
Command docker run
creates a fresh container (active instance of the image) from a Docker (static) image, and runs it.
The format is:
docker run image:tag command (command being a command called inside the image)
We can start a container from the ubuntu tag 18.04 image, executing the command ls
(stored in /bin in the container).
docker run ubuntu:18.04 /bin/ls
Now execute ls
in your current working directory: is the result the same?
You can execute any program/command that is stored inside the image:
docker run ubuntu:18.04 /bin/whoami
docker run ubuntu:18.04 cat /etc/issue
You can either execute programs in the image from the command line (see above) or execute a container interactively; that is, “enter” the container, using command docker run -it
.
docker run -it ubuntu:18.04 /bin/bash
If you want to leave and stop the container, type exit
and ENTER.
HANDS-ON
- Run the hello-world image:
- What is happening?
- Now run the blast image we previously pulled:
- Is something happening?
- Start again a container from the same blast image (not interactively), and run blastp. What happens?
- Start a container interactively from the same blast image:
- What is the default working directory? What is inside this directory?
- Where is the
blastp
program located in the image? - Exit the container.
Answer
# Run the hello-world image
docker run hello-world
# Run the blast image
docker run biocontainers/blast:2.2.31
# Start again a container from the same blast image, and run the path to the blastp command:
docker run biocontainers/blast:2.2.31 blastp
# Start a container interactively from the same blast image:
docker run -ti biocontainers/blast:2.2.31
# What is the default working directory?
pwd; ls
# Where is the `blastp` program located in the image?
which blastp
# Exit the container.
exit
Note about Docker inside Docker: “Although running Docker inside Docker is generally not recommended, there are some legitimate use cases, such as development of Docker itself.” https://hub.docker.com/_/docker
You can run the container as daemon (in background), instead of the default foreground running, with the --detach
parameter:
docker run --detach ubuntu:18.04 tail -f /dev/null
Run container as daemon (in background) with a given name:
docker run --detach --name myubuntu_${USER} ubuntu:18.04 tail -f /dev/null
3.2.5 docker ps: check containers status
List running containers:
docker ps
List all containers (whether they are running or not):
docker ps -a
Each container has a unique ID.
3.2.6 docker exec: execute process in a running container
Difference between docker run
and docker exec
:
docker run
creates a temporary container, runs the command and stops the container.docker exec
needs an already running container to query the command (that is, a detached container).
docker exec myubuntu_${USER} uname -a
- Interactively
docker exec -it myubuntu_${USER} /bin/bash
3.2.7 docker stop, start, restart: actions on container
Stop a running container with docker stop
.
# check the list of running containers
docker ps
# stop the myubuntu container
docker stop myubuntu_${USER}
# check the list of all containers
docker ps -a
Start a stopped container (does NOT create a new one):
docker start myubuntu_${USER}
docker ps -a
Restart a running container:
docker restart myubuntu_${USER}
docker ps -a
Run with restart is enabled (by default, when exits, Docker does not automatically restart the container).
In the example below, we start a detached container named “myubuntu2” with the unless-stopped restart policy: restart the container unless it is explicitly stopped or Docker itself is stopped or restarted.
docker run --restart=unless-stopped --detach --name myubuntu2_${USER} ubuntu:18.04 tail -f /dev/null
- Restart policies: no (default), always, on-failure, unless-stopped
Update restart policy:
docker update --restart unless-stopped myubuntu_${USER}
HANDS-ON
- Start a container from the “hello-world” image in the background. Give it a name.
- Is your container running? Can you explain why (or why not)?
- Start another detached container from the same image (with a new name), with the always restart policy.
- Is the container running?
Answer
# start a "detached" container (in the background)
docker run --detach --name helloworld1_${USER} hello-world
# start a "detached" container with the "--restart=always" option
docker run --detach --restart=always --name helloworld2_${USER} hello-world
3.2.8 docker rm, docker rmi: clean up!
docker rm
is used to remove a container (set -f
is the container is running, to force the removal):
docker rm myubuntu
docker rm -f myubuntu_${USER}
docker rmi
is used to remove an image:
docker rmi ubuntu:18.04
HANDS-ON
- Remove any container (whether it is running or not).
- Remove the “hello-world” image.
Answer
# check all containers
docker ps -a
# remove by their ID:
docker rm -f CONTAINER1_ID CONTAINER2_ID ...
# remove the "hello-world" image
docker rmi hello-world