From 0f4461a8b27b2b951bf9039a6b07324ac810ffd0 Mon Sep 17 00:00:00 2001 From: Sven Dowideit Date: Mon, 7 Apr 2014 17:00:01 +1000 Subject: [PATCH] add some more text to the cli docs Docker-DCO-1.1-Signed-off-by: Sven Dowideit (github: SvenDowideit) --- docs/sources/reference/commandline/cli.rst | 60 +++++++++++++++++----- 1 file changed, 48 insertions(+), 12 deletions(-) diff --git a/docs/sources/reference/commandline/cli.rst b/docs/sources/reference/commandline/cli.rst index c0df5f8175..37118c53f5 100644 --- a/docs/sources/reference/commandline/cli.rst +++ b/docs/sources/reference/commandline/cli.rst @@ -148,9 +148,14 @@ TMPDIR and the data directory can be set like this: --no-stdin=false: Do not attach stdin --sig-proxy=true: Proxify all received signal to the process (even in non-tty mode) +The ``attach`` command will allow you to view or interact with any +running container, detached (``-d``) or interactive (``-i``). You can +attach to the same container at the same time - screen sharing style, +or quickly view the progress of your daemonized process. + 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. When you detach from the container's +``CTRL-C`` (for a quiet exit) or ``CTRL-\`` to get a stacktrace of +the Docker client when it quits. When you detach from the container's process the exit code will be returned to the client. To stop a container, use ``docker stop``. @@ -211,6 +216,8 @@ Examples: --no-cache: Do not use the cache when building the image. --rm=true: Remove intermediate containers after a successful build +Use this command to build Docker images from a ``Dockerfile`` and a "context". + The files at ``PATH`` or ``URL`` are called the "context" of the build. The build process may refer to any of the files in the context, for example when using an :ref:`ADD ` instruction. @@ -317,6 +324,12 @@ by using the ``git://`` schema. -m, --message="": Commit message -a, --author="": Author (eg. "John Hannibal Smith " +It can be useful to commit a container's file changes or settings into a new image. +This allows you debug a container by running an interactive shell, or to export +a working dataset to another server. +Generally, it is better to use Dockerfiles to manage your images in a documented +and maintainable way. + .. _cli_commit_examples: Commit an existing container @@ -562,7 +575,7 @@ Listing the full length image IDs Create an empty filesystem image and import the contents of the tarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) into it, then optionally tag it. -At this time, the URL must start with ``http`` and point to a single +URLs must start with ``http`` and point to a single file archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) containing a root filesystem. If you would like to import from a local directory or archive, you can use the ``-`` parameter to take the data from *stdin*. @@ -625,6 +638,8 @@ preserved. Kernel Version: 3.8.0-33-generic WARNING: No swap limit support +When sending issue reports, please use ``docker version`` and ``docker info`` to +ensure we know how your setup is configured. .. _cli_inspect: @@ -788,10 +803,7 @@ Restores both images and tags. -f, --follow=false: Follow log output -The ``docker logs`` command is a convenience which batch-retrieves whatever -logs are present at the time of execution. This does not guarantee execution -order when combined with a ``docker run`` (i.e. your run may not have generated -any logs at the time you execute ``docker logs``). +The ``docker logs`` command batch-retrieves all logs present at the time of execution. The ``docker logs --follow`` command combines ``docker logs`` and ``docker attach``: it will first return all logs from the beginning and then continue streaming @@ -839,9 +851,6 @@ Running ``docker ps`` showing 2 linked containers. CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds webapp d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db - fd2645e2e2b5 busybox:latest top 10 days ago Ghost insane_ptolemy - -The last container is marked as a ``Ghost`` container. It is a container that was running when the docker daemon was restarted (upgraded, or ``-H`` settings changed). The container is still running, but as this docker daemon process is not able to manage it, you can't attach to it. To bring them out of ``Ghost`` Status, you need to use ``docker kill`` or ``docker restart``. ``docker ps`` will show only running containers by default. To see all containers: ``docker ps -a`` @@ -856,6 +865,23 @@ The last container is marked as a ``Ghost`` container. It is a container that wa Pull an image or a repository from the registry +Most of your images will be created on top of a base image from the +(https://index.docker.io). + +The Docker Index contains many pre-built images that you can ``pull`` and try +without needing to define and configure your own. + +To download a particular image, or set of images (i.e., a repository), +use ``docker pull``: + +.. code-block:: bash + + $ docker pull debian + # will pull all the images in the debian repository + $ docker pull debian:testing + # will pull only the image named debian:testing and any intermediate layers + # it is based on. (typically the empty `scratch` image, a MAINTAINERs layer, + # and the un-tared base. .. _cli_push: @@ -868,6 +894,7 @@ The last container is marked as a ``Ghost`` container. It is a container that wa Push an image or a repository to the registry +Use ``docker push`` to share your images on public or private registries. .. _cli_restart: @@ -926,7 +953,7 @@ network communication. .. code-block:: bash - $ sudo docker rm `docker ps -a -q` + $ sudo docker rm $(docker ps -a -q) This command will delete all stopped containers. The command ``docker ps -a -q`` will return all @@ -1022,7 +1049,8 @@ The ``docker run`` command first ``creates`` a writeable container layer over the specified image, and then ``starts`` it using the specified command. That is, ``docker run`` is equivalent to the API ``/containers/create`` then ``/containers/(id)/start``. -Once the container is stopped it still exists and can be started back up. See ``docker ps -a`` to view a list of all containers. +A stopped container can be restarted with all its previous changes intact using +``docker start``. See ``docker ps -a`` to view a list of all containers. The ``docker run`` command can be used in combination with ``docker commit`` to :ref:`change the command that a container runs `. @@ -1270,6 +1298,8 @@ This example shows 5 containers that might be set up to test a web application c Produces a tarred repository to the standard output stream. Contains all parent layers, and all tags + versions, or specified repo:tag. +It is used to create a backup that can then be used with ``docker load`` + .. code-block:: bash $ sudo docker save busybox > busybox.tar @@ -1297,6 +1327,9 @@ Contains all parent layers, and all tags + versions, or specified repo:tag. -s, --stars=0: Only displays with at least xxx stars -t, --trusted=false: Only show trusted builds +See :ref:`searching_central_index` for more details on finding shared images +from the commandline. + .. _cli_start: ``start`` @@ -1339,6 +1372,9 @@ The main process inside the container will receive SIGTERM, and after a grace pe -f, --force=false: Force +You can group your images together using names and +tags, and then upload them to :ref:`working_with_the_repository`. + .. _cli_top: ``top``