From cf8b8c1969daa423a1308561f3c1b2b863c64655 Mon Sep 17 00:00:00 2001 From: Mikhail Sobolev Date: Tue, 2 Apr 2013 04:52:44 +0300 Subject: [PATCH 1/3] move each command description into a separate document --- docs/sources/commandline/cli.rst | 338 ++----------------- docs/sources/commandline/command/attach.rst | 9 + docs/sources/commandline/command/commit.rst | 11 + docs/sources/commandline/command/diff.rst | 9 + docs/sources/commandline/command/export.rst | 9 + docs/sources/commandline/command/history.rst | 9 + docs/sources/commandline/command/images.rst | 12 + docs/sources/commandline/command/import.rst | 9 + docs/sources/commandline/command/info.rst | 9 + docs/sources/commandline/command/inspect.rst | 9 + docs/sources/commandline/command/kill.rst | 9 + docs/sources/commandline/command/login.rst | 9 + docs/sources/commandline/command/logs.rst | 9 + docs/sources/commandline/command/port.rst | 9 + docs/sources/commandline/command/ps.rst | 13 + docs/sources/commandline/command/pull.rst | 9 + docs/sources/commandline/command/push.rst | 9 + docs/sources/commandline/command/restart.rst | 9 + docs/sources/commandline/command/rm.rst | 9 + docs/sources/commandline/command/rmi.rst | 9 + docs/sources/commandline/command/run.rst | 19 ++ docs/sources/commandline/command/start.rst | 9 + docs/sources/commandline/command/stop.rst | 9 + docs/sources/commandline/command/tag.rst | 11 + docs/sources/commandline/command/version.rst | 3 + docs/sources/commandline/command/wait.rst | 9 + 26 files changed, 275 insertions(+), 303 deletions(-) create mode 100644 docs/sources/commandline/command/attach.rst create mode 100644 docs/sources/commandline/command/commit.rst create mode 100644 docs/sources/commandline/command/diff.rst create mode 100644 docs/sources/commandline/command/export.rst create mode 100644 docs/sources/commandline/command/history.rst create mode 100644 docs/sources/commandline/command/images.rst create mode 100644 docs/sources/commandline/command/import.rst create mode 100644 docs/sources/commandline/command/info.rst create mode 100644 docs/sources/commandline/command/inspect.rst create mode 100644 docs/sources/commandline/command/kill.rst create mode 100644 docs/sources/commandline/command/login.rst create mode 100644 docs/sources/commandline/command/logs.rst create mode 100644 docs/sources/commandline/command/port.rst create mode 100644 docs/sources/commandline/command/ps.rst create mode 100644 docs/sources/commandline/command/pull.rst create mode 100644 docs/sources/commandline/command/push.rst create mode 100644 docs/sources/commandline/command/restart.rst create mode 100644 docs/sources/commandline/command/rm.rst create mode 100644 docs/sources/commandline/command/rmi.rst create mode 100644 docs/sources/commandline/command/run.rst create mode 100644 docs/sources/commandline/command/start.rst create mode 100644 docs/sources/commandline/command/stop.rst create mode 100644 docs/sources/commandline/command/tag.rst create mode 100644 docs/sources/commandline/command/version.rst create mode 100644 docs/sources/commandline/command/wait.rst diff --git a/docs/sources/commandline/cli.rst b/docs/sources/commandline/cli.rst index 8e752e4473..2657b91777 100644 --- a/docs/sources/commandline/cli.rst +++ b/docs/sources/commandline/cli.rst @@ -10,312 +10,44 @@ Command Line Interface Docker Usage ~~~~~~~~~~~~ -:: +To list available commands, either run ``docker`` with no parameters or execute +``docker help``:: $ docker Usage: docker COMMAND [arg...] A self-sufficient runtime for linux containers. - Commands: - attach Attach to a running container - commit Create a new image from a container's changes - diff Inspect changes on a container's filesystem - export Stream the contents of a container as a tar archive - history Show the history of an image - images List images - import Create a new filesystem image from the contents of a tarball - info Display system-wide information - inspect Return low-level information on a container - kill Kill a running container - login Register or Login to the docker registry server - logs Fetch the logs of a container - port Lookup the public-facing port which is NAT-ed to PRIVATE_PORT - ps List containers - pull Pull an image or a repository to the docker registry server - push Push an image or a repository to the docker registry server - restart Restart a running container - rm Remove a container - rmi Remove an image - run Run a command in a new container - start Start a stopped container - stop Stop a running container - tag Tag an image into a repository - version Show the docker version information - wait Block until a container stops, then print its exit code - - -attach -~~~~~~ - -:: - - Usage: docker attach [OPTIONS] - - Attach to a running container - - -e=true: Attach to stderr - -i=false: Attach to stdin - -o=true: Attach to stdout - - -commit -~~~~~~ - -:: - - Usage: docker commit [OPTIONS] CONTAINER [DEST] - - Create a new image from a container's changes - - -m="": Commit message - - -diff -~~~~ - -:: - - Usage: docker diff CONTAINER [OPTIONS] - - Inspect changes on a container's filesystem - - -export -~~~~~~ - -:: - - Usage: docker export CONTAINER - - Export the contents of a filesystem as a tar archive - - -history -~~~~~~~ - -:: - - Usage: docker history [OPTIONS] IMAGE - - Show the history of an image - - -images -~~~~~~ - -:: - - Usage: docker images [OPTIONS] [NAME] - - List images - - -a=false: show all images - -q=false: only show numeric IDs - - -import -~~~~~~ - -:: - - Usage: docker import [OPTIONS] URL|- [REPOSITORY [TAG]] - - Create a new filesystem image from the contents of a tarball - - -info -~~~~ - -:: - - Usage: docker info - - Display system-wide information. - - -inspect -~~~~~~~ - -:: - - Usage: docker inspect [OPTIONS] CONTAINER - - Return low-level information on a container - - -kill -~~~~ - -:: - - Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...] - - Kill a running container - - -login -~~~~~ - -:: - - Usage: docker login - - Register or Login to the docker registry server - - -logs -~~~~ - -:: - - Usage: docker logs [OPTIONS] CONTAINER - - Fetch the logs of a container - - -port -~~~~ - -:: - - Usage: docker port [OPTIONS] CONTAINER PRIVATE_PORT - - Lookup the public-facing port which is NAT-ed to PRIVATE_PORT - - -ps -~~ - -:: - - Usage: docker ps [OPTIONS] - - List containers - - -a=false: Show all containers. Only running containers are shown by default. - -notrunc=false: Don't truncate output - -q=false: Only display numeric IDs - - -pull -~~~~ - -:: - - Usage: docker pull NAME - - Pull an image or a repository from the registry - -push -~~~~ - -:: - - Usage: docker push NAME - - Push an image or a repository to the registry - - -restart -~~~~~~~ - -:: - - Usage: docker restart [OPTIONS] NAME - - Restart a running container - - -rm -~~ - -:: - - Usage: docker rm [OPTIONS] CONTAINER - - Remove a container - - -rmi -~~~ - -:: - - Usage: docker rmi [OPTIONS] IMAGE - - Remove an image - - -a=false: Use IMAGE as a path and remove ALL images in this path - -r=false: Use IMAGE as a regular expression instead of an exact name - - -run -~~~ - -:: - - Usage: docker run [OPTIONS] IMAGE COMMAND [ARG...] - - Run a command in a new container - - -c="": Comment - -i=false: Keep stdin open even if not attached - -m=0: Memory limit (in bytes) - -p=[]: Map a network port to the container - -t=false: Allocate a pseudo-tty - -h="": Container host name - -u="": Username or UID - - -start -~~~~~ - -:: - - Usage: docker start [OPTIONS] NAME - - Start a stopped container - - -stop -~~~~ - -:: - - Usage: docker stop [OPTIONS] NAME - - Stop a running container - - -tag -~~~ - -:: - - Usage: docker tag [OPTIONS] IMAGE REPOSITORY [TAG] - - Tag an image into a repository - - -f=false: Force - - -version -~~~~~~~ - -:: - - Usage: docker version - - Show the docker version information - - -wait -~~~~ - -:: - - Usage: docker wait [OPTIONS] NAME - - Block until a container stops, then print its exit code. - + ... + +Available Commands +~~~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + command/attach + command/commit + command/diff + command/export + command/history + command/images + command/import + command/info + command/inspect + command/kill + command/login + command/logs + command/port + command/ps + command/pull + command/push + command/restart + command/rm + command/rmi + command/run + command/start + command/stop + command/tag + command/version + command/wait diff --git a/docs/sources/commandline/command/attach.rst b/docs/sources/commandline/command/attach.rst new file mode 100644 index 0000000000..ac9a84c0cf --- /dev/null +++ b/docs/sources/commandline/command/attach.rst @@ -0,0 +1,9 @@ +=========================================== +``attach`` -- Attach to a running container +=========================================== + +:: + + Usage: docker attach CONTAINER + + Attach to a running container diff --git a/docs/sources/commandline/command/commit.rst b/docs/sources/commandline/command/commit.rst new file mode 100644 index 0000000000..2af05ff093 --- /dev/null +++ b/docs/sources/commandline/command/commit.rst @@ -0,0 +1,11 @@ +=========================================================== +``commit`` -- Create a new image from a container's changes +=========================================================== + +:: + + Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY [TAG]] + + Create a new image from a container's changes + + -m="": Commit message diff --git a/docs/sources/commandline/command/diff.rst b/docs/sources/commandline/command/diff.rst new file mode 100644 index 0000000000..301da6c499 --- /dev/null +++ b/docs/sources/commandline/command/diff.rst @@ -0,0 +1,9 @@ +======================================================= +``diff`` -- Inspect changes on a container's filesystem +======================================================= + +:: + + Usage: docker diff CONTAINER [OPTIONS] + + Inspect changes on a container's filesystem diff --git a/docs/sources/commandline/command/export.rst b/docs/sources/commandline/command/export.rst new file mode 100644 index 0000000000..88ecd2fd53 --- /dev/null +++ b/docs/sources/commandline/command/export.rst @@ -0,0 +1,9 @@ +================================================================= +``export`` -- Stream the contents of a container as a tar archive +================================================================= + +:: + + Usage: docker export CONTAINER + + Export the contents of a filesystem as a tar archive diff --git a/docs/sources/commandline/command/history.rst b/docs/sources/commandline/command/history.rst new file mode 100644 index 0000000000..92fad3b487 --- /dev/null +++ b/docs/sources/commandline/command/history.rst @@ -0,0 +1,9 @@ +=========================================== +``history`` -- Show the history of an image +=========================================== + +:: + + Usage: docker history [OPTIONS] IMAGE + + Show the history of an image diff --git a/docs/sources/commandline/command/images.rst b/docs/sources/commandline/command/images.rst new file mode 100644 index 0000000000..c21762db05 --- /dev/null +++ b/docs/sources/commandline/command/images.rst @@ -0,0 +1,12 @@ +========================= +``images`` -- List images +========================= + +:: + + Usage: docker images [OPTIONS] [NAME] + + List images + + -a=false: show all images + -q=false: only show numeric IDs diff --git a/docs/sources/commandline/command/import.rst b/docs/sources/commandline/command/import.rst new file mode 100644 index 0000000000..5fe90764b9 --- /dev/null +++ b/docs/sources/commandline/command/import.rst @@ -0,0 +1,9 @@ +========================================================================== +``import`` -- Create a new filesystem image from the contents of a tarball +========================================================================== + +:: + + Usage: docker import [OPTIONS] URL|- [REPOSITORY [TAG]] + + Create a new filesystem image from the contents of a tarball diff --git a/docs/sources/commandline/command/info.rst b/docs/sources/commandline/command/info.rst new file mode 100644 index 0000000000..10697dba18 --- /dev/null +++ b/docs/sources/commandline/command/info.rst @@ -0,0 +1,9 @@ +=========================================== +``info`` -- Display system-wide information +=========================================== + +:: + + Usage: docker info + + Display system-wide information. diff --git a/docs/sources/commandline/command/inspect.rst b/docs/sources/commandline/command/inspect.rst new file mode 100644 index 0000000000..34365d1f26 --- /dev/null +++ b/docs/sources/commandline/command/inspect.rst @@ -0,0 +1,9 @@ +========================================================== +``inspect`` -- Return low-level information on a container +========================================================== + +:: + + Usage: docker inspect [OPTIONS] CONTAINER + + Return low-level information on a container diff --git a/docs/sources/commandline/command/kill.rst b/docs/sources/commandline/command/kill.rst new file mode 100644 index 0000000000..cbd019e1a9 --- /dev/null +++ b/docs/sources/commandline/command/kill.rst @@ -0,0 +1,9 @@ +==================================== +``kill`` -- Kill a running container +==================================== + +:: + + Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...] + + Kill a running container diff --git a/docs/sources/commandline/command/login.rst b/docs/sources/commandline/command/login.rst new file mode 100644 index 0000000000..b064b40145 --- /dev/null +++ b/docs/sources/commandline/command/login.rst @@ -0,0 +1,9 @@ +============================================================ +``login`` -- Register or Login to the docker registry server +============================================================ + +:: + + Usage: docker login + + Register or Login to the docker registry server diff --git a/docs/sources/commandline/command/logs.rst b/docs/sources/commandline/command/logs.rst new file mode 100644 index 0000000000..87f3f95b65 --- /dev/null +++ b/docs/sources/commandline/command/logs.rst @@ -0,0 +1,9 @@ +========================================= +``logs`` -- Fetch the logs of a container +========================================= + +:: + + Usage: docker logs [OPTIONS] CONTAINER + + Fetch the logs of a container diff --git a/docs/sources/commandline/command/port.rst b/docs/sources/commandline/command/port.rst new file mode 100644 index 0000000000..4fb6d7f812 --- /dev/null +++ b/docs/sources/commandline/command/port.rst @@ -0,0 +1,9 @@ +========================================================================= +``port`` -- Lookup the public-facing port which is NAT-ed to PRIVATE_PORT +========================================================================= + +:: + + Usage: docker port [OPTIONS] CONTAINER PRIVATE_PORT + + Lookup the public-facing port which is NAT-ed to PRIVATE_PORT diff --git a/docs/sources/commandline/command/ps.rst b/docs/sources/commandline/command/ps.rst new file mode 100644 index 0000000000..f73177918b --- /dev/null +++ b/docs/sources/commandline/command/ps.rst @@ -0,0 +1,13 @@ +========================= +``ps`` -- List containers +========================= + +:: + + Usage: docker ps [OPTIONS] + + List containers + + -a=false: Show all containers. Only running containers are shown by default. + -notrunc=false: Don't truncate output + -q=false: Only display numeric IDs diff --git a/docs/sources/commandline/command/pull.rst b/docs/sources/commandline/command/pull.rst new file mode 100644 index 0000000000..1c417ddcde --- /dev/null +++ b/docs/sources/commandline/command/pull.rst @@ -0,0 +1,9 @@ +========================================================================= +``pull`` -- Pull an image or a repository from the docker registry server +========================================================================= + +:: + + Usage: docker pull NAME + + Pull an image or a repository from the registry diff --git a/docs/sources/commandline/command/push.rst b/docs/sources/commandline/command/push.rst new file mode 100644 index 0000000000..a42296c715 --- /dev/null +++ b/docs/sources/commandline/command/push.rst @@ -0,0 +1,9 @@ +======================================================================= +``push`` -- Push an image or a repository to the docker registry server +======================================================================= + +:: + + Usage: docker push NAME + + Push an image or a repository to the registry diff --git a/docs/sources/commandline/command/restart.rst b/docs/sources/commandline/command/restart.rst new file mode 100644 index 0000000000..24bba5a5a9 --- /dev/null +++ b/docs/sources/commandline/command/restart.rst @@ -0,0 +1,9 @@ +========================================== +``restart`` -- Restart a running container +========================================== + +:: + + Usage: docker restart [OPTIONS] NAME + + Restart a running container diff --git a/docs/sources/commandline/command/rm.rst b/docs/sources/commandline/command/rm.rst new file mode 100644 index 0000000000..f6d6893bfb --- /dev/null +++ b/docs/sources/commandline/command/rm.rst @@ -0,0 +1,9 @@ +============================ +``rm`` -- Remove a container +============================ + +:: + + Usage: docker rm [OPTIONS] CONTAINER + + Remove a container diff --git a/docs/sources/commandline/command/rmi.rst b/docs/sources/commandline/command/rmi.rst new file mode 100644 index 0000000000..3761196f23 --- /dev/null +++ b/docs/sources/commandline/command/rmi.rst @@ -0,0 +1,9 @@ +========================== +``rmi`` -- Remove an image +========================== + +:: + + Usage: docker rmimage [OPTIONS] IMAGE + + Remove an image diff --git a/docs/sources/commandline/command/run.rst b/docs/sources/commandline/command/run.rst new file mode 100644 index 0000000000..c2096b3bd9 --- /dev/null +++ b/docs/sources/commandline/command/run.rst @@ -0,0 +1,19 @@ +=========================================== +``run`` -- Run a command in a new container +=========================================== + +:: + + Usage: docker run [OPTIONS] IMAGE COMMAND [ARG...] + + Run a command in a new container + + -a=map[]: Attach to stdin, stdout or stderr. + -d=false: Detached mode: leave the container running in the background + -e=[]: Set environment variables + -h="": Container host name + -i=false: Keep stdin open even if not attached + -m=0: Memory limit (in bytes) + -p=[]: Map a network port to the container + -t=false: Allocate a pseudo-tty + -u="": Username or UID diff --git a/docs/sources/commandline/command/start.rst b/docs/sources/commandline/command/start.rst new file mode 100644 index 0000000000..df415ca3d3 --- /dev/null +++ b/docs/sources/commandline/command/start.rst @@ -0,0 +1,9 @@ +====================================== +``start`` -- Start a stopped container +====================================== + +:: + + Usage: docker start [OPTIONS] NAME + + Start a stopped container diff --git a/docs/sources/commandline/command/stop.rst b/docs/sources/commandline/command/stop.rst new file mode 100644 index 0000000000..df6d66ccf9 --- /dev/null +++ b/docs/sources/commandline/command/stop.rst @@ -0,0 +1,9 @@ +==================================== +``stop`` -- Stop a running container +==================================== + +:: + + Usage: docker stop [OPTIONS] NAME + + Stop a running container diff --git a/docs/sources/commandline/command/tag.rst b/docs/sources/commandline/command/tag.rst new file mode 100644 index 0000000000..59647355e9 --- /dev/null +++ b/docs/sources/commandline/command/tag.rst @@ -0,0 +1,11 @@ +========================================= +``tag`` -- Tag an image into a repository +========================================= + +:: + + Usage: docker tag [OPTIONS] IMAGE REPOSITORY [TAG] + + Tag an image into a repository + + -f=false: Force diff --git a/docs/sources/commandline/command/version.rst b/docs/sources/commandline/command/version.rst new file mode 100644 index 0000000000..eedf02f2d0 --- /dev/null +++ b/docs/sources/commandline/command/version.rst @@ -0,0 +1,3 @@ +================================================== +``version`` -- Show the docker version information +================================================== diff --git a/docs/sources/commandline/command/wait.rst b/docs/sources/commandline/command/wait.rst new file mode 100644 index 0000000000..2959bf880b --- /dev/null +++ b/docs/sources/commandline/command/wait.rst @@ -0,0 +1,9 @@ +=================================================================== +``wait`` -- Block until a container stops, then print its exit code +=================================================================== + +:: + + Usage: docker wait [OPTIONS] NAME + + Block until a container stops, then print its exit code. From b74d1c92479bc6df61e7283f7639b02837bfb5f3 Mon Sep 17 00:00:00 2001 From: Mikhail Sobolev Date: Wed, 3 Apr 2013 16:37:56 +0300 Subject: [PATCH 2/3] change option description to reflect the semantics At least, for me, 'map' means that there are two values and one is "mapped" to another. In this case, just one value is provided (container's port), the other value is automatically obtained (host's port) and the actual mapping can be seen using ``docker port`` command. --- container.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/container.go b/container.go index adb1602162..8960320e1f 100644 --- a/container.go +++ b/container.go @@ -80,7 +80,7 @@ func ParseRun(args []string, stdout io.Writer) (*Config, error) { flMemory := cmd.Int64("m", 0, "Memory limit (in bytes)") var flPorts ports - cmd.Var(&flPorts, "p", "Map a network port to the container") + cmd.Var(&flPorts, "p", "Expose a container's port to the host (use 'docker port' to see the actual mapping)") var flEnv ListOpts cmd.Var(&flEnv, "e", "Set environment variables") From 92186d7cf71acbf4027e390b33590570cf4ff290 Mon Sep 17 00:00:00 2001 From: "Kevin J. Lynagh" Date: Wed, 3 Apr 2013 22:21:57 -0700 Subject: [PATCH 3/3] Fix broken link in doc site. Broken link was from python_web_app to nonexistent "base commands page"; updated to point to next item in examples menu, running_ssh_service screencast. --- AUTHORS | 1 + docs/sources/examples/index.rst | 2 +- docs/sources/examples/python_web_app.rst | 4 +--- .../{runningsshservice.rst => running_ssh_service.rst} | 5 +++++ 4 files changed, 8 insertions(+), 4 deletions(-) rename docs/sources/examples/{runningsshservice.rst => running_ssh_service.rst} (73%) diff --git a/AUTHORS b/AUTHORS index 382a11b5b0..fefd748422 100644 --- a/AUTHORS +++ b/AUTHORS @@ -21,6 +21,7 @@ Jonathan Rudenberg Julien Barbier Jérôme Petazzoni Ken Cochrane +Kevin J. Lynagh Louis Opter Mikhail Sobolev Nelson Chen diff --git a/docs/sources/examples/index.rst b/docs/sources/examples/index.rst index 4d37cdfe57..0ab2143a30 100644 --- a/docs/sources/examples/index.rst +++ b/docs/sources/examples/index.rst @@ -15,4 +15,4 @@ Contents: hello_world hello_world_daemon python_web_app - runningsshservice + running_ssh_service diff --git a/docs/sources/examples/python_web_app.rst b/docs/sources/examples/python_web_app.rst index 978c6de1c4..5f7a07ea1e 100644 --- a/docs/sources/examples/python_web_app.rst +++ b/docs/sources/examples/python_web_app.rst @@ -65,6 +65,4 @@ See the example in action -Continue to the `base commands`_ - -.. _base commands: ../commandline/basecommands.html +Continue to :ref:`running_ssh_service`. diff --git a/docs/sources/examples/runningsshservice.rst b/docs/sources/examples/running_ssh_service.rst similarity index 73% rename from docs/sources/examples/runningsshservice.rst rename to docs/sources/examples/running_ssh_service.rst index 0053efd4da..23d2d41c2f 100644 --- a/docs/sources/examples/runningsshservice.rst +++ b/docs/sources/examples/running_ssh_service.rst @@ -1,3 +1,8 @@ +:title: Running an SSH service +:description: A screencast of installing and running an sshd service +:keywords: docker, example, package installation, networking + +.. _running_ssh_service: Create an ssh daemon service ============================