github.com/vieux/docker@v0.6.3-0.20161004191708-e097c2a938c7/docs/tutorials/dockerimages.md (about)

     1  <!--[metadata]>
     2  +++
     3  aliases = [
     4  "/engine/userguide/containers/dockerimages/",
     5  "/engine/userguide/dockerimages/"
     6  ]
     7  title = "Build your own images"
     8  description = "How to work with Docker images."
     9  keywords = ["documentation, docs, the docker guide, docker guide, docker, docker platform, docker.io, Docker images, Docker image, image management, Docker repos, Docker repositories, docker, docker tag, docker tags, Docker Hub,  collaboration"]
    10  [menu.main]
    11  parent = "engine_learn_menu"
    12  weight = -4
    13  +++
    14  <![end-metadata]-->
    15  
    16  # Build your own images
    17  
    18  Docker images are the basis of containers. Each time you've used `docker run`
    19  you told it which image you wanted. In the previous sections of the guide you
    20  used Docker images that already exist, for example the `ubuntu` image and the
    21  `training/webapp` image.
    22  
    23  You also discovered that Docker stores downloaded images on the Docker host. If
    24  an image isn't already present on the host then it'll be downloaded from a
    25  registry: by default the [Docker Hub Registry](https://hub.docker.com).
    26  
    27  In this section you're going to explore Docker images a bit more
    28  including:
    29  
    30  * Managing and working with images locally on your Docker host.
    31  * Creating basic images.
    32  * Uploading images to [Docker Hub Registry](https://hub.docker.com).
    33  
    34  ## Listing images on the host
    35  
    36  Let's start with listing the images you have locally on our host. You can
    37  do this using the `docker images` command like so:
    38  
    39      $ docker images
    40  
    41      REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
    42      ubuntu              14.04               1d073211c498        3 days ago          187.9 MB
    43      busybox             latest              2c5ac3f849df        5 days ago          1.113 MB
    44      training/webapp     latest              54bb4e8718e8        5 months ago        348.7 MB
    45  
    46  You can see the images you've previously used in the user guide.
    47  Each has been downloaded from [Docker Hub](https://hub.docker.com) when you
    48  launched a container using that image. When you list images, you get three crucial pieces of information in the listing.
    49  
    50  * What repository they came from, for example `ubuntu`.
    51  * The tags for each image, for example `14.04`.
    52  * The image ID of each image.
    53  
    54  > **Tip:**
    55  > You can use [a third-party dockviz tool](https://github.com/justone/dockviz)
    56  > or the [Image layers site](https://imagelayers.io/) to display  
    57  > visualizations of image data.
    58  
    59  A repository potentially holds multiple variants of an image. In the case of
    60  our `ubuntu` image you can see multiple variants covering Ubuntu 10.04, 12.04,
    61  12.10, 13.04, 13.10 and 14.04. Each variant is identified by a tag and you can
    62  refer to a tagged image like so:
    63  
    64      ubuntu:14.04
    65  
    66  So when you run a container you refer to a tagged image like so:
    67  
    68      $ docker run -t -i ubuntu:14.04 /bin/bash
    69  
    70  If instead you wanted to run an Ubuntu 12.04 image you'd use:
    71  
    72      $ docker run -t -i ubuntu:12.04 /bin/bash
    73  
    74  If you don't specify a variant, for example you just use `ubuntu`, then Docker
    75  will default to using the `ubuntu:latest` image.
    76  
    77  > **Tip:**
    78  > You should always specify an image tag, for example `ubuntu:14.04`.
    79  > That way, you always know exactly what variant of an image you are using.
    80  > This is useful for troubleshooting and debugging.
    81  
    82  ## Getting a new image
    83  
    84  So how do you get new images? Well Docker will automatically download any image
    85  you use that isn't already present on the Docker host. But this can potentially
    86  add some time to the launch of a container. If you want to pre-load an image you
    87  can download it using the `docker pull` command. Suppose you'd like to
    88  download the `centos` image.
    89  
    90      $ docker pull centos
    91  
    92      Using default tag: latest
    93      latest: Pulling from library/centos
    94      f1b10cd84249: Pull complete
    95      c852f6d61e65: Pull complete
    96      7322fbe74aa5: Pull complete
    97      Digest: sha256:90305c9112250c7e3746425477f1c4ef112b03b4abe78c612e092037bfecc3b7
    98      Status: Downloaded newer image for centos:latest
    99  
   100  You can see that each layer of the image has been pulled down and now you
   101  can run a container from this image and you won't have to wait to
   102  download the image.
   103  
   104      $ docker run -t -i centos /bin/bash
   105  
   106      bash-4.1#
   107  
   108  ## Finding images
   109  
   110  One of the features of Docker is that a lot of people have created Docker
   111  images for a variety of purposes. Many of these have been uploaded to
   112  [Docker Hub](https://hub.docker.com). You can search these images on the
   113  [Docker Hub](https://hub.docker.com) website.
   114  
   115  ![indexsearch](search.png)
   116  
   117  You can also search for images on the command line using the `docker search`
   118  command. Suppose your team wants an image with Ruby and Sinatra installed on
   119  which to do our web application development. You can search for a suitable image
   120  by using the `docker search` command to find all the images that contain the
   121  term `sinatra`.
   122  
   123      $ docker search sinatra
   124      NAME                                   DESCRIPTION                                     STARS     OFFICIAL   AUTOMATED
   125      training/sinatra                       Sinatra training image                          0                    [OK]
   126      marceldegraaf/sinatra                  Sinatra test app                                0
   127      mattwarren/docker-sinatra-demo                                                         0                    [OK]
   128      luisbebop/docker-sinatra-hello-world                                                   0                    [OK]
   129      bmorearty/handson-sinatra              handson-ruby + Sinatra for Hands on with D...   0
   130      subwiz/sinatra                                                                         0
   131      bmorearty/sinatra                                                                      0
   132      . . .
   133  
   134  You can see the command returns a lot of images that use the term `sinatra`.
   135  You've received a list of image names, descriptions, Stars (which measure the
   136  social popularity of images - if a user likes an image then they can "star" it),
   137  and the Official and Automated build statuses. [Official
   138  Repositories](https://docs.docker.com/docker-hub/official_repos) are a carefully
   139  curated set of Docker repositories supported by Docker, Inc.  Automated
   140  repositories are [Automated Builds](dockerrepos.md#automated-builds) that allow
   141  you to validate the source and content of an image.
   142  
   143  You've reviewed the images available to use and you decided to use the
   144  `training/sinatra` image. So far you've seen two types of images repositories,
   145  images like `ubuntu`, which are called base or root images. These base images
   146  are provided by Docker Inc and are built, validated and supported. These can be
   147  identified by their single word names.
   148  
   149  You've also seen user images, for example the `training/sinatra` image you've
   150  chosen. A user image belongs to a member of the Docker community and is built
   151  and maintained by them.  You can identify user images as they are always
   152  prefixed with the user name, here `training`, of the user that created them.
   153  
   154  ## Pulling our image
   155  
   156  You've identified a suitable image, `training/sinatra`, and now you can download it using the `docker pull` command.
   157  
   158      $ docker pull training/sinatra
   159  
   160  The team can now use this image by running their own containers.
   161  
   162      $ docker run -t -i training/sinatra /bin/bash
   163  
   164      root@a8cb6ce02d85:/#
   165  
   166  ## Creating our own images
   167  
   168  The team has found the `training/sinatra` image pretty useful but it's not quite
   169  what they need and you need to make some changes to it. There are two ways you
   170  can update and create images.
   171  
   172  1. You can update a container created from an image and commit the results to an image.
   173  2. You can use a `Dockerfile` to specify instructions to create an image.
   174  
   175  
   176  ### Updating and committing an image
   177  
   178  To update an image you first need to create a container from the image
   179  you'd like to update.
   180  
   181      $ docker run -t -i training/sinatra /bin/bash
   182  
   183      root@0b2616b0e5a8:/#
   184  
   185  > **Note:**
   186  > Take note of the container ID that has been created, `0b2616b0e5a8`, as you'll
   187  > need it in a moment.
   188  
   189  Inside our running container first let's update Ruby:
   190  
   191      root@0b2616b0e5a8:/# apt-get install -y ruby2.0-dev
   192  
   193  Now let's add the `json` gem.
   194  
   195      root@0b2616b0e5a8:/# gem2.0 install json
   196  
   197  Once this has completed let's exit our container using the `exit`
   198  command.
   199  
   200  Now you have a container with the change you want to make. You can then
   201  commit a copy of this container to an image using the `docker commit`
   202  command.
   203  
   204      $ docker commit -m "Added json gem" -a "Kate Smith" \
   205      0b2616b0e5a8 ouruser/sinatra:v2
   206  
   207      4f177bd27a9ff0f6dc2a830403925b5360bfe0b93d476f7fc3231110e7f71b1c
   208  
   209  Here you've used the `docker commit` command. You've specified two flags: `-m`
   210  and `-a`. The `-m` flag allows us to specify a commit message, much like you
   211  would with a commit on a version control system. The `-a` flag allows us to
   212  specify an author for our update.
   213  
   214  You've also specified the container you want to create this new image from,
   215  `0b2616b0e5a8` (the ID you recorded earlier) and you've specified a target for
   216  the image:
   217  
   218      ouruser/sinatra:v2
   219  
   220  Break this target down. It consists of a new user, `ouruser`, that you're
   221  writing this image to. You've also specified the name of the image, here you're
   222  keeping the original image name `sinatra`. Finally you're specifying a tag for
   223  the image: `v2`.
   224  
   225  You can then look at our new `ouruser/sinatra` image using the `docker images`
   226  command.
   227  
   228      $ docker images
   229  
   230      REPOSITORY          TAG     IMAGE ID       CREATED       SIZE
   231      training/sinatra    latest  5bc342fa0b91   10 hours ago  446.7 MB
   232      ouruser/sinatra     v2      3c59e02ddd1a   10 hours ago  446.7 MB
   233      ouruser/sinatra     latest  5db5f8471261   10 hours ago  446.7 MB
   234  
   235  To use our new image to create a container you can then:
   236  
   237      $ docker run -t -i ouruser/sinatra:v2 /bin/bash
   238  
   239      root@78e82f680994:/#
   240  
   241  ### Building an image from a `Dockerfile`
   242  
   243  Using the `docker commit` command is a pretty simple way of extending an image
   244  but it's a bit cumbersome and it's not easy to share a development process for
   245  images amongst a team. Instead you can use a new command, `docker build`, to
   246  build new images from scratch.
   247  
   248  To do this you create a `Dockerfile` that contains a set of instructions that
   249  tell Docker how to build our image.
   250  
   251  First, create a directory and a `Dockerfile`.
   252  
   253      $ mkdir sinatra
   254  
   255      $ cd sinatra
   256  
   257      $ touch Dockerfile
   258  
   259  If you are using Docker Machine on Windows, you may access your host
   260  directory by `cd` to `/c/Users/your_user_name`.
   261  
   262  Each instruction creates a new layer of the image. Try a simple example now for
   263  building your own Sinatra image for your fictitious development team.
   264  
   265      # This is a comment
   266      FROM ubuntu:14.04
   267      RUN apt-get update && apt-get install -y ruby ruby-dev
   268      RUN gem install sinatra
   269  
   270  Examine what your `Dockerfile` does. Each instruction prefixes a statement and
   271  is capitalized.
   272  
   273      INSTRUCTION statement
   274  
   275  > **Note:** You use `#` to indicate a comment
   276  
   277  The first instruction `FROM` tells Docker what the source of our image is, in
   278  this case you're basing our new image on an Ubuntu 14.04 image.
   279  
   280  Lastly, you've specified two `RUN` instructions. A `RUN` instruction executes
   281  a command inside the image, for example installing a package. Here you're
   282  updating our APT cache, installing Ruby and RubyGems and then installing the
   283  Sinatra gem.
   284  
   285  
   286  
   287  Now let's take our `Dockerfile` and use the `docker build` command to build an image.
   288  
   289      $ docker build -t ouruser/sinatra:v2 .
   290  
   291      Sending build context to Docker daemon 2.048 kB
   292      Sending build context to Docker daemon
   293      Step 1 : FROM ubuntu:14.04
   294       ---> e54ca5efa2e9
   295      Step 2 : RUN apt-get update && apt-get install -y ruby ruby-dev
   296       ---> Running in 3a2558904e9b
   297      Selecting previously unselected package libasan0:amd64.
   298      (Reading database ... 11518 files and directories currently installed.)
   299      Preparing to unpack .../libasan0_4.8.2-19ubuntu1_amd64.deb ...
   300      Unpacking libasan0:amd64 (4.8.2-19ubuntu1) ...
   301      Selecting previously unselected package libatomic1:amd64.
   302      Preparing to unpack .../libatomic1_4.8.2-19ubuntu1_amd64.deb ...
   303      Unpacking libatomic1:amd64 (4.8.2-19ubuntu1) ...
   304      Selecting previously unselected package libgmp10:amd64.
   305      Preparing to unpack .../libgmp10_2%3a5.1.3+dfsg-1ubuntu1_amd64.deb ...
   306      Unpacking libgmp10:amd64 (2:5.1.3+dfsg-1ubuntu1) ...
   307      Selecting previously unselected package libisl10:amd64.
   308      Preparing to unpack .../libisl10_0.12.2-1_amd64.deb ...
   309      Unpacking libisl10:amd64 (0.12.2-1) ...
   310      Selecting previously unselected package libcloog-isl4:amd64.
   311      Preparing to unpack .../libcloog-isl4_0.18.2-1_amd64.deb ...
   312      Unpacking libcloog-isl4:amd64 (0.18.2-1) ...
   313      Selecting previously unselected package libgomp1:amd64.
   314      Preparing to unpack .../libgomp1_4.8.2-19ubuntu1_amd64.deb ...
   315      Unpacking libgomp1:amd64 (4.8.2-19ubuntu1) ...
   316      Selecting previously unselected package libitm1:amd64.
   317      Preparing to unpack .../libitm1_4.8.2-19ubuntu1_amd64.deb ...
   318      Unpacking libitm1:amd64 (4.8.2-19ubuntu1) ...
   319      Selecting previously unselected package libmpfr4:amd64.
   320      Preparing to unpack .../libmpfr4_3.1.2-1_amd64.deb ...
   321      Unpacking libmpfr4:amd64 (3.1.2-1) ...
   322      Selecting previously unselected package libquadmath0:amd64.
   323      Preparing to unpack .../libquadmath0_4.8.2-19ubuntu1_amd64.deb ...
   324      Unpacking libquadmath0:amd64 (4.8.2-19ubuntu1) ...
   325      Selecting previously unselected package libtsan0:amd64.
   326      Preparing to unpack .../libtsan0_4.8.2-19ubuntu1_amd64.deb ...
   327      Unpacking libtsan0:amd64 (4.8.2-19ubuntu1) ...
   328      Selecting previously unselected package libyaml-0-2:amd64.
   329      Preparing to unpack .../libyaml-0-2_0.1.4-3ubuntu3_amd64.deb ...
   330      Unpacking libyaml-0-2:amd64 (0.1.4-3ubuntu3) ...
   331      Selecting previously unselected package libmpc3:amd64.
   332      Preparing to unpack .../libmpc3_1.0.1-1ubuntu1_amd64.deb ...
   333      Unpacking libmpc3:amd64 (1.0.1-1ubuntu1) ...
   334      Selecting previously unselected package openssl.
   335      Preparing to unpack .../openssl_1.0.1f-1ubuntu2.4_amd64.deb ...
   336      Unpacking openssl (1.0.1f-1ubuntu2.4) ...
   337      Selecting previously unselected package ca-certificates.
   338      Preparing to unpack .../ca-certificates_20130906ubuntu2_all.deb ...
   339      Unpacking ca-certificates (20130906ubuntu2) ...
   340      Selecting previously unselected package manpages.
   341      Preparing to unpack .../manpages_3.54-1ubuntu1_all.deb ...
   342      Unpacking manpages (3.54-1ubuntu1) ...
   343      Selecting previously unselected package binutils.
   344      Preparing to unpack .../binutils_2.24-5ubuntu3_amd64.deb ...
   345      Unpacking binutils (2.24-5ubuntu3) ...
   346      Selecting previously unselected package cpp-4.8.
   347      Preparing to unpack .../cpp-4.8_4.8.2-19ubuntu1_amd64.deb ...
   348      Unpacking cpp-4.8 (4.8.2-19ubuntu1) ...
   349      Selecting previously unselected package cpp.
   350      Preparing to unpack .../cpp_4%3a4.8.2-1ubuntu6_amd64.deb ...
   351      Unpacking cpp (4:4.8.2-1ubuntu6) ...
   352      Selecting previously unselected package libgcc-4.8-dev:amd64.
   353      Preparing to unpack .../libgcc-4.8-dev_4.8.2-19ubuntu1_amd64.deb ...
   354      Unpacking libgcc-4.8-dev:amd64 (4.8.2-19ubuntu1) ...
   355      Selecting previously unselected package gcc-4.8.
   356      Preparing to unpack .../gcc-4.8_4.8.2-19ubuntu1_amd64.deb ...
   357      Unpacking gcc-4.8 (4.8.2-19ubuntu1) ...
   358      Selecting previously unselected package gcc.
   359      Preparing to unpack .../gcc_4%3a4.8.2-1ubuntu6_amd64.deb ...
   360      Unpacking gcc (4:4.8.2-1ubuntu6) ...
   361      Selecting previously unselected package libc-dev-bin.
   362      Preparing to unpack .../libc-dev-bin_2.19-0ubuntu6_amd64.deb ...
   363      Unpacking libc-dev-bin (2.19-0ubuntu6) ...
   364      Selecting previously unselected package linux-libc-dev:amd64.
   365      Preparing to unpack .../linux-libc-dev_3.13.0-30.55_amd64.deb ...
   366      Unpacking linux-libc-dev:amd64 (3.13.0-30.55) ...
   367      Selecting previously unselected package libc6-dev:amd64.
   368      Preparing to unpack .../libc6-dev_2.19-0ubuntu6_amd64.deb ...
   369      Unpacking libc6-dev:amd64 (2.19-0ubuntu6) ...
   370      Selecting previously unselected package ruby.
   371      Preparing to unpack .../ruby_1%3a1.9.3.4_all.deb ...
   372      Unpacking ruby (1:1.9.3.4) ...
   373      Selecting previously unselected package ruby1.9.1.
   374      Preparing to unpack .../ruby1.9.1_1.9.3.484-2ubuntu1_amd64.deb ...
   375      Unpacking ruby1.9.1 (1.9.3.484-2ubuntu1) ...
   376      Selecting previously unselected package libruby1.9.1.
   377      Preparing to unpack .../libruby1.9.1_1.9.3.484-2ubuntu1_amd64.deb ...
   378      Unpacking libruby1.9.1 (1.9.3.484-2ubuntu1) ...
   379      Selecting previously unselected package manpages-dev.
   380      Preparing to unpack .../manpages-dev_3.54-1ubuntu1_all.deb ...
   381      Unpacking manpages-dev (3.54-1ubuntu1) ...
   382      Selecting previously unselected package ruby1.9.1-dev.
   383      Preparing to unpack .../ruby1.9.1-dev_1.9.3.484-2ubuntu1_amd64.deb ...
   384      Unpacking ruby1.9.1-dev (1.9.3.484-2ubuntu1) ...
   385      Selecting previously unselected package ruby-dev.
   386      Preparing to unpack .../ruby-dev_1%3a1.9.3.4_all.deb ...
   387      Unpacking ruby-dev (1:1.9.3.4) ...
   388      Setting up libasan0:amd64 (4.8.2-19ubuntu1) ...
   389      Setting up libatomic1:amd64 (4.8.2-19ubuntu1) ...
   390      Setting up libgmp10:amd64 (2:5.1.3+dfsg-1ubuntu1) ...
   391      Setting up libisl10:amd64 (0.12.2-1) ...
   392      Setting up libcloog-isl4:amd64 (0.18.2-1) ...
   393      Setting up libgomp1:amd64 (4.8.2-19ubuntu1) ...
   394      Setting up libitm1:amd64 (4.8.2-19ubuntu1) ...
   395      Setting up libmpfr4:amd64 (3.1.2-1) ...
   396      Setting up libquadmath0:amd64 (4.8.2-19ubuntu1) ...
   397      Setting up libtsan0:amd64 (4.8.2-19ubuntu1) ...
   398      Setting up libyaml-0-2:amd64 (0.1.4-3ubuntu3) ...
   399      Setting up libmpc3:amd64 (1.0.1-1ubuntu1) ...
   400      Setting up openssl (1.0.1f-1ubuntu2.4) ...
   401      Setting up ca-certificates (20130906ubuntu2) ...
   402      debconf: unable to initialize frontend: Dialog
   403      debconf: (TERM is not set, so the dialog frontend is not usable.)
   404      debconf: falling back to frontend: Readline
   405      debconf: unable to initialize frontend: Readline
   406      debconf: (This frontend requires a controlling tty.)
   407      debconf: falling back to frontend: Teletype
   408      Setting up manpages (3.54-1ubuntu1) ...
   409      Setting up binutils (2.24-5ubuntu3) ...
   410      Setting up cpp-4.8 (4.8.2-19ubuntu1) ...
   411      Setting up cpp (4:4.8.2-1ubuntu6) ...
   412      Setting up libgcc-4.8-dev:amd64 (4.8.2-19ubuntu1) ...
   413      Setting up gcc-4.8 (4.8.2-19ubuntu1) ...
   414      Setting up gcc (4:4.8.2-1ubuntu6) ...
   415      Setting up libc-dev-bin (2.19-0ubuntu6) ...
   416      Setting up linux-libc-dev:amd64 (3.13.0-30.55) ...
   417      Setting up libc6-dev:amd64 (2.19-0ubuntu6) ...
   418      Setting up manpages-dev (3.54-1ubuntu1) ...
   419      Setting up libruby1.9.1 (1.9.3.484-2ubuntu1) ...
   420      Setting up ruby1.9.1-dev (1.9.3.484-2ubuntu1) ...
   421      Setting up ruby-dev (1:1.9.3.4) ...
   422      Setting up ruby (1:1.9.3.4) ...
   423      Setting up ruby1.9.1 (1.9.3.484-2ubuntu1) ...
   424      Processing triggers for libc-bin (2.19-0ubuntu6) ...
   425      Processing triggers for ca-certificates (20130906ubuntu2) ...
   426      Updating certificates in /etc/ssl/certs... 164 added, 0 removed; done.
   427      Running hooks in /etc/ca-certificates/update.d....done.
   428       ---> c55c31703134
   429      Removing intermediate container 3a2558904e9b
   430      Step 3 : RUN gem install sinatra
   431       ---> Running in 6b81cb6313e5
   432      unable to convert "\xC3" to UTF-8 in conversion from ASCII-8BIT to UTF-8 to US-ASCII for README.rdoc, skipping
   433      unable to convert "\xC3" to UTF-8 in conversion from ASCII-8BIT to UTF-8 to US-ASCII for README.rdoc, skipping
   434      Successfully installed rack-1.5.2
   435      Successfully installed tilt-1.4.1
   436      Successfully installed rack-protection-1.5.3
   437      Successfully installed sinatra-1.4.5
   438      4 gems installed
   439      Installing ri documentation for rack-1.5.2...
   440      Installing ri documentation for tilt-1.4.1...
   441      Installing ri documentation for rack-protection-1.5.3...
   442      Installing ri documentation for sinatra-1.4.5...
   443      Installing RDoc documentation for rack-1.5.2...
   444      Installing RDoc documentation for tilt-1.4.1...
   445      Installing RDoc documentation for rack-protection-1.5.3...
   446      Installing RDoc documentation for sinatra-1.4.5...
   447       ---> 97feabe5d2ed
   448      Removing intermediate container 6b81cb6313e5
   449      Successfully built 97feabe5d2ed
   450  
   451  You've specified our `docker build` command and used the `-t` flag to identify
   452  our new image as belonging to the user `ouruser`, the repository name `sinatra`
   453  and given it the tag `v2`.
   454  
   455  You've also specified the location of our `Dockerfile` using the `.` to
   456  indicate a `Dockerfile` in the current directory.
   457  
   458  > **Note:**
   459  > You can also specify a path to a `Dockerfile`.
   460  
   461  Now you can see the build process at work. The first thing Docker does is
   462  upload the build context: basically the contents of the directory you're
   463  building in. This is done because the Docker daemon does the actual
   464  build of the image and it needs the local context to do it.
   465  
   466  Next you can see each instruction in the `Dockerfile` being executed
   467  step-by-step. You can see that each step creates a new container, runs
   468  the instruction inside that container and then commits that change -
   469  just like the `docker commit` work flow you saw earlier. When all the
   470  instructions have executed you're left with the `97feabe5d2ed` image
   471  (also helpfuly tagged as `ouruser/sinatra:v2`) and all intermediate
   472  containers will get removed to clean things up.
   473  
   474  > **Note:**
   475  > An image can't have more than 127 layers regardless of the storage driver.
   476  > This limitation is set globally to encourage optimization of the overall
   477  > size of images.
   478  
   479  You can then create a container from our new image.
   480  
   481      $ docker run -t -i ouruser/sinatra:v2 /bin/bash
   482  
   483      root@8196968dac35:/#
   484  
   485  > **Note:**
   486  > This is just a brief introduction to creating images. We've
   487  > skipped a whole bunch of other instructions that you can use. We'll see more of
   488  > those instructions in later sections of the Guide or you can refer to the
   489  > [`Dockerfile`](../reference/builder.md) reference for a
   490  > detailed description and examples of every instruction.
   491  > To help you write a clear, readable, maintainable `Dockerfile`, we've also
   492  > written a [`Dockerfile` Best Practices guide](../userguide/eng-image/dockerfile_best-practices.md).
   493  
   494  
   495  ## Setting tags on an image
   496  
   497  You can also add a tag to an existing image after you commit or build it. We
   498  can do this using the `docker tag` command. Now, add a new tag to your
   499  `ouruser/sinatra` image.
   500  
   501      $ docker tag 5db5f8471261 ouruser/sinatra:devel
   502  
   503  The `docker tag` command takes the ID of the image, here `5db5f8471261`, and our
   504  user name, the repository name and the new tag.
   505  
   506  Now, see your new tag using the `docker images` command.
   507  
   508      $ docker images ouruser/sinatra
   509  
   510      REPOSITORY          TAG     IMAGE ID      CREATED        SIZE
   511      ouruser/sinatra     latest  5db5f8471261  11 hours ago   446.7 MB
   512      ouruser/sinatra     devel   5db5f8471261  11 hours ago   446.7 MB
   513      ouruser/sinatra     v2      5db5f8471261  11 hours ago   446.7 MB
   514  
   515  ## Image Digests
   516  
   517  Images that use the v2 or later format have a content-addressable identifier
   518  called a `digest`. As long as the input used to generate the image is
   519  unchanged, the digest value is predictable. To list image digest values, use
   520  the `--digests` flag:
   521  
   522      $ docker images --digests | head
   523  
   524      REPOSITORY        TAG      DIGEST                                                                     IMAGE ID      CREATED       SIZE
   525      ouruser/sinatra   latest   sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf    5db5f8471261  11 hours ago  446.7 MB
   526  
   527  When pushing or pulling to a 2.0 registry, the `push` or `pull` command
   528  output includes the image digest. You can `pull` using a digest value.
   529  
   530      $ docker pull ouruser/sinatra@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf
   531  
   532  You can also reference by digest in `create`, `run`, and `rmi` commands, as well as the
   533  `FROM` image reference in a Dockerfile.
   534  
   535  ## Push an image to Docker Hub
   536  
   537  Once you've built or created a new image you can push it to [Docker
   538  Hub](https://hub.docker.com) using the `docker push` command. This
   539  allows you to share it with others, either publicly, or push it into [a
   540  private repository](https://hub.docker.com/account/billing-plans/).
   541  
   542      $ docker push ouruser/sinatra
   543  
   544      The push refers to a repository [ouruser/sinatra] (len: 1)
   545      Sending image list
   546      Pushing repository ouruser/sinatra (3 tags)
   547      . . .
   548  
   549  ## Remove an image from the host
   550  
   551  You can also remove images on your Docker host in a way [similar to
   552  containers](usingdocker.md) using the `docker rmi` command.
   553  
   554  Delete the `training/sinatra` image as you don't need it anymore.
   555  
   556      $ docker rmi training/sinatra
   557  
   558      Untagged: training/sinatra:latest
   559      Deleted: 5bc342fa0b91cabf65246837015197eecfa24b2213ed6a51a8974ae250fedd8d
   560      Deleted: ed0fffdcdae5eb2c3a55549857a8be7fc8bc4241fb19ad714364cbfd7a56b22f
   561      Deleted: 5c58979d73ae448df5af1d8142436d81116187a7633082650549c52c3a2418f0
   562  
   563  > **Note:** To remove an image from the host, please make sure
   564  > that there are no containers actively based on it.
   565  
   566  # Next steps
   567  
   568  Until now you've seen how to build individual applications inside Docker
   569  containers. Now learn how to build whole application stacks with Docker
   570  by networking together multiple Docker containers.
   571  
   572  Go to [Network containers](networkingcontainers.md).