mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
Numerous small fixes to the CLI documentation
This commit is contained in:
James Turnbull
parent
237868e9c3
commit
a1dba16fe8
1 changed files with 81 additions and 76 deletions
|
|
@ -43,14 +43,14 @@ To list available commands, either run ``docker`` with no parameters or execute
|
|||
-s="": Force the docker runtime to use a specific storage driver
|
||||
-v=false: Print version information and quit
|
||||
|
||||
The docker daemon is the persistent process that manages containers. Docker uses the same binary for both the
|
||||
The Docker daemon is the persistent process that manages containers. Docker uses the same binary for both the
|
||||
daemon and client. To run the daemon you provide the ``-d`` flag.
|
||||
|
||||
To force docker to use devicemapper as the storage driver, use ``docker -d -s devicemapper``
|
||||
To force Docker to use devicemapper as the storage driver, use ``docker -d -s devicemapper``.
|
||||
|
||||
To set the dns server for all docker containers, use ``docker -d -dns 8.8.8.8``
|
||||
To set the DNS server for all Docker containers, use ``docker -d -dns 8.8.8.8``.
|
||||
|
||||
To run the daemon with debug output, use ``docker -d -D``
|
||||
To run the daemon with debug output, use ``docker -d -D``.
|
||||
|
||||
.. _cli_attach:
|
||||
|
||||
|
|
@ -69,11 +69,11 @@ To run the daemon with debug output, use ``docker -d -D``
|
|||
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
|
||||
process the exit code will be retuned to the client.
|
||||
process the exit code will be returned to the client.
|
||||
|
||||
To stop a container, use ``docker stop``
|
||||
To stop a container, use ``docker stop``.
|
||||
|
||||
To kill the container, use ``docker kill``
|
||||
To kill the container, use ``docker kill``.
|
||||
|
||||
.. _cli_attach_examples:
|
||||
|
||||
|
|
@ -129,12 +129,11 @@ Examples:
|
|||
-no-cache: Do not use the cache when building the image.
|
||||
-rm: Remove intermediate containers after a successful build
|
||||
|
||||
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 <dockerfile_add>` instruction. When a
|
||||
single ``Dockerfile`` is given as URL, then no context is set. When a
|
||||
git repository is set as URL, then the repository is used as the
|
||||
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 <dockerfile_add>` instruction. When a single ``Dockerfile``
|
||||
is given as ``URL``, then no context is set. When a Git repository is set as
|
||||
``URL``, then the repository is used as the context
|
||||
|
||||
.. _cli_build_examples:
|
||||
|
||||
|
|
@ -169,13 +168,13 @@ Examples:
|
|||
---> f52f38b7823e
|
||||
Successfully built f52f38b7823e
|
||||
|
||||
This example specifies that the PATH is ``.``, and so all the files in
|
||||
the local directory get tar'd and sent to the Docker daemon. The PATH
|
||||
This example specifies that the ``PATH`` is ``.``, and so all the files in
|
||||
the local directory get tar'd and sent to the Docker daemon. The ``PATH``
|
||||
specifies where to find the files for the "context" of the build on
|
||||
the Docker daemon. Remember that the daemon could be running on a
|
||||
remote machine and that no parsing of the Dockerfile happens at the
|
||||
remote machine and that no parsing of the ``Dockerfile`` happens at the
|
||||
client side (where you're running ``docker build``). That means that
|
||||
*all* the files at PATH get sent, not just the ones listed to
|
||||
*all* the files at ``PATH`` get sent, not just the ones listed to
|
||||
:ref:`ADD <dockerfile_add>` in the ``Dockerfile``.
|
||||
|
||||
The transfer of context from the local machine to the Docker daemon is
|
||||
|
|
@ -198,16 +197,16 @@ tag will be ``2.0``
|
|||
|
||||
This will read a ``Dockerfile`` from *stdin* without context. Due to
|
||||
the lack of a context, no contents of any local directory will be sent
|
||||
to the ``docker`` daemon. Since there is no context, a Dockerfile
|
||||
to the ``docker`` daemon. Since there is no context, a ``Dockerfile``
|
||||
``ADD`` only works if it refers to a remote URL.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo docker build github.com/creack/docker-firefox
|
||||
|
||||
This will clone the Github repository and use the cloned repository as
|
||||
This will clone the GitHub repository and use the cloned repository as
|
||||
context. The ``Dockerfile`` at the root of the repository is used as
|
||||
``Dockerfile``. Note that you can specify an arbitrary git repository
|
||||
``Dockerfile``. Note that you can specify an arbitrary Git repository
|
||||
by using the ``git://`` schema.
|
||||
|
||||
|
||||
|
|
@ -248,7 +247,7 @@ Change the command that a container runs
|
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Sometimes you have an application container running just a service and you need
|
||||
to make a quick change (run bash?) and then change it back.
|
||||
to make a quick change and then change it back.
|
||||
|
||||
In this example, we run a container with ``ls`` and then change the image to
|
||||
run ``ls /etc``.
|
||||
|
|
@ -271,9 +270,9 @@ Full -run example
|
|||
The ``-run`` JSON hash changes the ``Config`` section when running ``docker inspect CONTAINERID``
|
||||
or ``config`` when running ``docker inspect IMAGEID``.
|
||||
|
||||
(multiline is ok within a single quote ``'``)
|
||||
(Multiline is okay within a single quote ``'``)
|
||||
|
||||
::
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo docker commit -run='
|
||||
{
|
||||
|
|
@ -339,7 +338,7 @@ There are 3 events that are listed in the 'diff':
|
|||
2. ```D``` - Delete
|
||||
3. ```C``` - Change
|
||||
|
||||
for example:
|
||||
For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -431,7 +430,7 @@ Show events in the past from a specified time
|
|||
|
||||
Export the contents of a filesystem as a tar archive to STDOUT
|
||||
|
||||
for example:
|
||||
For example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -451,7 +450,7 @@ for example:
|
|||
-notrunc=false: Don't truncate output
|
||||
-q=false: only show numeric IDs
|
||||
|
||||
To see how the docker:latest image was built:
|
||||
To see how the ``docker:latest`` image was built:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -589,10 +588,9 @@ Displaying image hierarchy
|
|||
(.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
|
||||
file archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) containing a
|
||||
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
|
||||
standard in.
|
||||
archive, you can use the ``-`` parameter to take the data from *stdin*.
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
|
|
@ -602,24 +600,30 @@ Import from a remote location
|
|||
|
||||
This will create a new untagged image.
|
||||
|
||||
``$ sudo docker import http://example.com/exampleimage.tgz``
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo docker import http://example.com/exampleimage.tgz
|
||||
|
||||
Import from a local file
|
||||
........................
|
||||
|
||||
Import to docker via pipe and standard in
|
||||
Import to docker via pipe and *stdin*.
|
||||
|
||||
``$ cat exampleimage.tgz | sudo docker import - exampleimagelocal:new``
|
||||
.. code-block:: bash
|
||||
|
||||
$ cat exampleimage.tgz | sudo docker import - exampleimagelocal:new
|
||||
|
||||
Import from a local directory
|
||||
.............................
|
||||
|
||||
``$ sudo tar -c . | docker import - exampleimagedir``
|
||||
.. code-block:: bash
|
||||
|
||||
Note the ``sudo`` in this example -- you must preserve the ownership
|
||||
of the files (especially root ownership) during the archiving with
|
||||
tar. If you are not root (or sudo) when you tar, then the ownerships
|
||||
might not get preserved.
|
||||
$ sudo tar -c . | docker import - exampleimagedir
|
||||
|
||||
Note the ``sudo`` in this example -- you must preserve the ownership of the
|
||||
files (especially root ownership) during the archiving with tar. If you are not
|
||||
root (or the sudo command) when you tar, then the ownerships might not get
|
||||
preserved.
|
||||
|
||||
.. _cli_info:
|
||||
|
||||
|
|
@ -658,16 +662,16 @@ might not get preserved.
|
|||
|
||||
Insert a file from URL in the IMAGE at PATH
|
||||
|
||||
Use the specified IMAGE as the parent for a new image which adds a
|
||||
:ref:`layer <layer_def>` containing the new file. ``insert`` does not modify
|
||||
the original image, and the new image has the contents of the parent image,
|
||||
plus the new file.
|
||||
Use the specified ``IMAGE`` as the parent for a new image which adds a
|
||||
:ref:`layer <layer_def>` containing the new file. The ``insert`` command does
|
||||
not modify the original image, and the new image has the contents of the parent
|
||||
image, plus the new file.
|
||||
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
|
||||
Insert file from github
|
||||
Insert file from GitHub
|
||||
.......................
|
||||
|
||||
.. code-block:: bash
|
||||
|
|
@ -691,7 +695,7 @@ Insert file from github
|
|||
By default, this will render all results in a JSON array. If a format
|
||||
is specified, the given template will be executed for each result.
|
||||
|
||||
Go's `text/template <http://golang.org/pkg/text/template/>` package
|
||||
Go's `text/template <http://golang.org/pkg/text/template/>`_ package
|
||||
describes all the details of the format.
|
||||
|
||||
Examples
|
||||
|
|
@ -796,14 +800,14 @@ Known Issues (kill)
|
|||
|
||||
Fetch the logs of a container
|
||||
|
||||
``docker logs`` 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 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``).
|
||||
|
||||
``docker logs -f`` combines ``docker logs`` and ``docker attach``: it
|
||||
will first return all logs from the beginning and then continue
|
||||
streaming new output from the container's stdout and stderr.
|
||||
The ``docker logs -f`` command combines ``docker logs`` and ``docker attach``:
|
||||
it will first return all logs from the beginning and then continue streaming
|
||||
new output from the container's stdout and stderr.
|
||||
|
||||
|
||||
.. _cli_port:
|
||||
|
|
@ -1006,12 +1010,13 @@ image is removed.
|
|||
-name="": Assign the specified name to the container. If no name is specific docker will generate a random name
|
||||
-P=false: Publish all exposed ports to the host interfaces
|
||||
|
||||
``'docker run'`` 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``.
|
||||
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``.
|
||||
|
||||
``docker run`` can be used in combination with ``docker commit`` to :ref:`change the command that a container runs <cli_commit_examples>`.
|
||||
The ``docker run`` command can be used in combination with ``docker commit`` to
|
||||
:ref:`change the command that a container runs <cli_commit_examples>`.
|
||||
|
||||
Known Issues (run -volumes-from)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -1027,10 +1032,10 @@ Examples:
|
|||
|
||||
$ sudo docker run -cidfile /tmp/docker_test.cid ubuntu echo "test"
|
||||
|
||||
This will create a container and print "test" to the console. The
|
||||
``cidfile`` flag makes docker attempt to create a new file and write the
|
||||
container ID to it. If the file exists already, docker will return an
|
||||
error. Docker will close this file when docker run exits.
|
||||
This will create a container and print ``test`` to the console. The
|
||||
``cidfile`` flag makes Docker attempt to create a new file and write the
|
||||
container ID to it. If the file exists already, Docker will return an
|
||||
error. Docker will close this file when ``docker run`` exits.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -1064,7 +1069,7 @@ use-cases, like running Docker within Docker.
|
|||
$ sudo docker run -w /path/to/dir/ -i -t ubuntu pwd
|
||||
|
||||
The ``-w`` lets the command being executed inside directory given,
|
||||
here /path/to/dir/. If the path does not exists it is created inside the
|
||||
here ``/path/to/dir/``. If the path does not exists it is created inside the
|
||||
container.
|
||||
|
||||
.. code-block:: bash
|
||||
|
|
@ -1081,7 +1086,7 @@ using the container, but inside the current working directory.
|
|||
|
||||
$ sudo docker run -p 127.0.0.1:80:8080 ubuntu bash
|
||||
|
||||
This binds port ``8080`` of the container to port ``80`` on 127.0.0.1 of the
|
||||
This binds port ``8080`` of the container to port ``80`` on ``127.0.0.1`` of the
|
||||
host machine. :ref:`port_redirection` explains in detail how to manipulate ports
|
||||
in Docker.
|
||||
|
||||
|
|
@ -1115,11 +1120,11 @@ to the newly created container.
|
|||
$ sudo docker run -volumes-from 777f7dc92da7,ba8c0c54f0f2:ro -i -t ubuntu pwd
|
||||
|
||||
The ``-volumes-from`` flag mounts all the defined volumes from the
|
||||
refrence containers. Containers can be specified by a comma seperated
|
||||
referenced containers. Containers can be specified by a comma seperated
|
||||
list or by repetitions of the ``-volumes-from`` argument. The container
|
||||
id may be optionally suffixed with ``:ro`` or ``:rw`` to mount the volumes in
|
||||
ID may be optionally suffixed with ``:ro`` or ``:rw`` to mount the volumes in
|
||||
read-only or read-write mode, respectively. By default, the volumes are mounted
|
||||
in the same mode (rw or ro) as the reference container.
|
||||
in the same mode (read write or read only) as the reference container.
|
||||
|
||||
A complete example
|
||||
..................
|
||||
|
|
@ -1134,10 +1139,10 @@ A complete example
|
|||
|
||||
This example shows 5 containers that might be set up to test a web application change:
|
||||
|
||||
1. Start a pre-prepared volume image ``static-web-files`` (in the background) that has css, image and static html in it, (with a VOLUME statement in the Dockerfile to allow the web server to use those files);
|
||||
2. Start a pre-prepared ``riakserver`` image, give the container name ``riak`` and expose 8098 to any containers that link to it;
|
||||
1. Start a pre-prepared volume image ``static-web-files`` (in the background) that has CSS, image and static HTML in it, (with a ``VOLUME`` instruction in the ``Dockerfile`` to allow the web server to use those files);
|
||||
2. Start a pre-prepared ``riakserver`` image, give the container name ``riak`` and expose port ``8098`` to any containers that link to it;
|
||||
3. Start the ``appserver`` image, restricting its memory usage to 100MB, setting two environment variables ``DEVELOPMENT`` and ``BRANCH`` and bind-mounting the current directory (``$(pwd)``) in the container in read-only mode as ``/app/bin``;
|
||||
4. Start the ``webserver``, mapping port 443 (https) in the container to port 1443 on the docker server, setting the dns server to ``dns.dev.org``, creating a volume to put the log files into (so we can access it from another container), then importing the files from the volume exposed by the ``static`` container, and linking to all exposed ports from ``riak`` and ``app``. Lastly, we set the hostname to ``web.sven.dev.org`` so its consistent with the pre-generated ssl certificate;
|
||||
4. Start the ``webserver``, mapping port ``443`` in the container to port ``1443`` on the Docker server, setting the DNS server to ``dns.dev.org``, creating a volume to put the log files into (so we can access it from another container), then importing the files from the volume exposed by the ``static`` container, and linking to all exposed ports from ``riak`` and ``app``. Lastly, we set the hostname to ``web.sven.dev.org`` so its consistent with the pre-generated SSL certificate;
|
||||
5. Finally, we create a container that runs ``tail -f access.log`` using the logs volume from the ``web`` container, setting the workdir to ``/var/log/httpd``. The ``-rm`` option means that when the container exits, the container's layer is removed.
|
||||
|
||||
|
||||
|
|
@ -1226,7 +1231,7 @@ The main process inside the container will receive SIGTERM, and after a grace pe
|
|||
``version``
|
||||
-----------
|
||||
|
||||
Show the version of the docker client, daemon, and latest released version.
|
||||
Show the version of the Docker client, daemon, and latest released version.
|
||||
|
||||
|
||||
.. _cli_wait:
|
||||
|
|
|
|||
Loading…
Reference in a new issue