Red Hat Training

A Red Hat training course is available for Red Hat Container Development Kit

Chapter 6. Using the Docker Service

When you initialize the Container Development Kit virtual machine (using the vagrant up command), various services are automatically pre-configured and running — depending on the Vagrantfile you used to provision the Container Development Kit box. The Docker service is running in all cases, and you can use it immediately after the virtual machine is launched. While it is possible to use and interact with the Docker service using GUI tools (for example, the integrated Docker support provided by the Eclipse IDE), this section introduces a number of basic docker commands to get you started using the Docker service from the command line.

Command-line usage of the Docker service provided by the Container Development Kit box is possible both from within the virtual machine and from the host machine — see section Using the vagrant-service-manager Plugin for instructions on how to set up your host machine to interact with the Docker service running inside the Container Development Kit virtual machine.

See the Get Started with Docker Formatted Container Images chapter of the Red Hat Enterprise Linux Atomic Host 7 Getting Started with Containers guide for a more thorough introduction into the Docker service.

6.1. Preparing Host System for Using Docker from the Command Line

To use the docker command on your host system to interact with the Docker service running inside the Container Development Kit virtual machine, you need to install the docker executable.

If you intend to use Docker (and the docker command) only from within the Container Development Kit virtual machine, no preparation is required — the docker command is installed in the Container Development Kit box by default.

6.1.1. Installing the docker Executable

Use the install-cli command of the vagrant-service-manager plugin to install the docker binary on your host system.

For example:

~]$ vagrant service-manager install-cli docker
# Binary now available at /home/joe/.vagrant.d/data/service-manager/bin/docker/1.10.3/docker
# run binary as:
# docker <command>
export PATH=/home/joe/.vagrant.d/data/service-manager/bin/docker/1.10.3:$PATH

# run following command to configure your shell:
# eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager install-cli docker | tr -d '\r')"
Note

To use the install-cli command when behind a proxy, the Container Development Environment needs to be configured to operate behind a proxy using the vagrant-service-manager plugin. See section Using vagrant-service-manager to Set Proxy Environment Variables in the Red Hat Container Development Kit 2.3 Installation Guide.

6.1.1.1. Installing a Custom Version of the docker Binary

By default, the install-cli command installs the docker binary from the upstream Docker project in version 1.10.3. To install a different version, use the --cli-version option.

For example:

~]$ vagrant service-manager install-cli docker --cli-version 1.12.3
# Binary now available at /home/joe/.vagrant.d/data/service-manager/bin/docker/1.12.3/docker
# run binary as:
# docker <command>
export PATH=/home/joe/.vagrant.d/data/service-manager/bin/docker/1.12.3:$PATH

# run following command to configure your shell:
# eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager install-cli docker --cli-version 1.12.3 | tr -d '\r')"

6.1.1.2. Installing the docker Binary to a Custom Location

By default, the install-cli command installs the docker binary from the upstream Docker project to the following directory: /home/joe/.vagrant.d/data/service-manager/bin/docker/1.10.3/. To install the executable to a different location, use the --path option. Note that you need to specify an existing directory and the name of the binary.

For example:

~]$ vagrant service-manager install-cli docker --cli-version 1.12.3 --path ~/bin/docker
# Binary now available at /home/joe/bin/docker
# run binary as:
# docker <command>
export PATH=/home/joe/bin:$PATH

# run following command to configure your shell:
# eval "$(VAGRANT_NO_COLOR=1 vagrant service-manager install-cli docker --path /home/joe/bin/docker --cli-version 1.12.3 | tr -d '\r')"

6.2. Learning about the Docker Environment

The docker command offers several sub-commands that let you acquire information about the Docker service, the environment it runs in, and available resources. You can also query the service for images and containers it manages and for images that are available to you from the pre-configured registries. By default, the Docker service in Container Development Kit can download and use images from both the Docker Hub (docker.io) and the Red Hat Atomic Registry (registry.access.redhat.com).

