From 148a2be8788afe0c1fbccef4d5060cf9bff534ca Mon Sep 17 00:00:00 2001 From: "O.S.Tezer" Date: Wed, 23 Apr 2014 23:48:28 +0300 Subject: [PATCH] Docs auto-conversion fixes and MD marking and structure improvements. - Remove redundant chars and all errors caused by RST->MD conversion. e.g. [/#, /\, \<, />, etc.] - Fix broken inter-document links - Fix outbound links no-longer active or changed - Fix lists - Fix code blocks - Correct apostrophes - Replace redundant inline note marks for code with code marks - Fix broken image links - Remove non-functional title links - Correct broken cross-docs links - Improve readability Note: This PR does not try to fix/amend: - Grammatical errors - Lexical errors - Linguistic-logic errors etc. It just aims to fix main structural or conversion errors to serve as a base for further amendments that will cover others including but not limited to those mentioned above. Docker-DCO-1.1-Signed-off-by: O.S. Tezer (github: ostezer) Update: - Fix backtick issues Docker-DCO-1.1-Signed-off-by: Sven Dowideit (github: SvenDowideit) --- docs/sources/reference/builder.md | 390 ++++++------- docs/sources/reference/commandline/cli.md | 675 ++++++++++------------ docs/sources/reference/run.md | 301 +++++----- 3 files changed, 635 insertions(+), 731 deletions(-) diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md index 5c332e5c2f..c976c118d7 100644 --- a/docs/sources/reference/builder.md +++ b/docs/sources/reference/builder.md @@ -4,23 +4,21 @@ page_keywords: builder, docker, Dockerfile, automation, image creation # Dockerfile Reference -**Docker can act as a builder** and read instructions from a text -`Dockerfile` to automate the steps you would -otherwise take manually to create an image. Executing -`docker build` will run your steps and commit them -along the way, giving you a final image. +**Docker can act as a builder** and read instructions from a text *Dockerfile* +to automate the steps you would otherwise take manually to create an image. +Executing `docker build` will run your steps and commit them along the way, +giving you a final image. ## Usage -To [*build*](../commandline/cli/#cli-build) an image from a source -repository, create a description file called `Dockerfile` -at the root of your repository. This file will describe the -steps to assemble the image. +To [*build*](../commandline/cli/#cli-build) an image from a source repository, +create a description file called Dockerfile at the root of your repository. +This file will describe the steps to assemble the image. -Then call `docker build` with the path of your -source repository as argument (for example, `.`): +Then call `docker build` with the path of you source repository as argument +(for example, `.`): -> `sudo docker build .` + sudo docker build . The path to the source repository defines where to find the *context* of the build. The build is run by the Docker daemon, not by the CLI, so the @@ -30,7 +28,7 @@ whole context must be transferred to the daemon. The Docker CLI reports You can specify a repository and tag at which to save the new image if the build succeeds: -> `sudo docker build -t shykes/myapp .` + sudo docker build -t shykes/myapp . The Docker daemon will run your steps one-by-one, committing the result to a new image if necessary, before finally outputting the ID of your @@ -38,12 +36,11 @@ new image. The Docker daemon will automatically clean up the context you sent. Note that each instruction is run independently, and causes a new image -to be created - so `RUN cd /tmp` will not have any -effect on the next instructions. +to be created - so `RUN cd /tmp` will not have any effect on the next +instructions. Whenever possible, Docker will re-use the intermediate images, -accelerating `docker build` significantly (indicated -by `Using cache`): +accelerating `docker build` significantly (indicated by `Using cache`): $ docker build -t SvenDowideit/ambassador . Uploading context 10.24 kB @@ -58,9 +55,9 @@ by `Using cache`): ---> 1a5ffc17324d Successfully built 1a5ffc17324d -When you’re done with your build, you’re ready to look into [*Pushing a -repository to its -registry*](../../use/workingwithrepository/#image-push). +When you're done with your build, you're ready to look into +[*Pushing a repository to its registry*]( +../../use/workingwithrepository/#image-push). ## Format @@ -83,84 +80,73 @@ be treated as an argument. This allows statements like: # Comment RUN echo 'we are running some # of cool things' -Here is the set of instructions you can use in a `Dockerfile` +Here is the set of instructions you can use in a Dockerfile for building images. -## `FROM` +## FROM -> `FROM ` + FROM Or -> `FROM :` + FROM : -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). +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). -`FROM` must be the first non-comment instruction in -the `Dockerfile`. +`FROM` must be the first non-comment instruction in the Dockerfile. -`FROM` can appear multiple times within a single -Dockerfile in order to create multiple images. Simply make a note of the -last image id output by the commit before each new `FROM` -command. +`FROM` can appear multiple times within a single Dockerfile in order to create +multiple images. Simply make a note of the last image id output by the commit +before each new `FROM` command. -If no `tag` is given to the `FROM` -instruction, `latest` is assumed. If the +If no `tag` is given to the `FROM` instruction, `latest` is assumed. If the used tag does not exist, an error will be returned. -## `MAINTAINER` +## MAINTAINER -> `MAINTAINER ` + MAINTAINER -The `MAINTAINER` instruction allows you to set the -*Author* field of the generated images. +The `MAINTAINER` instruction allows you to set the *Author* field of the +generated images. -## `RUN` +## RUN RUN has 2 forms: -- `RUN ` (the command is run in a shell - - `/bin/sh -c`) -- `RUN ["executable", "param1", "param2"]` (*exec* - form) +- `RUN ` (the command is run in a shell - `/bin/sh -c`) +- `RUN ["executable", "param1", "param2"]` (*exec* form) -The `RUN` instruction will execute any commands in a -new layer on top of the current image and commit the results. The -resulting committed image will be used for the next step in the -Dockerfile. +The `RUN` instruction will execute any commands in a new layer on top of the +current image and commit the results. The resulting committed image will be +used for the next step in the Dockerfile. -Layering `RUN` instructions and generating commits -conforms to the core concepts of Docker where commits are cheap and -containers can be created from any point in an image’s history, much -like source control. +Layering `RUN` instructions and generating commits conforms to the core +concepts of Docker where commits are cheap and containers can be created from +any point in an image's history, much like source control. -The *exec* form makes it possible to avoid shell string munging, and to -`RUN` commands using a base image that does not -contain `/bin/sh`. +The *exec* form makes it possible to avoid shell string munging, and to `RUN` +commands using a base image that does not contain `/bin/sh`. ### Known Issues (RUN) -- [Issue 783](https://github.com/dotcloud/docker/issues/783) is about - file permissions problems that can occur when using the AUFS file - system. You might notice it during an attempt to `rm` - a file, for example. The issue describes a workaround. -- [Issue 2424](https://github.com/dotcloud/docker/issues/2424) Locale - will not be set automatically. +- [Issue 783](https://github.com/dotcloud/docker/issues/783) is about file + permissions problems that can occur when using the AUFS file system. You + might notice it during an attempt to `rm` a file, for example. The issue + describes a workaround. +- [Issue 2424](https://github.com/dotcloud/docker/issues/2424) Locale will + not be set automatically. -## `CMD` +## CMD CMD has three forms: -- `CMD ["executable","param1","param2"]` (like an - *exec*, preferred form) -- `CMD ["param1","param2"]` (as *default - parameters to ENTRYPOINT*) -- `CMD command param1 param2` (as a *shell*) +- `CMD ["executable","param1","param2"]` (like an *exec*, preferred form) +- `CMD ["param1","param2"]` (as *default parameters to ENTRYPOINT*) +- `CMD command param1 param2` (as a *shell*) There can only be one CMD in a Dockerfile. If you list more than one CMD then only the last CMD will take effect. @@ -169,83 +155,75 @@ then only the last CMD will take effect. container.** These defaults can include an executable, or they can omit the executable, in which case you must specify an ENTRYPOINT as well. -When used in the shell or exec formats, the `CMD` -instruction sets the command to be executed when running the image. +When used in the shell or exec formats, the `CMD` instruction sets the command +to be executed when running the image. -If you use the *shell* form of the CMD, then the `` -will execute in `/bin/sh -c`: +If you use the *shell* form of the CMD, then the `` will execute in +`/bin/sh -c`: FROM ubuntu CMD echo "This is a test." | wc - -If you want to **run your** `` **without a -shell** then you must express the command as a JSON array and give the -full path to the executable. **This array form is the preferred format -of CMD.** Any additional parameters must be individually expressed as -strings in the array: +If you want to **run your** `` **without a shell** then you must +express the command as a JSON array and give the full path to the executable. +**This array form is the preferred format of CMD.** Any additional parameters +must be individually expressed as strings in the array: FROM ubuntu CMD ["/usr/bin/wc","--help"] -If you would like your container to run the same executable every time, -then you should consider using `ENTRYPOINT` in -combination with `CMD`. See +If you would like your container to run the same executable every time, then +you should consider using `ENTRYPOINT` in combination with `CMD`. See [*ENTRYPOINT*](#entrypoint). -If the user specifies arguments to `docker run` then -they will override the default specified in CMD. +If the user specifies arguments to `docker run` then they will override the +default specified in CMD. > **Note**: -> Don’t confuse `RUN` with `CMD`. `RUN` actually runs a command and commits +> don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits > the result; `CMD` does not execute anything at build time, but specifies > the intended command for the image. -## `EXPOSE` +## EXPOSE -> `EXPOSE [...]` + EXPOSE [...] -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 +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)). +and to setup port redirection on the host system (see [*Redirect Ports*]( +../../use/port_redirection/#port-redirection)). -## `ENV` +## ENV -> `ENV ` + ENV -The `ENV` instruction sets the environment variable -`` to the value ``. -This value will be passed to all future `RUN` -instructions. This is functionally equivalent to prefixing the command -with `=` +The `ENV` instruction sets the environment variable `` to the value +``. This value will be passed to all future `RUN` instructions. This is +functionally equivalent to prefixing the command with `=` -The environment variables set using `ENV` will -persist when a container is run from the resulting image. You can view -the values using `docker inspect`, and change them -using `docker run --env =`. +The environment variables set using `ENV` will persist when a container is run +from the resulting image. You can view the values using `docker inspect`, and +change them using `docker run --env =`. > **Note**: > One example where this can cause unexpected consequenses, is setting -> `ENV DEBIAN_FRONTEND noninteractive`. Which will -> persist when the container is run interactively; for example: -> `docker run -t -i image bash` +> `ENV DEBIAN_FRONTEND noninteractive`. Which will persist when the container +> is run interactively; for example: `docker run -t -i image bash` -## `ADD` +## ADD -> `ADD ` + ADD -The `ADD` instruction will copy new files from -\ and add them to the container’s filesystem at path -``. +The `ADD` instruction will copy new files from `` and add them to the +container's filesystem at path ``. -`` must be the path to a file or directory -relative to the source directory being built (also called the *context* -of the build) or a remote file URL. +`` must be the path to a file or directory relative to the source directory +being built (also called the *context* of the build) or a remote file URL. -`` is the absolute path to which the source -will be copied inside the destination container. +`` is the absolute path to which the source will be copied inside the +destination container. All new files and directories are created with mode 0755, uid and gid 0. @@ -262,79 +240,64 @@ All new files and directories are created with mode 0755, uid and gid 0. The copy obeys the following rules: -- The `` path must be inside the *context* of - the build; you cannot `ADD ../something /something` -, because the first step of a `docker build` - is to send the context directory (and subdirectories) to - the docker daemon. +- The `` path must be inside the *context* of the build; + you cannot `ADD ../something /something`, because the first step of a + `docker build` is to send the context directory (and subdirectories) to the + docker daemon. -- If `` is a URL and `` - does not end with a trailing slash, then a file is - downloaded from the URL and copied to ``. +- If `` is a URL and `` does not end with a trailing slash, then a + file is downloaded from the URL and copied to ``. -- If `` is a URL and `` - does end with a trailing slash, then the filename is - inferred from the URL and the file is downloaded to - `/`. For instance, - `ADD http://example.com/foobar /` would create - the file `/foobar`. The URL must have a - nontrivial path so that an appropriate filename can be discovered in - this case (`http://example.com` will not work). +- If `` is a URL and `` does end with a trailing slash, then the + filename is inferred from the URL and the file is downloaded to + `/`. For instance, `ADD http://example.com/foobar /` would + create the file `/foobar`. The URL must have a nontrivial path so that an + appropriate filename can be discovered in this case (`http://example.com` + will not work). -- If `` is a directory, the entire directory - is copied, including filesystem metadata. +- If `` is a directory, the entire directory is copied, including + filesystem metadata. -- If `` is a *local* tar archive in a - recognized compression format (identity, gzip, bzip2 or xz) then it - is unpacked as a directory. Resources from *remote* URLs are **not** - decompressed. +- If `` is a *local* tar archive in a recognized compression format + (identity, gzip, bzip2 or xz) then it is unpacked as a directory. Resources + from *remote* URLs are **not** decompressed. When a directory is copied or + unpacked, it has the same behavior as `tar -x`: the result is the union of: - When a directory is copied or unpacked, it has the same behavior as - `tar -x`: the result is the union of + 1. whatever existed at the destination path and + 2. the contents of the source tree, with conflicts resolved in favor of + "2." on a file-by-file basis. - 1. whatever existed at the destination path and - 2. the contents of the source tree, +- If `` is any other kind of file, it is copied individually along with + its metadata. In this case, if `` ends with a trailing slash `/`, it + will be considered a directory and the contents of `` will be written + at `/base()`. - with conflicts resolved in favor of "2." on a file-by-file basis. +- If `` does not end with a trailing slash, it will be considered a + regular file and the contents of `` will be written at ``. -- If `` is any other kind of file, it is - copied individually along with its metadata. In this case, if - `` ends with a trailing slash - `/`, it will be considered a directory and the - contents of `` will be written at - `/base()`. +- If `` doesn't exist, it is created along with all missing directories + in its path. -- If `` does not end with a trailing slash, - it will be considered a regular file and the contents of - `` will be written at `` -. - -- If `` doesn’t exist, it is created along - with all missing directories in its path. - -## `ENTRYPOINT` +## ENTRYPOINT ENTRYPOINT has two forms: -- `ENTRYPOINT ["executable", "param1", "param2"]` - (like an *exec*, preferred form) -- `ENTRYPOINT command param1 param2` (as a - *shell*) +- `ENTRYPOINT ["executable", "param1", "param2"]` + (like an *exec*, preferred form) +- `ENTRYPOINT command param1 param2` + (as a *shell*) -There can only be one `ENTRYPOINT` in a Dockerfile. -If you have more than one `ENTRYPOINT`, then only -the last one in the Dockerfile will have an effect. +There can only be one `ENTRYPOINT` in a Dockerfile. If you have more than one +`ENTRYPOINT`, then only the last one in the Dockerfile will have an effect. -An `ENTRYPOINT` helps you to configure a container -that you can run as an executable. That is, when you specify an -`ENTRYPOINT`, then the whole container runs as if it -was just that executable. +An `ENTRYPOINT` helps you to configure a container that you can run as an +executable. That is, when you specify an `ENTRYPOINT`, then the whole container +runs as if it was just that executable. The `ENTRYPOINT` instruction adds an entry command that will **not** be -overwritten when arguments are passed to `docker run`, unlike the -behavior of `CMD`. This allows arguments to be passed to the entrypoint. -i.e. `docker run -d` will pass the "-d" argument to the -ENTRYPOINT. +overwritten when arguments are passed to `docker run`, unlike the behavior +of `CMD`. This allows arguments to be passed to the entrypoint. i.e. +`docker run -d` will pass the "-d" argument to the ENTRYPOINT. You can specify parameters either in the ENTRYPOINT JSON array (as in "like an exec" above), or by using a CMD statement. Parameters in the @@ -342,13 +305,13 @@ ENTRYPOINT will not be overridden by the `docker run` arguments, but parameters specified via CMD will be overridden by `docker run` arguments. -Like a `CMD`, you can specify a plain string for the -ENTRYPOINT and it will execute in `/bin/sh -c`: +Like a `CMD`, you can specify a plain string for the `ENTRYPOINT` and it will +execute in `/bin/sh -c`: FROM ubuntu ENTRYPOINT wc -l - -For example, that Dockerfile’s image will *always* take stdin as input +For example, that Dockerfile's image will *always* take stdin as input ("-") and print the number of lines ("-l"). If you wanted to make this optional but default, you could use a CMD: @@ -356,44 +319,41 @@ optional but default, you could use a CMD: CMD ["-l", "-"] ENTRYPOINT ["/usr/bin/wc"] -## `VOLUME` +## VOLUME -> `VOLUME ["/data"]` + VOLUME ["/data"] -The `VOLUME` instruction will create a mount point -with the specified name and mark it as holding externally mounted -volumes from native host or other containers. For more -information/examples and mounting instructions via docker client, refer -to [*Share Directories via -Volumes*](../../use/working_with_volumes/#volume-def) documentation. +The `VOLUME` instruction will create a mount point with the specified name +and mark it as holding externally mounted volumes from native host or other +containers. For more information/examples and mounting instructions via docker +client, refer to [*Share Directories via Volumes*]( +../../use/working_with_volumes/#volume-def) documentation. -## `USER` +## USER -> `USER daemon` + USER daemon -The `USER` instruction sets the username or UID to -use when running the image. +The `USER` instruction sets the username or UID to use when running the image. -## `WORKDIR` +## WORKDIR -> `WORKDIR /path/to/workdir` + WORKDIR /path/to/workdir -The `WORKDIR` instruction sets the working directory -for the `RUN`, `CMD` and +The `WORKDIR` instruction sets the working directory for the `RUN`, `CMD` and `ENTRYPOINT` Dockerfile commands that follow it. It can be used multiple times in the one Dockerfile. If a relative path -is provided, it will be relative to the path of the previous -`WORKDIR` instruction. For example: +is provided, it will be relative to the path of the previous `WORKDIR` +instruction. For example: -> WORKDIR /a WORKDIR b WORKDIR c RUN pwd + WORKDIR /a WORKDIR b WORKDIR c RUN pwd The output of the final `pwd` command in this Dockerfile would be `/a/b/c`. -## `ONBUILD` +## ONBUILD -> `ONBUILD [INSTRUCTION]` + ONBUILD [INSTRUCTION] The `ONBUILD` instruction adds to the image a "trigger" instruction to be executed at a later time, when the image is @@ -410,7 +370,7 @@ daemon which may be customized with user-specific configuration. For example, if your image is a reusable python application builder, it will require application source code to be added in a particular directory, and it might require a build script to be called *after* -that. You can’t just call *ADD* and *RUN* now, because you don’t yet +that. You can't just call *ADD* and *RUN* now, because you don't yet have access to the application source code, and it will be different for each application build. You could simply provide application developers with a boilerplate Dockerfile to copy-paste into their application, but @@ -420,23 +380,23 @@ mixes with application-specific code. The solution is to use *ONBUILD* to register in advance instructions to run later, during the next build stage. -Here’s how it works: +Here's how it works: -1. When it encounters an *ONBUILD* instruction, the builder adds a - trigger to the metadata of the image being built. The instruction - does not otherwise affect the current build. -2. At the end of the build, a list of all triggers is stored in the - image manifest, under the key *OnBuild*. They can be inspected with - *docker inspect*. -3. Later the image may be used as a base for a new build, using the - *FROM* instruction. As part of processing the *FROM* instruction, - the downstream builder looks for *ONBUILD* triggers, and executes - them in the same order they were registered. If any of the triggers - fail, the *FROM* instruction is aborted which in turn causes the - build to fail. If all triggers succeed, the FROM instruction - completes and the build continues as usual. -4. Triggers are cleared from the final image after being executed. In - other words they are not inherited by "grand-children" builds. +1. When it encounters an *ONBUILD* instruction, the builder adds a + trigger to the metadata of the image being built. The instruction + does not otherwise affect the current build. +2. At the end of the build, a list of all triggers is stored in the + image manifest, under the key *OnBuild*. They can be inspected with + *docker inspect*. +3. Later the image may be used as a base for a new build, using the + *FROM* instruction. As part of processing the *FROM* instruction, + the downstream builder looks for *ONBUILD* triggers, and executes + them in the same order they were registered. If any of the triggers + fail, the *FROM* instruction is aborted which in turn causes the + build to fail. If all triggers succeed, the FROM instruction + completes and the build continues as usual. +4. Triggers are cleared from the final image after being executed. In + other words they are not inherited by "grand-children" builds. For example you might add something like this: @@ -445,7 +405,7 @@ For example you might add something like this: ONBUILD RUN /usr/local/bin/python-build --dir /app/src [...] -> **Warning**: Chaining ONBUILD instructions using ONBUILD ONBUILD isn’t allowed. +> **Warning**: Chaining ONBUILD instructions using ONBUILD ONBUILD isn't allowed. > **Warning**: ONBUILD may not trigger FROM or MAINTAINER instructions. diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md index e0d896755b..d59bd37674 100644 --- a/docs/sources/reference/commandline/cli.md +++ b/docs/sources/reference/commandline/cli.md @@ -4,8 +4,8 @@ page_keywords: Docker, Docker documentation, CLI, command line # Command Line -To list available commands, either run `docker` with -no parameters or execute `docker help`: +To list available commands, either run `docker` with no parameters +or execute `docker help`: $ sudo docker Usage: docker [OPTIONS] COMMAND [arg...] @@ -33,13 +33,11 @@ will set the value to the opposite of the default value. ### Multi -Options like `-a=[]` indicate they can be specified -multiple times: +Options like `-a=[]` indicate they can be specified multiple times: docker run -a stdin -a stdout -a stderr -i -t ubuntu /bin/bash -Sometimes this can use a more complex value string, as for -`-v`: +Sometimes this can use a more complex value string, as for `-v`: docker run -v /host:/container example/mysql @@ -49,9 +47,10 @@ Options like `--name=""` expect a string, and they can only be specified once. Options like `-c=0` expect an integer, and they can only be specified once. -## `daemon` +## daemon Usage of docker: + -D, --debug=false: Enable debug mode -H, --host=[]: Multiple tcp://host:port or unix://path/to/socket to bind in daemon mode, single connection otherwise. systemd socket activation can be used with fd://[socketfd]. -G, --group="docker": Group to assign the unix socket specified by -H when running in daemon mode; use '' (the empty string) to disable setting of a group @@ -95,9 +94,8 @@ To run the daemon with debug output, use `docker -d -D`. To use lxc as the execution driver, use `docker -d -e lxc`. -The docker client will also honor the `DOCKER_HOST` -environment variable to set the `-H` flag for the -client. +The docker client will also honor the `DOCKER_HOST` environment variable to set +the `-H` flag for the client. docker -H tcp://0.0.0.0:4243 ps # or @@ -105,32 +103,32 @@ client. docker ps # both are equal -To run the daemon with [systemd socket -activation](http://0pointer.de/blog/projects/socket-activation.html), -use `docker -d -H fd://`. Using `fd://` -will work perfectly for most setups but you can also specify -individual sockets too `docker -d -H fd://3`. If the -specified socket activated files aren’t found then docker will exit. You +To run the daemon with [systemd socket activation]( +http://0pointer.de/blog/projects/socket-activation.html), use +`docker -d -H fd://`. Using `fd://` will work perfectly for most setups but +you can also specify individual sockets too `docker -d -H fd://3`. If the +specified socket activated files aren't found then docker will exit. You can find examples of using systemd socket activation with docker and -systemd in the [docker source -tree](https://github.com/dotcloud/docker/blob/master/contrib/init/systemd/socket-activation/). +systemd in the [docker source tree]( +https://github.com/dotcloud/docker/blob/master/contrib/init/systemd/socket-activation/). Docker supports softlinks for the Docker data directory -(`/var/lib/docker`) and for `/tmp`. TMPDIR and the data directory can be set like this: +(`/var/lib/docker`) and for `/tmp`. TMPDIR and the data directory can be set +like this: TMPDIR=/mnt/disk2/tmp /usr/local/bin/docker -d -D -g /var/lib/docker -H unix:// > /var/lib/boot2docker/docker.log 2>&1 # or export TMPDIR=/mnt/disk2/tmp /usr/local/bin/docker -d -D -g /var/lib/docker -H unix:// > /var/lib/boot2docker/docker.log 2>&1 -## `attach` +## attach + +Attach to a running container. Usage: docker attach CONTAINER - Attach to a running container. - - --no-stdin=false: Do not attach stdin - --sig-proxy=true: Proxify all received signal to the process (even in non-tty mode) + --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`) @@ -141,7 +139,7 @@ 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 process the exit code will be returned +you detach from the container's process the exit code will be returned to the client. To stop a container, use `docker stop`. @@ -182,34 +180,34 @@ To kill the container, use `docker kill`. ^C$ $ sudo docker stop $ID -## `build` +## build + +Build a new container image from the source code at PATH Usage: docker build [OPTIONS] PATH | URL | - - Build a new container image from the source code at PATH - -t, --tag="": Repository name (and optionally a tag) to be applied - to the resulting image in case of success. - -q, --quiet=false: Suppress the verbose output generated by the containers. - --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` + -t, --tag="": Repository name (and optionally a tag) to be applied + to the resulting image in case of success. + -q, --quiet=false: Suppress the verbose output generated by the containers. + --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 -[*ADD*](../../builder/#dockerfile-add) instruction. When a single -`Dockerfile` is given as `URL`, -then no context is set. +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 +[*ADD*](../../builder/#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 Git repository is cloned with its submodules (git clone –recursive). A fresh git clone occurs in a temporary directory on your local host, and then this is sent to the Docker daemon as the context. This way, your local user credentials and -vpn’s etc can be used to access private repositories +vpn's etc can be used to access private repositories -See also +See also: [*Dockerfile Reference*](../../builder/#dockerbuilder). @@ -243,14 +241,14 @@ See also 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` +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 client side (where you’re running +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 -[*ADD*](../../builder/#dockerfile-add) in the `Dockerfile`. +[*ADD*](../../builder/#dockerfile-add) in the Dockerfile. The transfer of context from the local machine to the Docker daemon is what the `docker` client means when you see the @@ -268,30 +266,30 @@ and the tag will be `2.0` $ sudo docker build - < Dockerfile -This will read a `Dockerfile` from *stdin* without +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` `ADD` +there is no context, a Dockerfile `ADD` only works if it refers to a remote URL. $ sudo docker build github.com/creack/docker-firefox 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 +context. The Dockerfile at the root of the +repository is used as Dockerfile. Note that you can specify an arbitrary Git repository by using the `git://` schema. -## `commit` +## 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, --message="": Commit message + -a, --author="": Author (eg. "John Hannibal Smith " - -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 +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 @@ -309,27 +307,27 @@ maintainable way. REPOSITORY TAG ID CREATED VIRTUAL SIZE SvenDowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB -## `cp` +## cp + +Copy files/folders from the containers filesystem to the host +path. Paths are relative to the root of the filesystem. Usage: docker cp CONTAINER:PATH HOSTPATH - Copy files/folders from the containers filesystem to the host - path. Paths are relative to the root of the filesystem. - $ sudo docker cp 7bb0e258aefe:/etc/debian_version . $ sudo docker cp blue_frog:/etc/hosts . -## `diff` +## diff + +List the changed files and directories in a container᾿s filesystem Usage: docker diff CONTAINER - List the changed files and directories in a container᾿s filesystem +There are 3 events that are listed in the `diff`: -There are 3 events that are listed in the ‘diff’: - -1. `` `A` `` - Add -2. `` `D` `` - Delete -3. `` `C` `` - Change +1. `A` - Add +2. `D` - Delete +3. `C` - Change For example: @@ -347,12 +345,12 @@ For example: A /go/src/github.com/dotcloud/docker/.git .... -## `events` +## events + +Get real time events from the server Usage: docker events - Get real time events from the server - --since="": Show all events created since timestamp (either seconds since epoch, or date string as below) --until="": Show events created before timestamp @@ -360,24 +358,24 @@ For example: ### Examples -You’ll need two shells for this example. +You'll need two shells for this example. -#### Shell 1: Listening for events +**Shell 1: Listening for events:** $ sudo docker events -#### Shell 2: Start and Stop a Container +**Shell 2: Start and Stop a Container:** $ sudo docker start 4386fb97867d $ sudo docker stop 4386fb97867d -#### Shell 1: (Again .. now showing events) +**Shell 1: (Again .. now showing events):** [2013-09-03 15:49:26 +0200 CEST] 4386fb97867d: (from 12de384bfb10) start [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop -#### Show events in the past from a specified time +**Show events in the past from a specified time:** $ sudo docker events --since 1378216169 [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die @@ -392,24 +390,24 @@ You’ll need two shells for this example. [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop -## `export` +## export + +Export the contents of a filesystem as a tar archive to STDOUT Usage: docker export CONTAINER - Export the contents of a filesystem as a tar archive to STDOUT - For example: $ sudo docker export red_panda > latest.tar -## `history` +## history + +Show the history of an image Usage: docker history [OPTIONS] IMAGE - Show the history of an image - - --no-trunc=false: Don᾿t truncate output - -q, --quiet=false: Only show numeric IDs + --no-trunc=false: Don᾿t truncate output + -q, --quiet=false: Only show numeric IDs To see how the `docker:latest` image was built: @@ -422,15 +420,15 @@ To see how the `docker:latest` image was built: 750d58736b4b6cc0f9a9abe8f258cef269e3e9dceced1146503522be9f985ada 6 weeks ago /bin/sh -c #(nop) MAINTAINER Tianon Gravi - mkimage-debootstrap.sh -t jessie.tar.xz jessie http://http.debian.net/debian 0 B 511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158 9 months ago 0 B -## `images` +## images + +List images Usage: docker images [OPTIONS] [NAME] - List images - - -a, --all=false: Show all images (by default filter out the intermediate image layers) - --no-trunc=false: Don᾿t truncate output - -q, --quiet=false: Only show numeric IDs + -a, --all=false: Show all images (by default filter out the intermediate image layers) + --no-trunc=false: Don᾿t truncate output + -q, --quiet=false: Only show numeric IDs The default `docker images` will show all top level images, their repository and tags, and their virtual size. @@ -468,7 +466,7 @@ by default. tryout latest 2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB 5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB -## `import` +## import Usage: docker import URL|- [REPOSITORY[:TAG]] @@ -483,19 +481,19 @@ data from *stdin*. ### Examples -#### Import from a remote location +**Import from a remote location:** This will create a new untagged image. $ sudo docker import http://example.com/exampleimage.tgz -#### Import from a local file +**Import from a local file:** Import to docker via pipe and *stdin*. $ cat exampleimage.tgz | sudo docker import - exampleimagelocal:new -#### Import from a local directory +**Import from a local directory:** $ sudo tar -c . | docker import - exampleimagedir @@ -504,12 +502,12 @@ 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. -## `info` +## info + +Display system-wide information. Usage: docker info - Display system-wide information. - $ sudo docker info Containers: 292 Images: 194 @@ -522,44 +520,43 @@ tar, then the ownerships might not get 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. +When sending issue reports, please use `docker version` and `docker info` to +ensure we know how your setup is configured. -## `inspect` +## inspect + +Return low-level information on a container/image Usage: docker inspect CONTAINER|IMAGE [CONTAINER|IMAGE...] - Return low-level information on a container/image - - -f, --format="": Format the output using the given go template. + -f, --format="": Format the output using the given go template. 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 -#### Get an instance’s IP Address +**Get an instance'sIP Address:** For the most part, you can pick out any field from the JSON in a fairly straightforward manner. $ sudo docker inspect --format='{{.NetworkSettings.IPAddress}}' $INSTANCE_ID -#### List All Port Bindings +**List All Port Bindings:** One can loop over arrays and maps in the results to produce simple text output: $ sudo docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID -#### Find a Specific Port Mapping +**Find a Specific Port Mapping:** -The `.Field` syntax doesn’t work when the field name -begins with a number, but the template language’s `index` +The `.Field` syntax doesn't work when the field name +begins with a number, but the template language's `index` function does. The `.NetworkSettings.Ports` section contains a map of the internal port mappings to a list of external address/port objects, so to grab just the numeric public @@ -570,43 +567,43 @@ the public address. $ sudo docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID -#### Get config +**Get config:** -The `.Field` syntax doesn’t work when the field -contains JSON data, but the template language’s custom `json` +The `.Field` syntax doesn't work when the field +contains JSON data, but the template language's custom `json` function does. The `.config` section contains complex json object, so to grab it as JSON, you use `json` to convert config object into JSON $ sudo docker inspect --format='{{json .config}}' $INSTANCE_ID -## `kill` +## kill + +Kill a running container (send SIGKILL, or specified signal) Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...] - Kill a running container (send SIGKILL, or specified signal) - - -s, --signal="KILL": Signal to send to the container + -s, --signal="KILL": Signal to send to the container 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. +- [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` +## load + +Load an image from a tar archive on STDIN Usage: docker load - Load an image from a tar archive on STDIN - - -i, --input="": Read from a tar archive file, instead of STDIN + -i, --input="": Read from a tar archive file, instead of STDIN Loads a tarred repository from a file or the standard input stream. Restores both images and tags. @@ -626,28 +623,28 @@ Restores both images and tags. fedora heisenbug 58394af37342 7 weeks ago 385.5 MB fedora latest 58394af37342 7 weeks ago 385.5 MB -## `login` +## login + +Register or Login to the docker registry server Usage: docker login [OPTIONS] [SERVER] - Register or Login to the docker registry server - -e, --email="": Email -p, --password="": Password -u, --username="": Username - If you want to login to a private registry you can - specify this by adding the server name. +If you want to login to a private registry you can +specify this by adding the server name. example: docker login localhost:8080 -## `logs` +## logs + +Fetch the logs of a container Usage: docker logs [OPTIONS] CONTAINER - Fetch the logs of a container - -f, --follow=false: Follow log output The `docker logs` command batch-retrieves all logs @@ -655,28 +652,28 @@ 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 new output from the container’s stdout and stderr. +continue streaming new output from the container'sstdout and stderr. -## `port` +## port Usage: docker port [OPTIONS] CONTAINER PRIVATE_PORT - Lookup the public-facing port which is NAT-ed to PRIVATE_PORT +Lookup the public-facing port which is NAT-ed to PRIVATE_PORT -## `ps` +## ps + +List containers Usage: docker ps [OPTIONS] - List containers - - -a, --all=false: Show all containers. Only running containers are shown by default. - --before="": Show only container created before Id or Name, include non-running ones. - -l, --latest=false: Show only the latest created container, include non-running ones. - -n=-1: Show n last created containers, include non-running ones. - --no-trunc=false: Don᾿t truncate output - -q, --quiet=false: Only display numeric IDs - -s, --size=false: Display sizes, not to be used with -q - --since="": Show only containers created since Id or Name, include non-running ones. + -a, --all=false: Show all containers. Only running containers are shown by default. + --before="": Show only container created before Id or Name, include non-running ones. + -l, --latest=false: Show only the latest created container, include non-running ones. + -n=-1: Show n last created containers, include non-running ones. + --no-trunc=false: Don᾿t truncate output + -q, --quiet=false: Only display numeric IDs + -s, --size=false: Display sizes, not to be used with -q + --since="": Show only containers created since Id or Name, include non-running ones. Running `docker ps` showing 2 linked containers. @@ -685,21 +682,20 @@ Running `docker ps` showing 2 linked containers. 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 -`docker ps` will show only running containers by -default. To see all containers: `docker ps -a` +`docker ps` will show only running containers by default. To see all containers: +`docker ps -a` -## `pull` +## pull + +Pull an image or a repository from the registry Usage: docker pull NAME[:TAG] - 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](https://index.docker.io)). +Docker Index ([https://index.docker.io](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. +`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`: @@ -711,31 +707,32 @@ use `docker pull`: # it is based on. (typically the empty `scratch` image, a MAINTAINERs layer, # and the un-tared base. -## `push` +## push + +Push an image or a repository to the registry Usage: docker push NAME[:TAG] - Push an image or a repository to the registry - Use `docker push` to share your images on public or private registries. -## `restart` +## restart + +Restart a running container Usage: docker restart [OPTIONS] NAME - Restart a running container + -t, --time=10: Number of seconds to try to stop for before killing the container. Once killed it will then be restarted. Default=10 - -t, --time=10: Number of seconds to try to stop for before killing the container. Once killed it will then be restarted. Default=10 +## rm -## `rm` +Remove one or more containers Usage: docker rm [OPTIONS] CONTAINER - Remove one or more containers - -l, --link="": Remove the link instead of the actual container - -f, --force=false: Force removal of running container - -v, --volumes=false: Remove the volumes associated to the container + -l, --link="": Remove the link instead of the actual container + -f, --force=false: Force removal of running container + -v, --volumes=false: Remove the volumes associated to the container ### Known Issues (rm) @@ -765,18 +762,18 @@ This command will delete all stopped containers. The command IDs and pass them to the `rm` command which will delete them. Any running containers will not be deleted. -## `rmi` +## rmi + +Remove one or more images Usage: docker rmi IMAGE [IMAGE...] - Remove one or more images - - -f, --force=false: Force - --no-prune=false: Do not delete untagged parents + -f, --force=false: Force + --no-prune=false: Do not delete untagged parents ### Removing tagged images -Images can be removed either by their short or long ID’s, or their image +Images can be removed either by their short or long ID`s, or their image names. If an image has more than one name, each of them needs to be removed before the image is removed. @@ -802,86 +799,79 @@ removed before the image is removed. Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 -## `run` +## run + +Run a command in a new container Usage: docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...] - Run a command in a new container + -a, --attach=map[]: Attach to stdin, stdout or stderr + -c, --cpu-shares=0: CPU shares (relative weight) + --cidfile="": Write the container ID to the file + -d, --detach=false: Detached mode: Run container in the background, print new container id + -e, --env=[]: Set environment variables + --env-file="": Read in a line delimited file of ENV variables + -h, --hostname="": Container host name + -i, --interactive=false: Keep stdin open even if not attached + --privileged=false: Give extended privileges to this container + -m, --memory="": Memory limit (format: , where unit = b, k, m or g) + -n, --networking=true: Enable networking for this container + -p, --publish=[]: Map a network port to the container + --rm=false: Automatically remove the container when it exits (incompatible with -d) + -t, --tty=false: Allocate a pseudo-tty + -u, --user="": Username or UID + --dns=[]: Set custom dns servers for the container + --dns-search=[]: Set custom DNS search domains for the container + -v, --volume=[]: Create a bind mount to a directory or file with: [host-path]:[container-path]:[rw|ro]. If a directory "container-path" is missing, then docker creates a new volume. + --volumes-from="": Mount all volumes from the given container(s) + --entrypoint="": Overwrite the default entrypoint set by the image + -w, --workdir="": Working directory inside the container + --lxc-conf=[]: (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1" + --sig-proxy=true: Proxify all received signal to the process (even in non-tty mode) + --expose=[]: Expose a port from the container without publishing it to your host + --link="": Add link to another container (name:alias) + --name="": Assign the specified name to the container. If no name is specific docker will generate a random name + -P, --publish-all=false: Publish all exposed ports to the host interfaces - -a, --attach=map[]: Attach to stdin, stdout or stderr - -c, --cpu-shares=0: CPU shares (relative weight) - --cidfile="": Write the container ID to the file - -d, --detach=false: Detached mode: Run container in the background, print new container id - -e, --env=[]: Set environment variables - --env-file="": Read in a line delimited file of ENV variables - -h, --hostname="": Container host name - -i, --interactive=false: Keep stdin open even if not attached - --privileged=false: Give extended privileges to this container - -m, --memory="": Memory limit (format: , where unit = b, k, m or g) - -n, --networking=true: Enable networking for this container - -p, --publish=[]: Map a network port to the container - --rm=false: Automatically remove the container when it exits (incompatible with -d) - -t, --tty=false: Allocate a pseudo-tty - -u, --user="": Username or UID - --dns=[]: Set custom dns servers for the container - --dns-search=[]: Set custom DNS search domains for the container - -v, --volume=[]: Create a bind mount to a directory or file with: [host-path]:[container-path]:[rw|ro]. If a directory "container-path" is missing, then docker creates a new volume. - --volumes-from="": Mount all volumes from the given container(s) - --entrypoint="": Overwrite the default entrypoint set by the image - -w, --workdir="": Working directory inside the container - --lxc-conf=[]: (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1" - --sig-proxy=true: Proxify all received signal to the process (even in non-tty mode) - --expose=[]: Expose a port from the container without publishing it to your host - --link="": Add link to another container (name:alias) - --name="": Assign the specified name to the container. If no name is specific docker will generate a random name - -P, --publish-all=false: Publish all exposed ports to the host interfaces +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`. 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 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`. 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 [*change the command that a -container runs*](#commit-an-existing-container). +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`. +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`. ### Known Issues (run –volumes-from) -- [Issue 2702](https://github.com/dotcloud/docker/issues/2702): - "lxc-start: Permission denied - failed to mount" could indicate a - permissions problem with AppArmor. Please see the issue for a - workaround. +- [Issue 2702](https://github.com/dotcloud/docker/issues/2702): + "lxc-start: Permission denied - failed to mount" could indicate a + permissions problem with AppArmor. Please see the issue for a + workaround. ### 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. $ sudo docker run -t -i --rm ubuntu bash root@bc338942ef20:/# mount -t tmpfs none /mnt mount: permission denied -This will *not* work, because by default, most potentially dangerous -kernel capabilities are dropped; including `cap_sys_admin` -(which is required to mount filesystems). However, the -`--privileged` flag will allow it to run: +This will *not* work, because by default, most potentially dangerous kernel +capabilities are dropped; including `cap_sys_admin` (which is required to mount +filesystems). However, the `--privileged` flag will allow it to run: $ sudo docker run --privileged ubuntu bash root@50e3f57e16e6:/# mount -t tmpfs none /mnt @@ -889,30 +879,27 @@ kernel capabilities are dropped; including `cap_sys_admin` Filesystem Size Used Avail Use% Mounted on none 1.9G 0 1.9G 0% /mnt -The `--privileged` flag gives *all* capabilities to -the container, and it also lifts all the limitations enforced by the -`device` cgroup controller. In other words, the -container can then do almost everything that the host can do. This flag -exists to allow special use-cases, like running Docker within Docker. +The `--privileged` flag gives *all* capabilities to the container, and it also +lifts all the limitations enforced by the `device` cgroup controller. In other +words, the container can then do almost everything that the host can do. This +flag exists to allow special 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 container. +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 container. $ sudo docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd -The `-v` flag mounts the current working directory -into the container. The `-w` lets the command being -executed inside the current working directory, by changing into the -directory to the value returned by `pwd`. So this +The `-v` flag mounts the current working directory into the container. The `-w` +lets the command being executed inside the current working directory, by +changing into the directory to the value returned by `pwd`. So this combination executes the command using the container, but inside the current working directory. $ sudo docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash -When the host directory of a bind-mounted volume doesn’t exist, Docker +When the host directory of a bind-mounted volume doesn't exist, Docker will automatically create this directory on the host for you. In the example above, Docker will create the `/doesnt/exist` folder before starting your container. @@ -920,49 +907,43 @@ folder before starting your container. $ sudo docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v ./static-docker:/usr/bin/docker busybox sh By bind-mounting the docker unix socket and statically linked docker -binary (such as that provided by -[https://get.docker.io](https://get.docker.io)), you give the container -the full access to create and manipulate the host’s docker daemon. +binary (such as that provided by [https://get.docker.io]( +https://get.docker.io)), you give the container the full access to create and +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) explains in -detail how to manipulate ports in Docker. +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) +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. [*Redirect Ports*]( +../../../use/port_redirection/#port-redirection) explains in detail how to +manipulate ports in Docker. $ sudo docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash -This sets environmental variables in the container. For illustration all -three flags are shown here. Where `-e`, -`--env` take an environment variable and value, or -if no "=" is provided, then that variable’s current value is passed -through (i.e. $MYVAR1 from the host is set to $MYVAR1 in the -container). All three flags, `-e`, `--env` -and `--env-file` can be repeated. +This sets environmental variables in the container. For illustration all three +flags are shown here. Where `-e`, `--env` take an environment variable and +value, or if no "=" is provided, then that variable's current value is passed +through (i.e. $MYVAR1 from the host is set to $MYVAR1 in the container). All +three flags, `-e`, `--env` and `--env-file` can be repeated. -Regardless of the order of these three flags, the `--env-file` -are processed first, and then `-e`, `--env` flags. This way, the -`-e` or `--env` will override variables as needed. +Regardless of the order of these three flags, the `--env-file` are processed +first, and then `-e`, `--env` flags. This way, the `-e` or `--env` will +override variables as needed. $ cat ./env.list TEST_FOO=BAR $ sudo docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO TEST_FOO=This is a test -The `--env-file` flag takes a filename as an -argument and expects each line to be in the VAR=VAL format, mimicking -the argument passed to `--env`. Comment lines need -only be prefixed with `#` +The `--env-file` flag takes a filename as an argument and expects each line +to be in the VAR=VAL format, mimicking the argument passed to `--env`. Comment +lines need only be prefixed with `#` An example of a file passed with `--env-file` @@ -991,48 +972,44 @@ This will create and run a new container with the container name being $ sudo docker run --link /redis:redis --name console ubuntu bash -The `--link` flag will link the container named -`/redis` into the newly created container with the -alias `redis`. The new container can access the -network and environment of the redis container via environment -variables. The `--name` flag will assign the name -`console` to the newly created container. +The `--link` flag will link the container named `/redis` into the newly +created container with the alias `redis`. The new container can access the +network and environment of the redis container via environment variables. +The `--name` flag will assign the name `console` 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 referenced containers. Containers can be specified by a -comma separated 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 read-only or read-write mode, respectively. By default, the -volumes are mounted in the same mode (read write or read only) as the -reference container. +The `--volumes-from` flag mounts all the defined volumes from the referenced +containers. Containers can be specified by a comma separated 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 read-only +or read-write mode, respectively. By default, the volumes are mounted in +the same mode (read write or read only) as the reference container. -The `-a` flag tells `docker run` -to bind to the container’s stdin, stdout or stderr. This makes it -possible to manipulate the output and input as needed. +The `-a` flag tells `docker run` to bind to the container'sstdin, stdout or +stderr. This makes it possible to manipulate the output and input as needed. $ sudo echo "test" | docker run -i -a stdin ubuntu cat - -This pipes data into a container and prints the container’s ID by -attaching only to the container’s stdin. +This pipes data into a container and prints the container's ID by attaching +only to the container'sstdin. $ sudo docker run -a stderr ubuntu echo test -This isn’t going to print anything unless there’s an error because we’ve -only attached to the stderr of the container. The container’s logs still -store what’s been written to stderr and stdout. +This isn't going to print anything unless there's an error because We've +only attached to the stderr of the container. The container's logs still + store what's been written to stderr and stdout. $ sudo cat somefile | docker run -i -a stdin mybuilder dobuild This is how piping a file into a container could be done for a build. -The container’s ID will be printed after the build is done and the build +The container's ID will be printed after the build is done and the build logs could be retrieved using `docker logs`. This is useful if you need to pipe a file or something else into a container and -retrieve the container’s ID once the container has finished running. +retrieve the container's ID once the container has finished running. -#### A complete example +**A complete example:** $ sudo docker run -d --name static static-web-files sh $ sudo docker run -d --expose=8098 --name riak riakserver @@ -1043,45 +1020,33 @@ retrieve the container’s ID once the container has finished running. 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` 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` in the container to port `1443` - on the Docker server, setting the DNS server to - `dns.dev.org` and DNS search domain to - `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. +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` in the container to port `1443` on + the Docker server, setting the DNS server to `dns.dev.org` and DNS search + domain to `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. -## `save` +## save + +Save an image to a tar archive (streamed to stdout by default) Usage: docker save IMAGE - Save an image to a tar archive (streamed to stdout by default) - - -o, --output="": Write to an file, instead of STDOUT + -o, --output="": Write to an file, instead of STDOUT Produces a tarred repository to the standard output stream. Contains all parent layers, and all tags + versions, or specified repo:tag. @@ -1098,65 +1063,65 @@ It is used to create a backup that can then be used with $ sudo docker save -o fedora-all.tar fedora $ sudo docker save -o fedora-latest.tar fedora:latest -## `search` +## search + +Search the docker index for images Usage: docker search TERM - Search the docker index for images - --no-trunc=false: Don᾿t truncate output -s, --stars=0: Only displays with at least xxx stars -t, --trusted=false: Only show trusted builds -See [*Find Public Images on the Central -Index*](../../../use/workingwithrepository/#searching-central-index) for +See [*Find Public Images on the Central Index*]( +../../../use/workingwithrepository/#searching-central-index) for more details on finding shared images from the commandline. -## `start` +## start + +Start a stopped container Usage: docker start [OPTIONS] CONTAINER - Start a stopped container - -a, --attach=false: Attach container᾿s stdout/stderr and forward all signals to the process -i, --interactive=false: Attach container᾿s stdin -## `stop` +## stop + +Stop a running container (Send SIGTERM, and then SIGKILL after grace period) Usage: docker stop [OPTIONS] CONTAINER [CONTAINER...] - Stop a running container (Send SIGTERM, and then SIGKILL after grace period) - - -t, --time=10: Number of seconds to wait for the container to stop before killing it. + -t, --time=10: Number of seconds to wait for the container to stop before killing it. The main process inside the container will receive SIGTERM, and after a grace period, SIGKILL -## `tag` +## tag + +Tag an image into a repository Usage: docker tag [OPTIONS] IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG] - Tag an image into a repository - - -f, --force=false: Force + -f, --force=false: Force 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). +them to [*Share Images via Repositories*]( +../../../use/workingwithrepository/#working-with-the-repository). -## `top` +## top Usage: docker top CONTAINER [ps OPTIONS] - Lookup the running processes of a container +Lookup the running processes of a container -## `version` +## version Show the version of the Docker client, daemon, and latest released version. -## `wait` +## wait Usage: docker wait [OPTIONS] NAME - Block until a container stops, then print its exit code. +Block until a container stops, then print its exit code. \ No newline at end of file diff --git a/docs/sources/reference/run.md b/docs/sources/reference/run.md index 236b8065b8..f6f132a09d 100644 --- a/docs/sources/reference/run.md +++ b/docs/sources/reference/run.md @@ -2,7 +2,7 @@ page_title: Docker Run Reference page_description: Configure containers at runtime page_keywords: docker, run, configure, runtime -# [Docker Run Reference](#id2) +# Docker Run Reference **Docker runs processes in isolated containers**. When an operator executes `docker run`, she starts a process with its @@ -10,59 +10,60 @@ own file system, its own networking, and its own isolated process tree. 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 +the operator who starts the container from the image. That's the main +reason [*run*](../../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](#id3) +## General Form -As you’ve seen in the [*Examples*](../../examples/#example-list), the +As you`ve seen in the [*Examples*](../../examples/#example-list), the basic 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*](../../commandline/cli/#cli-options). The list of `[OPTIONS]` breaks down into two groups: -1. Settings exclusive to operators, including: - - Detached or Foreground running, - - Container Identification, - - Network settings, and - - Runtime Constraints on CPU and Memory - - Privileges and LXC Configuration +1. Settings exclusive to operators, including: -2. Setting shared between operators and developers, where operators can - override defaults developers set in images at build time. + - Detached or Foreground running, + - Container Identification, + - Network settings, and + - Runtime Constraints on CPU and Memory + - Privileges and LXC Configuration + +2. Setting shared between operators and developers, where operators can + override defaults developers set in images at build time. Together, the `docker run [OPTIONS]` give complete control over runtime behavior to the operator, allowing them to override all defaults set by the developer during `docker build` and nearly all the defaults set by the Docker runtime itself. -## [Operator Exclusive Options](#id4) +## Operator Exclusive Options Only the operator (the person executing `docker run`) can set the following options. -- [Detached vs Foreground](#detached-vs-foreground) - - [Detached (-d)](#detached-d) - - [Foreground](#foreground) -- [Container Identification](#container-identification) - - [Name (–name)](#name-name) - - [PID Equivalent](#pid-equivalent) -- [Network Settings](#network-settings) -- [Clean Up (–rm)](#clean-up-rm) -- [Runtime Constraints on CPU and + - [Detached vs Foreground](#detached-vs-foreground) + - [Detached (-d)](#detached-d) + - [Foreground](#foreground) + - [Container Identification](#container-identification) + - [Name (–name)](#name-name) + - [PID Equivalent](#pid-equivalent) + - [Network Settings](#network-settings) + - [Clean Up (–rm)](#clean-up-rm) + - [Runtime Constraints on CPU and Memory](#runtime-constraints-on-cpu-and-memory) -- [Runtime Privilege and LXC + - [Runtime Privilege and LXC Configuration](#runtime-privilege-and-lxc-configuration) -### [Detached vs Foreground](#id2) +## Detached vs Foreground When starting a Docker container, you must first decide if you want to run the container in the background in a "detached" mode or in the @@ -70,53 +71,50 @@ default foreground mode: -d=false: Detached mode: Run container in the background, print new container id -#### [Detached (-d)](#id3) +### Detached (-d) 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`. You can reattach to a detached container with `docker` -[*attach*](../commandline/cli/#cli-attach). If you choose to run a +[*attach*](commandline/cli/#attach). If you choose to run a container in the detached mode, then you cannot use the `--rm` option. -#### [Foreground](#id4) +### Foreground -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 of -that is configurable: +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 +of that is configurable: -a=[] : Attach to ``stdin``, ``stdout`` and/or ``stderr`` -t=false : Allocate a pseudo-tty --sig-proxy=true: Proxify all received signal to the process (even in non-tty mode) -i=false : Keep STDIN open even if not attached -If you do not specify `-a` then Docker will [attach -everything -(stdin,stdout,stderr)](https://github.com/dotcloud/docker/blob/75a7f4d90cde0295bcfb7213004abce8d4779b75/commands.go#L1797). -You can specify to which of the three standard streams -(`stdin`, `stdout`, -`stderr`) you’d like to connect instead, as in: +If you do not specify `-a` then Docker will [attach everything (stdin,stdout,stderr)]( +https://github.com/dotcloud/docker/blob/ +75a7f4d90cde0295bcfb7213004abce8d4779b75/commands.go#L1797). You can specify to which +of the three standard streams (`stdin`, `stdout`, `stderr`) you'd like to connect +instead, as in: docker run -a stdin -a stdout -i -t ubuntu /bin/bash -For interactive processes (like a shell) you will typically want a tty -as well as persistent standard input (`stdin`), so -you’ll use `-i -t` together in most interactive -cases. +For interactive processes (like a shell) you will typically want a tty as well as +persistent standard input (`stdin`), so you'll use `-i -t` together in most +interactive cases. -### [Container Identification](#id5) +## Container Identification -#### [Name (–name)](#id6) +### Name (–name) The operator can identify a container in three ways: - UUID long identifier ("f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778") - UUID short identifier ("f78375b1c487") -- Name ("evil\_ptolemy") +- Name ("evil_ptolemy") The UUID identifiers come from the Docker daemon, and if you do not assign a name to the container with `--name` then @@ -127,16 +125,16 @@ name when defining (or any other place you need to identify a container). This works for both background and foreground Docker containers. -#### [PID Equivalent](#id7) +### 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 -programs might write out their process ID to a file (you’ve seen them as +programs might write out their process ID to a file (you`ve seen them as PID files): --cidfile="": Write the container ID to the file -### [Network Settings](#id8) +## Network Settings -n=true : Enable networking for this container --dns=[] : Set custom dns servers for the container @@ -150,19 +148,19 @@ files or STDIN/STDOUT only. Your container will use the same DNS servers as the host by default, but you can override this with `--dns`. -### [Clean Up (–rm)](#id9) +## Clean Up (–rm) -By default a container’s file system persists even after the container +By default a container's file system persists even after the container exits. This makes debugging a lot easier (since you can inspect the final state) and you retain all your data by default. But if you are running short-term **foreground** processes, these container file -systems can really pile up. If instead you’d like Docker to +systems can really pile up. If instead you'd like Docker to **automatically clean up the container and remove the file system when the container exits**, you can add the `--rm` flag: --rm=false: Automatically remove the container when it exits (incompatible with -d) -### [Runtime Constraints on CPU and Memory](#id10) +## Runtime Constraints on CPU and Memory The operator can also adjust the performance parameters of the container: @@ -181,7 +179,7 @@ the same priority and get the same proportion of CPU cycles, but you can tell the kernel to give more shares of CPU time to one or more containers when you start them via Docker. -### [Runtime Privilege and LXC Configuration](#id11) +## Runtime Privilege and LXC Configuration --privileged=false: Give extended privileges to this container --lxc-conf=[]: (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1" @@ -189,71 +187,63 @@ containers when you start them via Docker. By default, Docker containers are "unprivileged" and cannot, for example, run a Docker daemon inside a Docker container. This is because by default a container is not allowed to access any devices, but a -"privileged" container is given access to all devices (see -[lxc-template.go](https://github.com/dotcloud/docker/blob/master/execdriver/lxc/lxc_template.go) -and documentation on [cgroups -devices](https://www.kernel.org/doc/Documentation/cgroups/devices.txt)). +"privileged" container is given access to all devices (see [lxc-template.go]( +https://github.com/dotcloud/docker/blob/master/execdriver/lxc/lxc_template.go) +and documentation on [cgroups devices]( +https://www.kernel.org/doc/Documentation/cgroups/devices.txt)). When the operator executes `docker run --privileged`, Docker will enable to access to all devices on the host as well as set some configuration in AppArmor to allow the container nearly all the same access to the host as processes running outside containers on the host. Additional information about running with `--privileged` is available on the -[Docker -Blog](http://blog.docker.io/2013/09/docker-can-now-run-within-docker/). +[Docker Blog](http://blog.docker.io/2013/09/docker-can-now-run-within-docker/). -If the Docker daemon was started using the `lxc` -exec-driver (`docker -d --exec-driver=lxc`) then the -operator can also specify LXC options using one or more -`--lxc-conf` parameters. These can be new parameters -or override existing parameters from the -[lxc-template.go](https://github.com/dotcloud/docker/blob/master/execdriver/lxc/lxc_template.go). -Note that in the future, a given host’s Docker daemon may not use LXC, -so this is an implementation-specific configuration meant for operators -already familiar with using LXC directly. +If the Docker daemon was started using the `lxc` exec-driver +(`docker -d --exec-driver=lxc`) then the operator can also specify LXC options +using one or more `--lxc-conf` parameters. These can be new parameters or +override existing parameters from the [lxc-template.go]( +https://github.com/dotcloud/docker/blob/master/execdriver/lxc/lxc_template.go). +Note that in the future, a given host's docker daemon may not use LXC, so this +is an implementation-specific configuration meant for operators already +familiar with using LXC directly. -## Overriding `Dockerfile` Image Defaults +## Overriding Dockerfile Image Defaults -When a developer builds an image from a -[*Dockerfile*](../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. +When a developer builds an image from a [*Dockerfile*](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. -Four of the `Dockerfile` commands cannot be -overridden at runtime: `FROM, MAINTAINER, RUN`, and -`ADD`. Everything else has a corresponding override -in `docker run`. We’ll go through what the developer -might have set in each `Dockerfile` instruction and -how the operator can override that setting. +Four of the Dockerfile commands cannot be overridden at runtime: `FROM`, +`MAINTAINER`, `RUN`, and `ADD`. Everything else has a corresponding override +in `docker run`. We'll go through what the developer might have set in each +Dockerfile instruction and how the operator can override that setting. -- [CMD (Default Command or Options)](#cmd-default-command-or-options) -- [ENTRYPOINT (Default Command to Execute at - Runtime](#entrypoint-default-command-to-execute-at-runtime) -- [EXPOSE (Incoming Ports)](#expose-incoming-ports) -- [ENV (Environment Variables)](#env-environment-variables) -- [VOLUME (Shared Filesystems)](#volume-shared-filesystems) -- [USER](#user) -- [WORKDIR](#workdir) + - [CMD (Default Command or Options)](#cmd-default-command-or-options) + - [ENTRYPOINT (Default Command to Execute at Runtime]( + #entrypoint-default-command-to-execute-at-runtime) + - [EXPOSE (Incoming Ports)](#expose-incoming-ports) + - [ENV (Environment Variables)](#env-environment-variables) + - [VOLUME (Shared Filesystems)](#volume-shared-filesystems) + - [USER](#user) + - [WORKDIR](#workdir) -### [CMD (Default Command or Options)](#id12) +## CMD (Default Command or Options) Recall the optional `COMMAND` in the Docker commandline: docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...] -This command is optional because the person who created the -`IMAGE` may have already provided a default -`COMMAND` using the `Dockerfile` -`CMD`. As the operator (the person running a -container from the image), you can override that `CMD` -just by specifying a new `COMMAND`. +This command is optional because the person who created the `IMAGE` may have +already provided a default `COMMAND` using the Dockerfile `CMD`. As the +operator (the person running a container from the image), you can override that +`CMD` just by specifying a new `COMMAND`. -If the image also specifies an `ENTRYPOINT` then the -`CMD` or `COMMAND` get appended -as arguments to the `ENTRYPOINT`. +If the image also specifies an `ENTRYPOINT` then the `CMD` or `COMMAND` get +appended as arguments to the `ENTRYPOINT`. -### [ENTRYPOINT (Default Command to Execute at Runtime](#id13) +## ENTRYPOINT (Default Command to Execute at Runtime --entrypoint="": Overwrite the default entrypoint set by the image @@ -276,13 +266,12 @@ or two examples of how to pass more parameters to that ENTRYPOINT: docker run -i -t --entrypoint /bin/bash example/redis -c ls -l docker run -i -t --entrypoint /usr/bin/redis-cli example/redis --help -### [EXPOSE (Incoming Ports)](#id14) +## EXPOSE (Incoming Ports) -The `Dockerfile` doesn’t give much control over -networking, only providing the `EXPOSE` instruction -to give a hint to the operator about what incoming ports might provide -services. The following options work with or override the -`Dockerfile`‘s exposed defaults: +The Dockerfile doesn't give much control over networking, only providing the +`EXPOSE` instruction to give a hint to the operator about what incoming ports +might provide services. The following options work with or override the +Dockerfile's exposed defaults: --expose=[]: Expose a port from the container without publishing it to your host @@ -293,40 +282,34 @@ services. The following options work with or override the (use 'docker port' to see the actual mapping) --link="" : Add link to another container (name:alias) -As mentioned previously, `EXPOSE` (and -`--expose`) make a port available **in** a container -for incoming connections. The port number on the inside of the container -(where the service listens) does not need to be the same number as the -port exposed on the outside of the container (where clients connect), so -inside the container you might have an HTTP service listening on port 80 -(and so you `EXPOSE 80` in the -`Dockerfile`), but outside the container the port -might be 42800. +As mentioned previously, `EXPOSE` (and `--expose`) make a port available **in** +a container for incoming connections. The port number on the inside of the +container (where the service listens) does not need to be the same number as the +port exposed on the outside of the container (where clients connect), so inside +the container you might have an HTTP service listening on port 80 (and so you +`EXPOSE 80` in the Dockerfile), but outside the container the port might be +42800. -To help a new client container reach the server container’s internal -port operator `--expose`‘d by the operator or -`EXPOSE`‘d by the developer, the operator has three -choices: start the server container with `-P` or -`-p,` or start the client container with -`--link`. +To help a new client container reach the server container's internal port +operator `--expose``d by the operator or `EXPOSE``d by the developer, the +operator has three choices: start the server container with `-P` or `-p,` or +start the client container with `--link`. -If the operator uses `-P` or `-p` -then Docker will make the exposed port accessible on the host -and the ports will be available to any client that can reach the host. -To find the map between the host ports and the exposed ports, use -`docker port`) +If the operator uses `-P` or `-p` then Docker will make the exposed port +accessible on the host and the ports will be available to any client that +can reach the host. To find the map between the host ports and the exposed +ports, use `docker port`) -If the operator uses `--link` when starting the new -client container, then the client container can access the exposed port -via a private networking interface. Docker will set some environment -variables in the client container to help indicate which interface and -port to use. +If the operator uses `--link` when starting the new client container, then the +client container can access the exposed port via a private networking interface. +Docker will set some environment variables in the client container to help +indicate which interface and port to use. -### [ENV (Environment Variables)](#id15) +## ENV (Environment Variables) -The operator can **set any environment variable** in the container by -using one or more `-e` flags, even overriding those -already defined by the developer with a Dockefile `ENV`: +The operator can **set any environment variable** in the container by using one +or more `-e` flags, even overriding those already defined by the developer with +a Dockefile `ENV`: $ docker run -e "deep=purple" --rm ubuntu /bin/bash -c export declare -x HOME="/" @@ -340,10 +323,10 @@ already defined by the developer with a Dockefile `ENV`: Similarly the operator can set the **hostname** with `-h`. -`--link name:alias` also sets environment variables, -using the *alias* string to define environment variables within the -container that give the IP and PORT information for connecting to the -service container. Let’s imagine we have a container running Redis: +`--link name:alias` also sets environment variables, using the *alias* string to +define environment variables within the container that give the IP and PORT +information for connecting to the service container. Let's imagine we have a +container running Redis: # Start the service container, named redis-name $ docker run -d --name redis-name dockerfiles/redis @@ -358,7 +341,7 @@ service container. Let’s imagine we have a container running Redis: $ docker port 4241164edf6f 6379 2014/01/25 00:55:38 Error: No public port '6379' published for 4241164edf6f -Yet we can get information about the Redis container’s exposed ports +Yet we can get information about the Redis container'sexposed ports with `--link`. Choose an alias that will form a valid environment variable! @@ -377,40 +360,36 @@ valid environment variable! declare -x SHLVL="1" declare -x container="lxc" -And we can use that information to connect from another container as a -client: +And we can use that information to connect from another container as a client: $ docker run -i -t --rm --link redis-name:redis_alias --entrypoint /bin/bash dockerfiles/redis -c '/redis-stable/src/redis-cli -h $REDIS_ALIAS_PORT_6379_TCP_ADDR -p $REDIS_ALIAS_PORT_6379_TCP_PORT' 172.17.0.32:6379> -### [VOLUME (Shared Filesystems)](#id16) +## VOLUME (Shared Filesystems) -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro]. If "container-dir" is missing, then docker creates a new volume. --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). 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). +The volumes commands are complex enough to have their own documentation in +section [*Share Directories via Volumes*](../../use/working_with_volumes/#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). -### [USER](#id17) +## USER -The default user within a container is `root` (id = -0), but if the developer created additional users, those are accessible -too. The developer can set a default user to run the first process with -the `Dockerfile USER` command, but the operator can -override it +The default user within a container is `root` (id = 0), but if the developer +created additional users, those are accessible too. The developer can set a +default user to run the first process with the `Dockerfile USER` command, +but the operator can override it: -u="": Username or UID -### [WORKDIR](#id18) +## WORKDIR -The default working directory for running binaries within a container is -the root directory (`/`), but the developer can set -a different default with the `Dockerfile WORKDIR` -command. The operator can override this with: +The default working directory for running binaries within a container is the +root directory (`/`), but the developer can set a different default with the +Dockerfile `WORKDIR` command. The operator can override this with: -w="": Working directory inside the container