From 2cb184ade59ccb578d50f5ff535d1d02e7855563 Mon Sep 17 00:00:00 2001 From: William Henry Date: Tue, 27 May 2014 11:56:11 -0600 Subject: [PATCH] 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