Use the following commands to obtain information about the Docker service and the working environment.

6.2.1. Verifying the Version of the Docker Service

Run the docker version command to see the version of both the Docker Client and Docker Server:

~]$ docker version
Client:
 Version:         1.10.3
 API version:     1.22
 Package version: docker-1.10.3-46.el7.14.x86_64
 Go version:      go1.4.2
 Git commit:      78ee77d/1.10.3
 Built:
 OS/Arch:         linux/amd64

Server:
 Version:         1.10.3
 API version:     1.22
 Package version: docker-1.10.3-46.el7.14.x86_64
 Go version:      go1.4.2
 Git commit:      78ee77d/1.10.3
 Built:
 OS/Arch:         linux/amd64

6.2.2. Displaying Information about the System and Resources

Run the docker info command to see information about the host system (which, in this case, is the virtualized Red Hat Enterprise Linux instance managed by Vagrant), utilization of virtualization resources, basic networking information, and the numbers of managed containerrs and images:

~]$ docker info
Containers: 14
Images: 32
Server Version: 1.9.1
Storage Driver: devicemapper
 Pool Name: VolGroup00-docker--pool
 Pool Blocksize: 524.3 kB
 Base Device Size: 107.4 GB
 Backing Filesystem: xfs
 Data file:
 Metadata file:
 Data Space Used: 2.172 GB
 Data Space Total: 13.6 GB
 Data Space Available: 11.43 GB
 Metadata Space Used: 1.016 MB
 Metadata Space Total: 46.14 MB
 Metadata Space Available: 45.12 MB
 Udev Sync Supported: true
 Deferred Removal Enabled: true
 Deferred Deletion Enabled: true
 Deferred Deleted Device Count: 0
 Library Version: 1.02.107-RHEL7 (2015-12-01)
Execution Driver: native-0.2
Logging Driver: json-file
Kernel Version: 3.10.0-514.el7.x86_64
Operating System: Red Hat Enterprise Linux Server 7.3 (Maipo)
CPUs: 2
Total Memory: 2.781 GiB
Name: rhel-cdk
ID: PZ3X:6J7V:OF4L:KZRY:XXDT:QXCU:UHGQ:XMWE:EMM5:4POR:CG6D:YF4S

6.3. Learning about Containers and Images

Use the following commands to obtain information about images and containers on your system.

6.3.1. Listing Managed Images

Run the docker images command to display a list of images available in the local registry.

~]$ docker images
REPOSITORY                                                 TAG       IMAGE ID      CREATED      VIRTUAL SIZE
docker.io/prom/haproxy-exporter                            latest    2b168f203700  11 days ago  23.64 MB
registry.access.redhat.com/openshift3/ose-pod              v3.1.1.6  2b96d2bcbc46  2 weeks ago  428 MB
registry.access.redhat.com/openshift3/ose-sti-builder      v3.1.1.6  983aa720a8e7  3 weeks ago  441.9 MB
registry.access.redhat.com/openshift3/ose-deployer         v3.1.1.6  d772a87d1aac  3 weeks ago  441.9 MB
registry.access.redhat.com/openshift3/ose                  v3.1.1.6  88178069a37f  3 weeks ago  441.9 MB
registry.access.redhat.com/openshift3/ose-haproxy-router   v3.1.1.6  5e18f7fbcc6c  3 weeks ago  456.8 MB
registry.access.redhat.com/openshift3/ose-docker-registry  v3.1.1.6  3c272743b20a  3 weeks ago  478.5 MB

6.3.2. Listing Managed Containers

Run the docker ps command to display a list of running containers. Add the --all or -a parameter to list all available containers (not just the running ones). As you can see from the example output below, there are several running containers in Container Development Kit immediately after launch. These containers provide some of the services offered by Container Development Kit and as such should not be stopped or removed. The example below shows containers with the OpenShift service

