Let’s say that you’re working on an application,
sandbox/tremaine-test-app, on your local machine and you just made the image. When you run
$ docker images, you are able to see the image amidst all the other images saved to your machine.
Now, you want to push it to your private Docker repository so that your friend across the country can pull it and then run and test it on their machine. However, you want to change the name of the image, and you want to also mark it as a
SNAPSHOT version to emphasize that it’s not really intended to be a formal release.
More than purely aesthetic reasons of possibly re-naming the image, tagging is important because it tells Docker the repository you wish to place the image in on the registry side.
The key here is to tag the image. This basically means that you re-name the image. It follows the following format:
The tags, which are optional as denoted by the parentheses, must be comprised of ASCII characters, digits, underscores, periods, and dashes; additionally, it can’t start with a period or dash, and it can’t exceed 128 characters.
yourRegistryHost:<port> corresponds with the hostname of your private Docker registry along with a port, if necessary. This is for later when you’re pushing the newly-tagged Docker image.
It turns out that there are a lot of different methods you can use to tag a local image.
Tag by Image ID
If we take a look at the list given to us by
$ docker images earlier in the article, we saw the images’ corresponding image IDs. We can use one of those in this command and Docker’s CLI will know to reference that ID.
In the earlier example,
sandbox/tremaine-test-app had both a
1.0.0 and a
latest version, but their image IDs were the same. That’s because they are the same image in reality; if there were more tags of
sandbox/tremaine-test-app with different versions, then that one may not necessarily be the latest one, and therefore they may have different image IDs.
In this example, and all the subsequent ones, we are tagging our local
sandbox/tremaine-test-app image with
By doing that, we’re saying that we want to have a new tag of the image called
hello-world with version tag
1.0.0-SNAPSHOT to be placed in the
Tag by Image Name
In this case, we explicitly use the image name to be used as the source image. I like this approach because it’s easier for me to remember my image name as opposed to copy and pasting the image ID.
In this case, we did not specify a tag in our source (leftmost) image, and so Docker will infer that it is for the
Tag by Name and Tag
This is quite similar to the last example, but in this one, we didn’t want it to default to the
latest tag for the source image. Therefore, we specified
Now that we have our tagged image,
yourRegistryHost:<port>/tremaine/hello-world:1.0.0-SNAPSHOT, we can push it to our private Docker registry with a simple command:
Since we already have the Docker host in the image, Docker will know to push it there.
The push will take a little bit of time, but when it’s all said and done, your friend will be able to run
$ docker pull to pull the image to their machine and then run it as they please.
In a later article to be linked here when published, I will go over some finer details and options available with
$ docker push.