From 74a03f6def9eb3af4df7401002731604ce55dd1f Mon Sep 17 00:00:00 2001 From: James Turnbull Date: Thu, 22 May 2014 07:05:19 +1000 Subject: [PATCH] Adding User Guide * Added User Guide section outlines. * Added User Guide to menu. * Moved HTTPS example to articles. * Replaced Hello World example with User Guide. * Moved use cases out of examples. * Updated Introduction to add User Guide. * Redirected migrated /use and /articles links. * Added Docker.io section * Added Dockerized section * Added Using Docker section * Added Docker Images section * Added Docker Links section * Added Docker Volumes section Docker-DCO-1.1-Signed-off-by: James Turnbull (github: jamtur01) --- docs/sources/reference/builder.md | 12 ++++----- docs/sources/reference/commandline/cli.md | 33 ++++++++--------------- docs/sources/reference/run.md | 24 +++++++---------- 3 files changed, 26 insertions(+), 43 deletions(-) diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index 235d92e1b7..10973665b1 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -57,7 +57,7 @@ accelerating `docker build` significantly (indicated by `Using cache`): When you're done with your build, you're ready to look into [*Pushing a repository to its registry*]( -/use/workingwithrepository/#image-push). +/userguide/dockerrepos/#image-push). ## Format @@ -95,7 +95,7 @@ The `FROM` instruction sets the [*Base Image*](/terms/image/#base-image-def) for subsequent instructions. As such, a valid Dockerfile must have `FROM` as its first instruction. The image can be any valid image – it is especially easy to start by **pulling an image** from the [*Public Repositories*]( -/use/workingwithrepository/#using-public-repositories). +/userguide/dockerrepos/#using-public-repositories). `FROM` must be the first non-comment instruction in the Dockerfile. @@ -200,10 +200,8 @@ default specified in CMD. The `EXPOSE` instructions informs Docker that the container will listen on the specified network ports at runtime. Docker uses this information to interconnect -containers using links (see -[*links*](/use/working_with_links_names/#working-with-links-names)), -and to setup port redirection on the host system (see [*Redirect Ports*]( -/use/port_redirection/#port-redirection)). +containers using links (see the [Docker User +Guide](/userguide/dockerlinks)). ## ENV @@ -380,7 +378,7 @@ and mark it as holding externally mounted volumes from native host or other containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain string, `VOLUME /var/log`. For more information/examples and mounting instructions via the Docker client, refer to [*Share Directories via Volumes*]( -/use/working_with_volumes/#volume-def) documentation. +/userguide/dockervolumes/#volume-def) documentation. ## USER diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index 8325bc794f..f2e370ace5 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -602,15 +602,6 @@ contains complex json object, so to grab it as JSON, you use The main process inside the container will be sent SIGKILL, or any signal specified with option `--signal`. -### Known Issues (kill) - -- [Issue 197](https://github.com/dotcloud/docker/issues/197) indicates - that `docker kill` may leave directories behind - and make it difficult to remove the container. -- [Issue 3844](https://github.com/dotcloud/docker/issues/3844) lxc - 1.0.0 beta3 removed `lcx-kill` which is used by - Docker versions before 0.8.0; see the issue for a workaround. - ## load Usage: docker load @@ -864,11 +855,9 @@ of all containers. The `docker run` command can be used in combination with `docker commit` to [*change the command that a container runs*](#commit-an-existing-container). -See [*Redirect Ports*](/use/port_redirection/#port-redirection) -for more detailed information about the `--expose`, `-p`, `-P` and `--link` -parameters, and [*Link Containers*]( -/use/working_with_links_names/#working-with-links-names) for specific -examples using `--link`. +See the [Docker User Guide](/userguide/dockerlinks/) for more detailed +information about the `--expose`, `-p`, `-P` and `--link` parameters, +and linking containers. ### Known Issues (run –volumes-from) @@ -934,16 +923,16 @@ manipulate the host's docker daemon. $ 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 host -machine. [*Redirect Ports*](/use/port_redirection/#port-redirection) +This binds port `8080` of the container to port `80` on `127.0.0.1` of +the host machine. The [Docker User Guide](/userguide/dockerlinks/) explains in detail how to manipulate ports in Docker. $ sudo docker run --expose 80 ubuntu bash -This exposes port `80` of the container for use within a link without publishing -the port to the host system's interfaces. [*Redirect Ports*]( -/use/port_redirection/#port-redirection) explains in detail how to -manipulate ports in Docker. +This exposes port `80` of the container for use within a link without +publishing the port to the host system's interfaces. The [Docker User +Guide](/userguide/dockerlinks) explains in detail how to manipulate +ports in Docker. $ sudo docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash @@ -1097,7 +1086,7 @@ Search [Docker.io](https://index.docker.io) for images -t, --trusted=false Only show trusted builds See [*Find Public Images on Docker.io*]( -/use/workingwithrepository/#find-public-images-on-dockerio) for +/userguide/dockerrepos/#find-public-images-on-dockerio) for more details on finding shared images from the commandline. ## start @@ -1130,7 +1119,7 @@ grace period, SIGKILL You can group your images together using names and tags, and then upload them to [*Share Images via Repositories*]( -/use/workingwithrepository/#working-with-the-repository). +/userguide/dockerrepos/#working-with-the-repository). ## top diff --git a/docs/sources/reference/run.md b/docs/sources/reference/run.md index aa3d941b13..7d5fcbc51f 100644 --- a/docs/sources/reference/run.md +++ b/docs/sources/reference/run.md @@ -11,21 +11,17 @@ The [*Image*](/terms/image/#image-def) which starts the process may define defaults related to the binary to run, the networking to expose, and more, but `docker run` gives final control to the operator who starts the container from the image. That's the main -reason [*run*](/commandline/cli/#cli-run) has more options than any +reason [*run*](/reference/commandline/cli/#cli-run) has more options than any other `docker` command. -Every one of the [*Examples*](/examples/#example-list) shows -running containers, and so here we try to give more in-depth guidance. - ## General Form -As you`ve seen in the [*Examples*](/examples/#example-list), the -basic run command takes this form: +The basic `docker run` command takes this form: $ docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...] To learn how to interpret the types of `[OPTIONS]`, -see [*Option types*](/commandline/cli/#cli-options). +see [*Option types*](/reference/commandline/cli/#cli-options). The list of `[OPTIONS]` breaks down into two groups: @@ -75,9 +71,9 @@ default foreground mode: In detached mode (`-d=true` or just `-d`), all I/O should be done through network connections or shared volumes because the container is -no longer listening to the commandline where you executed `docker run`. +no longer listening to the command line where you executed `docker run`. You can reattach to a detached container with `docker` -[*attach*](commandline/cli/#attach). If you choose to run a +[*attach*](/reference/commandline/cli/#attach). If you choose to run a container in the detached mode, then you cannot use the `--rm` option. ### Foreground @@ -85,7 +81,7 @@ container in the detached mode, then you cannot use the `--rm` option. In foreground mode (the default when `-d` is not specified), `docker run` can start the process in the container and attach the console to the process's standard input, output, and standard error. It can even pretend to be a TTY -(this is what most commandline executables expect) and pass along signals. All +(this is what most command line executables expect) and pass along signals. All of that is configurable: -a=[] : Attach to ``stdin``, ``stdout`` and/or ``stderr`` @@ -121,11 +117,11 @@ assign a name to the container with `--name` then the daemon will also generate a random string name too. The name can become a handy way to add meaning to a container since you can use this name when defining -[*links*](/use/working_with_links_names/#working-with-links-names) +[*links*](/userguide/dockerlinks/#working-with-links-names) (or any other place you need to identify a container). This works for both background and foreground Docker containers. -### PID Equivalent +### PID Equivalent And finally, to help with automation, you can have Docker write the container ID out to a file of your choosing. This is similar to how some @@ -256,7 +252,7 @@ familiar with using LXC directly. ## Overriding Dockerfile Image Defaults -When a developer builds an image from a [*Dockerfile*](builder/#dockerbuilder) +When a developer builds an image from a [*Dockerfile*](/reference/builder/#dockerbuilder) or when she commits it, the developer can set a number of default parameters that take effect when the image starts up as a container. @@ -425,7 +421,7 @@ mechanism to communicate with a linked container by its alias: --volumes-from="": Mount all volumes from the given container(s) The volumes commands are complex enough to have their own documentation in -section [*Share Directories via Volumes*](/use/working_with_volumes/#volume-def). +section [*Share Directories via Volumes*](/userguide/dockervolumes/#volume-def). A developer can define one or more `VOLUME's associated with an image, but only the operator can give access from one container to another (or from a container to a volume mounted on the host).