Use the --format parameter to specify what information you want displayed about the individual containers (see the docker-ps(1) manual page for a list of available placeholders). For example:

~]$ docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Command}}\t{{.Status}}"
CONTAINER ID  IMAGE                                               COMMAND                 STATUS
ce4817df7620  prom/haproxy-exporter:latest                        "/bin/go-run -haproxy"  Up 55 minutes
e38b37b6e13a  openshift3/ose-docker-registry:v3.1.1.6             "/bin/sh -c 'DOCKER_R"  Up 56 minutes
8abd50d2311f  openshift3/ose-pod:v3.1.1.6                         "/pod"                  Up 56 minutes
6821a60044a8  openshift3/ose-haproxy-router:v3.1.1.6              "/usr/bin/openshift-r"  Up 56 minutes
5312e060116d  openshift3/ose-pod:v3.1.1.6                         "/pod"                  Up 56 minutes
8c94cc0c049b  registry.access.redhat.com/openshift3/ose:v3.1.1.6  "/usr/bin/openshift s"  Up 59 minutes

6.3.3. Displaying Information about Container Resource Usage

Run the docker stats <container> command to display a live output showing resource-usage statistics for a specific running container. For example:

~]$ docker stats openshift
CONTAINER  CPU %  MEM USAGE / LIMIT    MEM %  NET I/O    BLOCK I/O
openshift  0.00%  110.4 MB / 2.986 GB  3.70%  0 B / 0 B  77.24 MB / 3.708 MB

6.3.4. Displaying Detailed Information about Container or Image Configuration

Run the docker inspect <container> command to show low-level information about a container or an image in JSON format. Use the --type parameter to specify whether you want to display information about a container (the default) or an image in case you have containers and images of the same name.

Use the --format parameter to specify what part of the output you want displayed (see the docker-inspect(1) manual page for examples of the output). For example, define the following format to list network ports exposed by the container:

~]$ docker inspect --format='{{.Config.ExposedPorts}}' openshift
map[8443/tcp:{} 53/tcp:{}]

6.4. Getting New Docker-Formatted Container Images

Existing images for creating containers can be either downloaded (pulled) from one of the two pre-configured repositories (the Docker Hub (docker.io) and the Red Hat Atomic Registry (registry.access.redhat.com)) or imported from a local file.

6.4.1. Searching Registries for Images

Run the docker search <search-term> command to search the pre-configured registries for images. For example, to search for images containing the string rhscl in the name or namespace, use the following command:

~]$ docker search rhscl
INDEX        NAME                                                           DESCRIPTION                                     STARS  OFFICIAL  AUTOMAT
docker.io    docker.io/rhscl/mongodb-26-centos7                             A Centos7 based MongoDB v2.6 image for use...   0
redhat.com   registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7  Developer toolset toolchain                     0
redhat.com   registry.access.redhat.com/rhscl/httpd-24-rhel7                Apache HTTP 2.4 Server                          0
redhat.com   registry.access.redhat.com/rhscl/mariadb-100-rhel7             MariaDB 10.0 SQL database server                0
redhat.com   registry.access.redhat.com/rhscl/mongodb-26-rhel7              MongoDB 2.6 NoSQL database server               0
redhat.com   registry.access.redhat.com/rhscl/mysql-56-rhel7                MySQL 5.6 SQL database server                   0
redhat.com   registry.access.redhat.com/rhscl/nginx-16-rhel7                Nginx 1.6 server and a reverse proxy server     0
[...]

6.4.2. Downloading Images from a Registry

Run the docker pull <image> command to download (pull) the specified image to your system for local use. Note that while it is possible to provide just the name of the image, it is better practice to also specify the registry you want to pull from and the namespace in which the particular image is published. The naming convention follows this order: [registry/][namespace/]name.

For example, to pull the image with the toolchain components of the Red Hat Developer Toolset from the Red Hat Atomic Registry, use the following command:

