Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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 Your Host System for Using Docker
Copy link

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 obtain and install the docker executable.

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. Understanding Docker Compatibility Issues
Copy link

The version of the Docker client on your host machine and the version of the Docker engine used within the Container Development Environment impose certain limitations on the way the Docker service can be used.

6.1.1.1. Docker API Compatibility
Copy link

It is necessary to use a Docker client version that uses the same Docker API version as is provided by the Container Development Kit box. In Container Development Kit 2.1, the version of the Docker API is 1.21, which can only be used with Docker clients versions 1.9.x. See the client-API version-mapping table at Docker Remote API for reference.

Other versions of the Docker client do not work properly with the Docker service provided by the Container Development Kit box. If you have a different version of the Docker client installed (for example, through you distribution’s packaging system or as a part of Docker Toolbox on Mac OS X or Windows), make sure you use the client installed by following the instructions in this section to interact with the Docker service in Container Development Kit.

6.1.1.2. Docker Registry Compatibility
Copy link

Docker registries support two different formats for images manifests. Scheme 1 is supported in Docker 1.9 and earlier. Scheme 2 is supported in Docker 1.10 and later. The two schemes are not compatible. However, Scheme 2 is automatically translated into Scheme 1 in some situations. Only some docker registries support Scheme 2 at this time.

Specifically, if Docker 1.9 is used to pull an image from a registry using Scheme 2, the registry automatically converts the manifest to Scheme 1 if the pull is done by specifying an image tag. A pull done by specifying a hash digest is not automatically converted and fails if the image was pushed to the registry using Docker 1.10 or later. If the image was pushed to the registry using Docker 1.9 or earlier, a pull using a hash digest succeeds.

Docker 1.10 supports both Scheme 1 and Scheme 2 fully and is not affected by this issue.

The Container Development Environment provides Docker 1.9, which is affected by this issue.

The official Red Hat Container Registry, which is one of the two preconfigured registries in the Container Development Environment, only uses Scheme 1 image manifests and is not affected by this incompatibility between Docker 1.9 and 1.10.

The Docker Hub registry, the other preconfigured registry in the Container Development Environment, uses Scheme 2 and is affected by this issue. Users are advised to only use name and tag-based image pulls with this registry as a workaround.

See Registry Compatibility for more information.

Note

The docker package is only available for the Server variant of Red Hat Enterprise Linux.

Install the docker package, which provides the docker executable. The package is available from the rhel-7-server-extras-rpms (Red Hat Enterprise Linux 7 Server - Extras) repository. Use the following command as root to enable the repository: 

~]# subscription-manager repos --enable=rhel-7-server-extras-rpms

Install the docker package using the following command as root: 

~]# yum install -y docker

If you already have the docker binary installed on your system (for example, as a part of the Docker Toolbox), check that it is the correct version (1.9.1) for use with the Docker service provided by the Container Development Kit virtual machine by running the following command: 

~]$ docker version
Client:
 Version:         1.9.1

[...]

If the version of the docker binary is different from what is required for working with the Docker service provided by the Container Development Kit box, or if you do not have the docker binary installed, see the following procedure.

  1. Download the docker-1.9.1 binary from https://get.docker.com/builds/Darwin/x86_64/docker-1.9.1 to a directory of your choice. In this example, the ~/docker directory is used: 

    ~]$ mkdir ~/docker

~]$ cd ~/docker

~/docker]$ wget https://get.docker.com/builds/Darwin/x86_64/docker-1.9.1

  2. Add the ~/docker directory to the PATH environmental variable, so that the docker-1.9.1 command can be used without specifying its location: 

    ~/docker]$ export PATH=$PATH:~/docker

  3. Make the binary executable: 

    ~/docker]$ chmod 764 docker-1.9.1
Note

It is only necessary to use a file name other than docker if you have (or plan to have) another version of the Docker client installed on your system. To use the Docker client installed by following the instructions in this section, remember to call the docker-1.9.1 binary. To do so, substitute the docker command used in examples in this guide with docker-1.9.1.

If you already have the docker.exe binary installed on your system (for example, as a part of the Docker Toolbox), check that it is the correct version (1.9.1) for use with the Docker service provided by the Container Development Kit virtual machine by running the following command (using the Cygwin Bash environment): 

~]$ docker version
Client:
 Version:         1.9.1

[...]

If the version of the docker.exe binary is different from what is required for working with the Docker service provided by the Container Development Kit box, or if you do not have the docker.exe binary installed, see the following procedure.

  1. Download the docker-1.9.1.exe binary from https://get.docker.com/builds/Windows/x86_64/docker-1.9.1.exe to a folder of your choice.

    Note

    It is only necessary to use a file name other than docker.exe if you have (or plan to have) another version of the Docker client installed on your system. To use the Docker client installed by following the instructions in this section, remember to call the docker-1.9.1.exe binary. To do so, substitute the docker command used in examples in this guide with docker-1.9.1.

  2. Add the C:\Program Files (x86)\docker folder to the PATH environmental variable, so that the docker-1.9.1 command can be used without specifying its location: 

    C:\> set PATH=%PATH%;"C:\Program Files (x86)\docker"

6.2. Learning about the Docker Environment
Copy link

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
Copy link

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

~]$ docker version
Client:
 Version:         1.9.1
 API version:     1.21
 Package version: docker-1.9.1-25.el7.x86_64
 Go version:      go1.4.2
 Git commit:      78ee77d/1.9.1
 Built:
 OS/Arch:         linux/amd64

Server:
 Version:         1.9.1
 API version:     1.21
 Package version: docker-1.9.1-25.el7.x86_64
 Go version:      go1.4.2
 Git commit:      78ee77d/1.9.1
 Built:
 OS/Arch:         linux/amd64

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-327.13.1.el7.x86_64
Operating System: Red Hat Enterprise Linux Server 7.2 (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
Copy link

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

6.3.1. Listing Managed Images
Copy link

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
Copy link

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

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

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
Copy link

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
Copy link

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
Copy link

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
Copy link

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
Copy link

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

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
Copy link

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
Copy link

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

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
Copy link

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
Copy link

  • 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.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top