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