~]$ docker pull registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7
Using default tag: latest
68f6775524af: Download complete
6c3a84d798dc: Download complete
Status: Downloaded newer image for registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7:latest

~]$ docker images registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7
REPOSITORY                                                     TAG     IMAGE ID      CREATED      VIRTUAL SIZE
registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7  latest  68f6775524af  7 weeks ago  365.5 MB

6.4.3. Loading an Image from a File

Run the docker load < file.tar command to load an image from a local file file.tar. By default, the docker pull command loads image data from the standard input. To load an image from a file, use the --input or -i parameter. For example to load the Red Hat Developer Toolset toolchain image that was previously saved to a tar file using the docker save command, use the following command:

~]$ docker load -i devtoolset.tar

6.5. Using Containers

Use the following commands to launch, stop, or remove containers or to run applications from within containers.

6.5.1. Launching a New Container and Running a Command

Run the docker run <image> <command> command to launch a new container from an image and run the specified command. Use the --name parameter to specify a name for the container to prevent the Docker service from assigning a random name to the container. For example, to run the uname -a command (and display its output) in a container created from the Red Hat Developer Toolset toolchain image, use the following command:

~]$ docker run --name devtoolset registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7 uname -a
Linux 22b819dec3f1 3.10.0-327.el7.x86_64 #1 SMP Thu Oct 29 17:29:29 EDT 2015 x86_64 x86_64 x86_64 GNU/Linux

~]$ docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Command}}\t{{.Status}}"
CONTAINER ID  NAMES       COMMAND     STATUS
22b819dec3f1  devtoolset  "uname -a"  Exited (0) 2 seconds ago
[...]

6.5.2. Stopping a Container

Run the docker stop <container> command to stop one or more containers. This action tries to gracefully shut down the applications running in the container by sending them the SIGTERM signal (followed by the SIGKILL signal if SIGTERM does not work). For example, to stop the container created in the previous example, use the following command:

~]$ docker stop devtoolset
devtoolset

~]$ docker ps | grep devtoolset

6.5.3. Starting an Existing Container

Use the docker start -i <container> command to run the container stopped in the previous example (the --interactive or -i parameter ensures that the container’s standard output is attached to your current shell — in other words, it ensures that the output of the command executed in the container is displayed):

~]$ docker start -i devtoolset
Linux 22b819dec3f1 3.10.0-327.el7.x86_64 #1 SMP Thu Oct 29 17:29:29 EDT 2015 x86_64 x86_64 x86_64 GNU/Linux

6.5.4. Launching a New Container and Switching to the Container’s Shell

Run the docker run -ti <image> bash command to launch a new container from an image and switch to an interactive shell within the container. The --interactive or -i parameter along with the --tty or -t parameter are used to allocate a pseudo-TTY within which the Bash shell is run. For example:

~]$ docker run -it registry.access.redhat.com/rhscl/devtoolset-4-toolchain-rhel7 bash
bash-4.2$ uname -a
Linux 5e224c8c3878 3.10.0-327.el7.x86_64 #1 SMP Thu Oct 29 17:29:29 EDT 2015 x86_64 x86_64 x86_64 GNU/Linux
bash-4.2$ exit
exit

~]$ docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Command}}\t{{.Status}}"
CONTAINER ID  NAMES       COMMAND     STATUS
5e224c8c3878  devtoolset  "uname -a"  Exited (0) 2 seconds ago
[...]

6.5.5. Removing a Container

Run the docker rm <container> command to remove one or more containers, thus freeing the host’s resources. For example, to remove the container created in the previous example, use the following command:

~]$ docker rm devtoolset
devtoolset

~]$ docker ps -a | grep devtoolset

6.6. Additional Resources

  • See the COMMANDS section of the docker(1) manual page for a complete list of available docker commands and detailed descriptions of their function.
  • See the Getting Started with Containers guide for detailed information about the use and management of containers on the Red Hat Enterprise Linux and Red Hat Atomic platforms.