From 2cb184ade59ccb578d50f5ff535d1d02e7855563 Mon Sep 17 00:00:00 2001 From: William Henry Date: Tue, 27 May 2014 11:56:11 -0600 Subject: [PATCH 1/4] Some changes to semantics around tagging, detaching. Tried to clarify some of the semantics regarding --tag and renaming etc. Added some text clarifying how to detach from a running containers. Fixed a bug that reference /varlog instead of /dev/log. Docker-DCO-1.1-Signed-off-by: William Henry (github: ipbabble) Changes to be committed: modified: docker-attach.1.md modified: docker-build.1.md modified: docker-run.1.md modified: docker-tag.1.md --- contrib/man/md/docker-attach.1.md | 7 +++--- contrib/man/md/docker-build.1.md | 37 +++++++++++++++++++++++++++++-- contrib/man/md/docker-run.1.md | 5 ++++- contrib/man/md/docker-tag.1.md | 9 +++++--- 4 files changed, 49 insertions(+), 9 deletions(-) diff --git a/contrib/man/md/docker-attach.1.md b/contrib/man/md/docker-attach.1.md index 2755fd27f5..5a3b7a2856 100644 --- a/contrib/man/md/docker-attach.1.md +++ b/contrib/man/md/docker-attach.1.md @@ -9,10 +9,11 @@ docker-attach - Attach to a running container # DESCRIPTION If you **docker run** a container in detached mode (**-d**), you can reattach to - the detached container with **docker attach** using the container's ID or name. +the detached container with **docker attach** using the container's ID or name. -You can detach from the container again (and leave it running) with `CTRL-c` (for -a quiet exit) or `CTRL-\` to get a stacktrace of the Docker client when it quits. +You can detach from the container again (and leave it running) with `CTRL-q +CTRL-q` (for a quiet exit), or `CTRL-c` which will send a SIGKILL to the +container, or `CTRL-\` to get a stacktrace of the Docker client when it quits. When you detach from a container the exit code will be returned to the client. diff --git a/contrib/man/md/docker-build.1.md b/contrib/man/md/docker-build.1.md index b3e9a2842e..f242bdd2c9 100644 --- a/contrib/man/md/docker-build.1.md +++ b/contrib/man/md/docker-build.1.md @@ -34,8 +34,9 @@ as context. build process. The default is true. **-t**, **--tag**=*tag* - Tag to be applied to the resulting image on successful completion of -the build. + The name to be applied to the resulting image on successful completion of +the build. 'Tag' is this context means the entire image name including the +optional TAG after the ':'. **--no-cache**=*true*|*false* When set to true, do not use a cache when building the image. The @@ -66,6 +67,38 @@ in the Dockerfile. Note: If you include a tar file (a good practice!), then Docker will automatically extract the contents of the tar file specified within the `ADD` instruction into the specified target. +## Building an image and naming that image + +A good practice is to give a name to the image you are building. There are +not hard rules here but it is best to give the names consideration. + +The '-t'/'--tag' flag is used to rename an image. Here are some examples: + +Though not a good practice image names can be aribtrary: + + docker build -t myimage . + +Better is provide a fully qualified and meaningful repository name, name, +and tag (where tag in this context means the qualifier after the ':'). In +this example we build a Jboss image for the Fedora repository and give it +a version 1.0: + + docker build -t fedora/jboss:1.0 + +The next example is for the 'whenry' user repository and uses Fedora and +JBoss and gives it a version 2.1 : + + docker build -t whenry/fedora-jboss:V2.1 + +Or: + + docker build -t whenry/fedora-jboss:latest + +So renaming an image is arbitrary but consideration should be given to +a useful convention that makes sense for consumers and should also take +into account Docker community conventions. + + ## Building an image using a URL This will clone the specified Github repository from the URL and use it diff --git a/contrib/man/md/docker-run.1.md b/contrib/man/md/docker-run.1.md index 2ebf82b6a5..72b01419bf 100644 --- a/contrib/man/md/docker-run.1.md +++ b/contrib/man/md/docker-run.1.md @@ -64,6 +64,9 @@ the other shell to view a list of the running containers. You can reattach to a detached container with **docker attach**. If you choose to run a container in the detached mode, then you cannot use the **-rm** option. + When attached in tty mode, you can detach from a running container by pressing +the keys ctrl+p ctrl+q. + **--dns**=*IP-address* Set custom DNS servers. This option can be used to override the DNS @@ -237,7 +240,7 @@ can override the working directory by using the **-w** option. ## Exposing log messages from the container to the host's log If you want messages that are logged in your container to show up in the host's -syslog/journal then you should bind mount the /var/log directory as follows. +syslog/journal then you should bind mount the /dev/log directory as follows. # docker run -v /dev/log:/dev/log -i -t fedora /bin/bash diff --git a/contrib/man/md/docker-tag.1.md b/contrib/man/md/docker-tag.1.md index 49f5a6c4d1..687b6ddb47 100644 --- a/contrib/man/md/docker-tag.1.md +++ b/contrib/man/md/docker-tag.1.md @@ -9,7 +9,8 @@ docker-tag - Tag an image in the repository IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG] # DESCRIPTION -This will tag an image in the repository. +This will rename an image in the repository. "Tag" is this context means the +entire image name including the optional TAG after the ':'. # "OPTIONS" **-f**, **--force**=*true*|*false* @@ -26,13 +27,15 @@ separated by a ':' The image name. **TAG** - The tag you are assigning to the image. + The tag you are assigning to the image. This is often a version or other +'tag' to distinguish from other similarly named images. # EXAMPLES ## Tagging an image -Here is an example of tagging an image with the tag version1.0 : +Here is an example of renaming an image with the repository 'fedora', name +'httpd', and tag version1.0 : docker tag 0e5574283393 fedora/httpd:version1.0 From a14a88e53dc71b1013d7b629d23d3908d15d57f4 Mon Sep 17 00:00:00 2001 From: William Henry Date: Tue, 27 May 2014 12:05:48 -0600 Subject: [PATCH 2/4] Fixed some typos in docker-build. Docker-DCO-1.1-Signed-off-by: William Henry (github: ipbabble) Changes to be committed: modified: contrib/man/md/docker-build.1.md --- contrib/man/md/docker-build.1.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/contrib/man/md/docker-build.1.md b/contrib/man/md/docker-build.1.md index f242bdd2c9..da4f5c017e 100644 --- a/contrib/man/md/docker-build.1.md +++ b/contrib/man/md/docker-build.1.md @@ -35,7 +35,7 @@ build process. The default is true. **-t**, **--tag**=*tag* The name to be applied to the resulting image on successful completion of -the build. 'Tag' is this context means the entire image name including the +the build. `tag` in this context means the entire image name including the optional TAG after the ':'. **--no-cache**=*true*|*false* @@ -72,20 +72,20 @@ specified within the `ADD` instruction into the specified target. A good practice is to give a name to the image you are building. There are not hard rules here but it is best to give the names consideration. -The '-t'/'--tag' flag is used to rename an image. Here are some examples: +The **-t**/**--tag** flag is used to rename an image. Here are some examples: -Though not a good practice image names can be aribtrary: +Though t is not good practice, image names can be aribtrary: docker build -t myimage . -Better is provide a fully qualified and meaningful repository name, name, -and tag (where tag in this context means the qualifier after the ':'). In -this example we build a Jboss image for the Fedora repository and give it -a version 1.0: +A better approach is provide a fully qualified and meaningful repository +name, name, and tag (where tag in this context means the qualifier after +the ":"). In this example we build a Jboss image for the Fedora repository +and give it a version 1.0: docker build -t fedora/jboss:1.0 -The next example is for the 'whenry' user repository and uses Fedora and +The next example is for the "whenry" user repository and uses Fedora and JBoss and gives it a version 2.1 : docker build -t whenry/fedora-jboss:V2.1 From e471a87f1975a101cf7464c0c2cc48db3b79ec26 Mon Sep 17 00:00:00 2001 From: William Henry Date: Sat, 31 May 2014 15:44:17 -0600 Subject: [PATCH 3/4] Fixed some typos and other issues from ostezer comments. Docker-DCO-1.1-Signed-off-by: William Henry (github: ipbabble) Changes to be committed: modified: contrib/man/md/docker-build.1.md modified: contrib/man/md/docker-run.1.md modified: contrib/man/md/docker-tag.1.md --- contrib/man/md/docker-build.1.md | 20 +++++++++++--------- contrib/man/md/docker-run.1.md | 4 ++-- contrib/man/md/docker-tag.1.md | 11 ++++++----- 3 files changed, 19 insertions(+), 16 deletions(-) diff --git a/contrib/man/md/docker-build.1.md b/contrib/man/md/docker-build.1.md index da4f5c017e..1f8cb9cc10 100644 --- a/contrib/man/md/docker-build.1.md +++ b/contrib/man/md/docker-build.1.md @@ -70,29 +70,31 @@ specified within the `ADD` instruction into the specified target. ## Building an image and naming that image A good practice is to give a name to the image you are building. There are -not hard rules here but it is best to give the names consideration. +no hard rules here but it is best to give the names consideration. The **-t**/**--tag** flag is used to rename an image. Here are some examples: -Though t is not good practice, image names can be aribtrary: +Though it is not a good practice, image names can be arbtrary: docker build -t myimage . -A better approach is provide a fully qualified and meaningful repository -name, name, and tag (where tag in this context means the qualifier after -the ":"). In this example we build a Jboss image for the Fedora repository -and give it a version 1.0: +A better approach is to provide a fully qualified and meaningful repository, +name, and tag (where the tag in this context means the qualifier after +the ":"). In this example we build a JBoss image for the Fedora repository +and give it the version 1.0: docker build -t fedora/jboss:1.0 The next example is for the "whenry" user repository and uses Fedora and -JBoss and gives it a version 2.1 : +JBoss and gives it the version 2.1 : docker build -t whenry/fedora-jboss:V2.1 -Or: +If you do not provide a version tag then Docker will assign `latest`: - docker build -t whenry/fedora-jboss:latest + docker build -t whenry/fedora-jboss + +When you list the images, the image above will have the tag `latest`. So renaming an image is arbitrary but consideration should be given to a useful convention that makes sense for consumers and should also take diff --git a/contrib/man/md/docker-run.1.md b/contrib/man/md/docker-run.1.md index 72b01419bf..a1e380ff58 100644 --- a/contrib/man/md/docker-run.1.md +++ b/contrib/man/md/docker-run.1.md @@ -64,8 +64,8 @@ the other shell to view a list of the running containers. You can reattach to a detached container with **docker attach**. If you choose to run a container in the detached mode, then you cannot use the **-rm** option. - When attached in tty mode, you can detach from a running container by pressing -the keys ctrl+p ctrl+q. + When attached in the tty mode, you can detach from a running container without +stopping the process by pressing the keys CTRL-P CTRL-Q. **--dns**=*IP-address* diff --git a/contrib/man/md/docker-tag.1.md b/contrib/man/md/docker-tag.1.md index 687b6ddb47..eca821ebff 100644 --- a/contrib/man/md/docker-tag.1.md +++ b/contrib/man/md/docker-tag.1.md @@ -9,7 +9,7 @@ docker-tag - Tag an image in the repository IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG] # DESCRIPTION -This will rename an image in the repository. "Tag" is this context means the +This will rename an image in the repository. This refers to the entire image name including the optional TAG after the ':'. # "OPTIONS" @@ -27,15 +27,16 @@ separated by a ':' The image name. **TAG** - The tag you are assigning to the image. This is often a version or other -'tag' to distinguish from other similarly named images. + The tag you are assigning to the image. Though this is arbitrary it is +recommended to be used for a version to disinguish images with the same name. +Note that here TAG is a part of the overall name or "tag". # EXAMPLES ## Tagging an image -Here is an example of renaming an image with the repository 'fedora', name -'httpd', and tag version1.0 : +Here is an example of renaming an image (e.g. 0e5574283393) as "httpd" and +tagging it into the "fedora" repository with "version1.0": docker tag 0e5574283393 fedora/httpd:version1.0 From 2858180a9a05dad999df0f4d9adc9750b0fb1c66 Mon Sep 17 00:00:00 2001 From: William Henry Date: Sun, 1 Jun 2014 17:16:14 -0600 Subject: [PATCH 4/4] Changed the term rename to alias etc. Docker-DCO-1.1-Signed-off-by: William Henry (github: ipbabble) Changes to be committed: modified: contrib/man/md/docker-tag.1.md --- contrib/man/md/docker-tag.1.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/contrib/man/md/docker-tag.1.md b/contrib/man/md/docker-tag.1.md index eca821ebff..0c42769908 100644 --- a/contrib/man/md/docker-tag.1.md +++ b/contrib/man/md/docker-tag.1.md @@ -9,12 +9,12 @@ docker-tag - Tag an image in the repository IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG] # DESCRIPTION -This will rename an image in the repository. This refers to the +This will give a new alias to an image in the repository. This refers to the entire image name including the optional TAG after the ':'. # "OPTIONS" **-f**, **--force**=*true*|*false* - When set to true, force the tag name. The default is *false*. + When set to true, force the alias. The default is *false*. **REGISTRYHOST** The hostname of the registry if required. This may also include the port @@ -33,9 +33,9 @@ Note that here TAG is a part of the overall name or "tag". # EXAMPLES -## Tagging an image +## Giving an image a new alias -Here is an example of renaming an image (e.g. 0e5574283393) as "httpd" and +Here is an example of aliasing an image (e.g. 0e5574283393) as "httpd" and tagging it into the "fedora" repository with "version1.0": docker tag 0e5574283393 fedora/httpd:version1.0