diff --git a/docs/sources/reference/builder.md b/docs/sources/reference/builder.md new file mode 100644 index 0000000000..2c55448a41 --- /dev/null +++ b/docs/sources/reference/builder.md @@ -0,0 +1,510 @@ +page_title: Dockerfile Reference +page_description: Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image. +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. + +## 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. + +Then call `docker build` with the path of your +source repository as argument (for example, `.`): + +> `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 +whole context must be transferred to the daemon. The Docker CLI reports +"Uploading context" when the context is sent to the daemon. + +You can specify a repository and tag at which to save the new image if +the build succeeds: + +> `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 +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. + +Whenever possible, Docker will re-use the intermediate images, +accelerating `docker build` significantly (indicated +by `Using cache`): + + $ docker build -t SvenDowideit/ambassador . + Uploading context 10.24 kB + Uploading context + Step 1 : FROM docker-ut + ---> cbba202fe96b + Step 2 : MAINTAINER SvenDowideit@home.org.au + ---> Using cache + ---> 51182097be13 + Step 3 : CMD env | grep _TCP= | sed 's/.*_PORT_\([0-9]*\)_TCP=tcp:\/\/\(.*\):\(.*\)/socat TCP4-LISTEN:\1,fork,reuseaddr TCP4:\2:\3 \&/' | sh && top + ---> 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). + +## Format + +Here is the format of the Dockerfile: + + # Comment + INSTRUCTION arguments + +The Instruction is not case-sensitive, however convention is for them to +be UPPERCASE in order to distinguish them from arguments more easily. + +Docker evaluates the instructions in a Dockerfile in order. **The first +instruction must be \`FROM\`** in order to specify the [*Base +Image*](../../terms/image/#base-image-def) from which you are building. + +Docker will treat lines that *begin* with `#` as a +comment. A `#` marker anywhere else in the line will +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` +for building images. + +## `FROM` + +> `FROM ` + +Or + +> `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). + +`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. + +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 ` + +The `MAINTAINER` instruction allows you to set the +*Author* field of the generated images. + +## `RUN` + +RUN has 2 forms: + +- `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. + +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`. + +### 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. + +## `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*) + +There can only be one CMD in a Dockerfile. If you list more than one CMD +then only the last CMD will take effect. + +**The main purpose of a CMD is to provide defaults for an executing +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. + +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: + + 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 +[*ENTRYPOINT*](#dockerfile-entrypoint). + +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 the +result; `CMD` does not execute anything at build +time, but specifies the intended command for the image. + +## `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 +[*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)). + +## `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 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` + +## `ADD` + +> `ADD ` + +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. + +`` 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. + +Note + +if you build using STDIN (`docker build - < somefile` +.literal}), there is no build context, so the Dockerfile can only +contain an URL based ADD statement. + +Note + +if your URL files are protected using authentication, you will need to +use an `RUN wget` , `RUN curl` +or other tool from within the container as ADD does not support +authentication. + +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. + +- 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 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. + + 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. + +- 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 `` 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 has two forms: + +- `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. + +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` +.literal}. 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 +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`: + + FROM ubuntu + ENTRYPOINT wc -l - + +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: + + FROM ubuntu + CMD ["-l", "-"] + ENTRYPOINT ["/usr/bin/wc"] + +## `VOLUME` + +> `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. + +## `USER` + +> `USER daemon` + +The `USER` instruction sets the username or UID to +use when running the image. + +## `WORKDIR` + +> `WORKDIR /path/to/workdir` + +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: + +> 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 [INSTRUCTION]` + +The `ONBUILD` instruction adds to the image a +"trigger" instruction to be executed at a later time, when the image is +used as the base for another build. The trigger will be executed in the +context of the downstream build, as if it had been inserted immediately +after the *FROM* instruction in the downstream Dockerfile. + +Any build instruction can be registered as a trigger. + +This is useful if you are building an image which will be used as a base +to build other images, for example an application build environment or a +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 +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 +that is inefficient, error-prone and difficult to update because it +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: + +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: + + [...] + ONBUILD ADD . /app/src + ONBUILD RUN /usr/local/bin/python-build --dir /app/src + [...] + +Warning + +Chaining ONBUILD instructions using ONBUILD ONBUILD isn’t allowed. + +Warning + +ONBUILD may not trigger FROM or MAINTAINER instructions. + +## Dockerfile Examples + + # Nginx + # + # VERSION 0.0.1 + + FROM ubuntu + MAINTAINER Guillaume J. Charmes + + # make sure the package repository is up to date + RUN echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > /etc/apt/sources.list + RUN apt-get update + + RUN apt-get install -y inotify-tools nginx apache2 openssh-server + + # Firefox over VNC + # + # VERSION 0.3 + + FROM ubuntu + # make sure the package repository is up to date + RUN echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > /etc/apt/sources.list + RUN apt-get update + + # Install vnc, xvfb in order to create a 'fake' display and firefox + RUN apt-get install -y x11vnc xvfb firefox + RUN mkdir /.vnc + # Setup a password + RUN x11vnc -storepasswd 1234 ~/.vnc/passwd + # Autostart firefox (might not be the best way, but it does the trick) + RUN bash -c 'echo "firefox" >> /.bashrc' + + EXPOSE 5900 + CMD ["x11vnc", "-forever", "-usepw", "-create"] + + # Multiple images example + # + # VERSION 0.1 + + FROM ubuntu + RUN echo foo > bar + # Will output something like ===> 907ad6c2736f + + FROM ubuntu + RUN echo moo > oink + # Will output something like ===> 695d7793cbe4 + + # You'll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with + # /oink. diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md new file mode 100644 index 0000000000..6bb0dc9e22 --- /dev/null +++ b/docs/sources/reference/commandline/cli.md @@ -0,0 +1,1170 @@ +page_title: Command Line Interface +page_description: Docker's CLI command description and usage +page_keywords: Docker, Docker documentation, CLI, command line + +# Command Line + +To list available commands, either run `docker` with +no parameters or execute `docker help`: + + $ sudo docker + Usage: docker [OPTIONS] COMMAND [arg...] + -H=[unix:///var/run/docker.sock]: tcp://[host]:port to bind/connect to or unix://[/path/to/socket] to use. When host=[127.0.0.1] is omitted for tcp or path=[/var/run/docker.sock] is omitted for unix sockets, default values are used. + + A self-sufficient runtime for linux containers. + + ... + +## Option types + +Single character commandline options can be combined, so rather than +typing `docker run -t -i --name test busybox sh`, +you can write `docker run -ti --name test busybox sh` +.literal}. + +### Boolean + +Boolean options look like `-d=false`. The value you +see is the default value which gets set if you do **not** use the +boolean flag. If you do call `run -d`, that sets the +opposite boolean value, so in this case, `true`, and +so `docker run -d` **will** run in "detached" mode, +in the background. Other boolean options are similar – specifying them +will set the value to the opposite of the default value. + +### Multi + +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`: + + docker run -v /host:/container example/mysql + +### Strings and Integers + +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` + + 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 + --api-enable-cors=false: Enable CORS headers in the remote API + -b, --bridge="": Attach containers to a pre-existing network bridge; use 'none' to disable container networking + -bip="": Use this CIDR notation address for the network bridge's IP, not compatible with -b + -d, --daemon=false: Enable daemon mode + --dns=[]: Force docker to use specific DNS servers + --dns-search=[]: Force Docker to use specific DNS search domains + -g, --graph="/var/lib/docker": Path to use as the root of the docker runtime + --icc=true: Enable inter-container communication + --ip="0.0.0.0": Default IP address to use when binding container ports + --ip-forward=true: Enable net.ipv4.ip_forward + --iptables=true: Enable Docker's addition of iptables rules + -p, --pidfile="/var/run/docker.pid": Path to use for daemon PID file + -r, --restart=true: Restart previously running containers + -s, --storage-driver="": Force the docker runtime to use a specific storage driver + -e, --exec-driver="native": Force the docker runtime to use a specific exec driver + -v, --version=false: Print version information and quit + --tls=false: Use TLS; implied by tls-verify flags + --tlscacert="~/.docker/ca.pem": Trust only remotes providing a certificate signed by the CA given here + --tlscert="~/.docker/cert.pem": Path to TLS certificate file + --tlskey="~/.docker/key.pem": Path to TLS key file + --tlsverify=false: Use TLS and verify the remote (daemon: verify client, client: verify daemon) + --mtu=0: Set the containers network MTU; if no value is provided: default to the default route MTU or 1500 if no default route is available + +The Docker daemon is the persistent process that manages containers. +Docker uses the same binary for both the daemon and client. To run the +daemon you provide the `-d` flag. + +To force Docker to use devicemapper as the storage driver, use +`docker -d -s devicemapper`. + +To set the DNS server for all Docker containers, use +`docker -d --dns 8.8.8.8`. + +To set the DNS search domain for all Docker containers, use +`docker -d --dns-search example.com`. + +To run the daemon with debug output, use `docker -d -D` +.literal}. + +To use lxc as the execution driver, use `docker -d -e lxc` +.literal}. + +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 + export DOCKER_HOST="tcp://0.0.0.0:4243" + 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 +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/). + +Docker supports softlinks for the Docker data directory +(`/var/lib/docker`) and for `/tmp` +.literal}. 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` + + 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) + +The `attach` command will allow you to view or +interact with any running container, detached (`-d`) +or interactive (`-i`). You can attach to the same +container at the same time - screen sharing style, or quickly view the +progress of your daemonized process. + +You can detach from the container again (and leave it running) with +`CTRL-C` (for a quiet exit) or `CTRL-\` +to get a stacktrace of the Docker client when it quits. When +you detach from the container’s process the exit code will be returned +to the client. + +To stop a container, use `docker stop`. + +To kill the container, use `docker kill`. + +### Examples: + + $ ID=$(sudo docker run -d ubuntu /usr/bin/top -b) + $ sudo docker attach $ID + top - 02:05:52 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + Cpu(s): 0.1%us, 0.2%sy, 0.0%ni, 99.7%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st + Mem: 373572k total, 355560k used, 18012k free, 27872k buffers + Swap: 786428k total, 0k used, 786428k free, 221740k cached + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 17200 1116 912 R 0 0.3 0:00.03 top + + top - 02:05:55 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + Cpu(s): 0.0%us, 0.2%sy, 0.0%ni, 99.8%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st + Mem: 373572k total, 355244k used, 18328k free, 27872k buffers + Swap: 786428k total, 0k used, 786428k free, 221776k cached + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top + + + top - 02:05:58 up 3:06, 0 users, load average: 0.01, 0.02, 0.05 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + Cpu(s): 0.2%us, 0.3%sy, 0.0%ni, 99.5%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st + Mem: 373572k total, 355780k used, 17792k free, 27880k buffers + Swap: 786428k total, 0k used, 786428k free, 221776k cached + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top + ^C$ + $ sudo docker stop $ID + +## `build` + + 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` +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. + +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 + +See also + +[*Dockerfile Reference*](../../builder/#dockerbuilder). + +### Examples: + + $ sudo docker build . + Uploading context 10240 bytes + Step 1 : FROM busybox + Pulling repository busybox + ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/ + Step 2 : RUN ls -lh / + ---> Running in 9c9e81692ae9 + total 24 + drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin + drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev + drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc + drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib + lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib + dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc + lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin + dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys + drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp + drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr + ---> b35f4035db3f + Step 3 : CMD echo Hello World + ---> Running in 02071fceb21b + ---> f52f38b7823e + Successfully built f52f38b7823e + Removing intermediate container 9c9e81692ae9 + Removing intermediate container 02071fceb21b + +This example specifies that the `PATH` is +`.`, and so all the files in the local directory get +tar’d and sent to the Docker daemon. The `PATH` +specifies where to find the files for the "context" of the build on the +Docker daemon. Remember that the daemon could be running on a remote +machine and that no parsing of the `Dockerfile` +happens at the 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` +.literal}. + +The transfer of context from the local machine to the Docker daemon is +what the `docker` client means when you see the +"Uploading context" message. + +If you wish to keep the intermediate containers after the build is +complete, you must use `--rm=false`. This does not +affect the build cache. + + $ sudo docker build -t vieux/apache:2.0 . + +This will build like the previous example, but it will then tag the +resulting image. The repository name will be `vieux/apache` +and the tag will be `2.0` + + $ sudo docker build - < Dockerfile + +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` +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 +can specify an arbitrary Git repository by using the `git://` +schema. + +## `commit` + + 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 " + +It can be useful to commit a container’s file changes or settings into a +new image. This allows you debug a container by running an interactive +shell, or to export a working dataset to another server. Generally, it +is better to use Dockerfiles to manage your images in a documented and +maintainable way. + +### Commit an existing container + + $ sudo docker ps + ID IMAGE COMMAND CREATED STATUS PORTS + c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours + 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours + $ docker commit c3f279d17e0a SvenDowideit/testimage:version3 + f5283438590d + $ docker images | head + REPOSITORY TAG ID CREATED VIRTUAL SIZE + SvenDowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB + +## `cp` + + 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` + + 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’: + +1. `` `A` `` - Add +2. `` `D` `` - Delete +3. `` `C` `` - Change + +For example: + + $ sudo docker diff 7bb0e258aefe + + C /dev + A /dev/kmsg + C /etc + A /etc/mtab + A /go + A /go/src + A /go/src/github.com + A /go/src/github.com/dotcloud + A /go/src/github.com/dotcloud/docker + A /go/src/github.com/dotcloud/docker/.git + .... + +## `events` + + 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 + (either seconds since epoch, or date string as below) + +### Examples + +You’ll need two shells for this example. + +#### Shell 1: Listening for events + + $ sudo docker events + +#### Shell 2: Start and Stop a Container + + $ sudo docker start 4386fb97867d + $ sudo docker stop 4386fb97867d + +#### 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 + + $ sudo docker events --since 1378216169 + [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) die + [2013-09-03 15:49:29 +0200 CEST] 4386fb97867d: (from 12de384bfb10) stop + + $ sudo docker events --since '2013-09-03' + [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 + + $ sudo docker events --since '2013-09-03 15:49:29 +0200 CEST' + [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` + + 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` + + 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 + +To see how the `docker:latest` image was built: + + $ docker history docker + IMAGE CREATED CREATED BY SIZE + 3e23a5875458790b7a806f95f7ec0d0b2a5c1659bfc899c89f939f6d5b8f7094 8 days ago /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8 0 B + 8578938dd17054dce7993d21de79e96a037400e8d28e15e7290fea4f65128a36 8 days ago /bin/sh -c dpkg-reconfigure locales && locale-gen C.UTF-8 && /usr/sbin/update-locale LANG=C.UTF-8 1.245 MB + be51b77efb42f67a5e96437b3e102f81e0a1399038f77bf28cea0ed23a65cf60 8 days ago /bin/sh -c apt-get update && apt-get install -y git libxml2-dev python build-essential make gcc python-dev locales python-pip 338.3 MB + 4b137612be55ca69776c7f30c2d2dd0aa2e7d72059820abf3e25b629f887a084 6 weeks ago /bin/sh -c #(nop) ADD jessie.tar.xz in / 121 MB + 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` + + 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 + +The default `docker images` will show all top level +images, their repository and tags, and their virtual size. + +Docker images have intermediate layers that increase reuseability, +decrease disk usage, and speed up `docker build` by +allowing each step to be cached. These intermediate layers are not shown +by default. + +### Listing the most recently created images + + $ sudo docker images | head + REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + 77af4d6b9913 19 hours ago 1.089 GB + committest latest b6fa739cedf5 19 hours ago 1.089 GB + 78a85c484f71 19 hours ago 1.089 GB + docker latest 30557a29d5ab 20 hours ago 1.089 GB + 0124422dd9f9 20 hours ago 1.089 GB + 18ad6fad3402 22 hours ago 1.082 GB + f9f1e26352f0 23 hours ago 1.089 GB + tryout latest 2629d1fa0b81 23 hours ago 131.5 MB + 5ed6274db6ce 24 hours ago 1.089 GB + +### Listing the full length image IDs + + $ sudo docker images --no-trunc | head + REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + 77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB + committest latest b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB + 78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB + docker latest 30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB + 0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB + 18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB + f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB + tryout latest 2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB + 5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB + +## `import` + + Usage: docker import URL|- [REPOSITORY[:TAG]] + + Create an empty filesystem image and import the contents of the tarball + (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) into it, then optionally tag it. + +URLs must start with `http` and point to a single +file archive (.tar, .tar.gz, .tgz, .bzip, .tar.xz, or .txz) containing a +root filesystem. If you would like to import from a local directory or +archive, you can use the `-` parameter to take the +data from *stdin*. + +### Examples + +#### 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 to docker via pipe and *stdin*. + + $ cat exampleimage.tgz | sudo docker import - exampleimagelocal:new + +#### Import from a local directory + + $ sudo tar -c . | docker import - exampleimagedir + +Note the `sudo` in this example – you must preserve +the ownership of the files (especially root ownership) during the +archiving with tar. If you are not root (or the sudo command) when you +tar, then the ownerships might not get preserved. + +## `info` + + Usage: docker info + + Display system-wide information. + + $ sudo docker info + Containers: 292 + Images: 194 + Debug mode (server): false + Debug mode (client): false + Fds: 22 + Goroutines: 67 + LXC Version: 0.9.0 + EventsListeners: 115 + 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. + +## `inspect` + + 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. + +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 +describes all the details of the format. + +### Examples + +#### Get an instance’s IP 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 + +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 + +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 +port, you use `index` to find the specific port map, +and then `index` 0 contains first object inside of +that. Then we ask for the `HostPort` field to get +the public address. + + $ sudo docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID + +#### Get config + +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` + + Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...] + + Kill a running container (send SIGKILL, or specified signal) + + -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. + +## `load` + + Usage: docker load + + Load an image from a tar archive on 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. + + $ sudo docker images + REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + $ sudo docker load < busybox.tar + $ sudo docker images + REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + busybox latest 769b9341d937 7 weeks ago 2.489 MB + $ sudo docker load --input fedora.tar + $ sudo docker images + REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE + busybox latest 769b9341d937 7 weeks ago 2.489 MB + fedora rawhide 0d20aec6529d 7 weeks ago 387 MB + fedora 20 58394af37342 7 weeks ago 385.5 MB + fedora heisenbug 58394af37342 7 weeks ago 385.5 MB + fedora latest 58394af37342 7 weeks ago 385.5 MB + +## `login` + + 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. + + example: + docker login localhost:8080 + +## `logs` + + 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 +present at the time of execution. + +The `docker logs --follow` command combines +`docker logs` and `docker attach` +.literal}: it will first return all logs from the beginning and then +continue streaming new output from the container’s stdout and stderr. + +## `port` + + Usage: docker port [OPTIONS] CONTAINER PRIVATE_PORT + + Lookup the public-facing port which is NAT-ed to PRIVATE_PORT + +## `ps` + + Usage: docker ps [OPTIONS] + + List containers + + -a, --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. + + $ docker ps + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds webapp + d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db + +`docker ps` will show only running containers by +default. To see all containers: `docker ps -a` + +## `pull` + + 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)). + +The Docker Index contains many pre-built images that you can +`pull` and try without needing to define and +configure your own. + +To download a particular image, or set of images (i.e., a repository), +use `docker pull`: + + $ docker pull debian + # will pull all the images in the debian repository + $ docker pull debian:testing + # will pull only the image named debian:testing and any intermediate layers + # it is based on. (typically the empty `scratch` image, a MAINTAINERs layer, + # and the un-tared base. + +## `push` + + 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` + + 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 + +## `rm` + + 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 + +### Known Issues (rm) + +- [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. + +### Examples: + + $ sudo docker rm /redis + /redis + +This will remove the container referenced under the link +`/redis`. + + $ sudo docker rm --link /webapp/redis + /webapp/redis + +This will remove the underlying link between `/webapp` +and the `/redis` containers removing all +network communication. + + $ sudo docker rm $(docker ps -a -q) + +This command will delete all stopped containers. The command +`docker ps -a -q` will return all existing container +IDs and pass them to the `rm` command which will +delete them. Any running containers will not be deleted. + +## `rmi` + + Usage: docker rmi IMAGE [IMAGE...] + + Remove one or more images + + -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 +names. If an image has more than one name, each of them needs to be +removed before the image is removed. + + $ sudo docker images + REPOSITORY TAG IMAGE ID CREATED SIZE + test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + + $ sudo docker rmi fd484f19954f + Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories + 2013/12/11 05:47:16 Error: failed to remove one or more images + + $ sudo docker rmi test1 + Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 + $ sudo docker rmi test2 + Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 + + $ sudo docker images + REPOSITORY TAG IMAGE ID CREATED SIZE + test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) + $ sudo docker rmi test + Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 + Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 + +## `run` + + 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 + +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*](#cli-commit-examples). + +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`. + +### 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. + +### 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. + + $ 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: + + $ sudo docker run --privileged ubuntu bash + root@50e3f57e16e6:/# mount -t tmpfs none /mnt + root@50e3f57e16e6:/# df -h + 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. + + $ 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. + + $ 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 +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 +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. + + $ 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. + + $ 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. + + $ 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. + + $ 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. + +Regardless of the order of these three flags, the `--env-file` +are processed first, and then `-e` +.literal}/`--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 `#` + +An example of a file passed with `--env-file` + + $ cat ./env.list + TEST_FOO=BAR + + # this is a comment + TEST_APP_DEST_HOST=10.10.0.127 + TEST_APP_DEST_PORT=8888 + + # pass through this variable from the caller + TEST_PASSTHROUGH + $ sudo TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env + HOME=/ + PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + HOSTNAME=5198e0745561 + TEST_FOO=BAR + TEST_APP_DEST_HOST=10.10.0.127 + TEST_APP_DEST_PORT=8888 + TEST_PASSTHROUGH=howdy + + $ sudo docker run --name console -t -i ubuntu bash + +This will create and run a new container with the container name being +`console`. + + $ 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. + + $ 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 `-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. + + $ 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. + + $ 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. + + $ 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 +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. + +#### A complete example + + $ sudo docker run -d --name static static-web-files sh + $ sudo docker run -d --expose=8098 --name riak riakserver + $ sudo docker run -d -m 100m -e DEVELOPMENT=1 -e BRANCH=example-code -v $(pwd):/app/bin:ro --name app appserver + $ sudo docker run -d -p 1443:443 --dns=dns.dev.org --dns-search=dev.org -v /var/log/httpd --volumes-from static --link riak --link app -h www.sven.dev.org --name web webserver + $ sudo docker run -t -i --rm --volumes-from web -w /var/log/httpd busybox tail -f access.log + +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. + +## `save` + + 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 + +Produces a tarred repository to the standard output stream. Contains all +parent layers, and all tags + versions, or specified repo:tag. + +It is used to create a backup that can then be used with +`docker load` + + $ sudo docker save busybox > busybox.tar + $ ls -sh b.tar + 2.7M b.tar + $ sudo docker save --output busybox.tar busybox + $ ls -sh b.tar + 2.7M b.tar + $ sudo docker save -o fedora-all.tar fedora + $ sudo docker save -o fedora-latest.tar fedora:latest + +## `search` + + 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 +more details on finding shared images from the commandline. + +## `start` + + 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` + + 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. + +The main process inside the container will receive SIGTERM, and after a +grace period, SIGKILL + +## `tag` + + Usage: docker tag [OPTIONS] IMAGE [REGISTRYHOST/][USERNAME/]NAME[:TAG] + + Tag an image into a repository + + -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). + +## `top` + + Usage: docker top CONTAINER [ps OPTIONS] + + Lookup the running processes of a container + +## `version` + +Show the version of the Docker client, daemon, and latest released +version. + +## `wait` + + Usage: docker wait [OPTIONS] NAME + + Block until a container stops, then print its exit code. diff --git a/docs/sources/reference/run.md b/docs/sources/reference/run.md new file mode 100644 index 0000000000..6afc130085 --- /dev/null +++ b/docs/sources/reference/run.md @@ -0,0 +1,422 @@ +page_title: Docker Run Reference +page_description: Configure containers at runtime +page_keywords: docker, run, configure, runtime + +# [Docker Run Reference](#id2) + +**Docker runs processes in isolated containers**. When an operator +executes `docker run`, she starts a process with its +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 +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) + +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). + +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 + +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) + +Only the operator (the person executing `docker run` +.literal}) 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 + Memory](#runtime-constraints-on-cpu-and-memory) +- [Runtime Privilege and LXC + Configuration](#runtime-privilege-and-lxc-configuration) + +### [Detached vs Foreground](#id2) + +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 +default foreground mode: + + -d=false: Detached mode: Run container in the background, print new container id + +#### [Detached (-d)](#id3) + +In detached mode (`-d=true` or just `-d` +.literal}), 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 +container in the detached mode, then you cannot use the `--rm` +option. + +#### [Foreground](#id4) + +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: + + 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. + +### [Container Identification](#id5) + +#### [Name (–name)](#id6) + +The operator can identify a container in three ways: + +- UUID long identifier + ("f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778") +- UUID short identifier ("f78375b1c487") +- 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 +the daemon will also generate a random string name too. The name can +become a handy way to add meaning to a container since you can use this +name when defining +[*links*](../../use/working_with_links_names/#working-with-links-names) +(or any other place you need to identify a container). This works for +both background and foreground Docker containers. + +#### [PID Equivalent](#id7) + +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 +PID files): + + --cidfile="": Write the container ID to the file + +### [Network Settings](#id8) + + -n=true : Enable networking for this container + --dns=[] : Set custom dns servers for the container + +By default, all containers have networking enabled and they can make any +outgoing connections. The operator can completely disable networking +with `docker run -n` which disables all incoming and +outgoing networking. In cases like this, you would perform I/O through +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) + +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 +**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) + +The operator can also adjust the performance parameters of the +container: + + -m="": Memory limit (format: , where unit = b, k, m or g) + -c=0 : CPU shares (relative weight) + +The operator can constrain the memory available to a container easily +with `docker run -m`. If the host supports swap +memory, then the `-m` memory setting can be larger +than physical RAM. + +Similarly the operator can increase the priority of this container with +the `-c` option. By default, all containers run at +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) + + --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" + +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)). + +When the operator executes `docker run --privileged` +.literal}, 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/). + +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 + +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. + +- [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) + +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`. + +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="": Overwrite the default entrypoint set by the image + +The ENTRYPOINT of an image is similar to a `COMMAND` +because it specifies what executable to run when the container starts, +but it is (purposely) more difficult to override. The +`ENTRYPOINT` gives a container its default nature or +behavior, so that when you set an `ENTRYPOINT` you +can run the container *as if it were that binary*, complete with default +options, and you can pass in more options via the `COMMAND` +.literal}. But, sometimes an operator may want to run something else +inside the container, so you can override the default +`ENTRYPOINT` at runtime by using a string to specify +the new `ENTRYPOINT`. Here is an example of how to +run a shell in a container that has been set up to automatically run +something else (like `/usr/bin/redis-server`): + + docker run -i -t --entrypoint /bin/bash example/redis + +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) + +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 + -P=false : Publish all exposed ports to the host interfaces + -p=[] : Publish a container's port to the host (format: + ip:hostPort:containerPort | ip::containerPort | + hostPort:containerPort) + (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. + +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 `--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) + +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` +.literal}: + + $ docker run -e "deep=purple" --rm ubuntu /bin/bash -c export + declare -x HOME="/" + declare -x HOSTNAME="85bc26a0e200" + declare -x OLDPWD + declare -x PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + declare -x PWD="/" + declare -x SHLVL="1" + declare -x container="lxc" + declare -x deep="purple" + +Similarly the operator can set the **hostname** with `-h` +.literal}. + +`--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 + 4241164edf6f5aca5b0e9e4c9eccd899b0b8080c64c0cd26efe02166c73208f3 + + # The redis-name container exposed port 6379 + $ docker ps + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 4241164edf6f dockerfiles/redis:latest /redis-stable/src/re 5 seconds ago Up 4 seconds 6379/tcp redis-name + + # Note that there are no public ports exposed since we didn't use -p or -P + $ 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 +with `--link`. Choose an alias that will form a +valid environment variable! + + $ docker run --rm --link redis-name:redis_alias --entrypoint /bin/bash dockerfiles/redis -c export + declare -x HOME="/" + declare -x HOSTNAME="acda7f7b1cdc" + declare -x OLDPWD + declare -x PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + declare -x PWD="/" + declare -x REDIS_ALIAS_NAME="/distracted_wright/redis" + declare -x REDIS_ALIAS_PORT="tcp://172.17.0.32:6379" + declare -x REDIS_ALIAS_PORT_6379_TCP="tcp://172.17.0.32:6379" + declare -x REDIS_ALIAS_PORT_6379_TCP_ADDR="172.17.0.32" + declare -x REDIS_ALIAS_PORT_6379_TCP_PORT="6379" + declare -x REDIS_ALIAS_PORT_6379_TCP_PROTO="tcp" + declare -x SHLVL="1" + declare -x container="lxc" + +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) + + -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). + +### [USER](#id17) + +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) + +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