diff --git a/docs/sources/reference/builder.rst b/docs/sources/reference/builder.rst new file mode 100644 index 0000000000..e61db62689 --- /dev/null +++ b/docs/sources/reference/builder.rst @@ -0,0 +1,456 @@ +:title: Build Images (Dockerfile Reference) +:description: Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image. +:keywords: builder, docker, Dockerfile, automation, image creation + +.. _dockerbuilder: + +=================================== +Build Images (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. + +.. contents:: Table of Contents + +.. _dockerfile_usage: + +1. Usage +======== + +To :ref:`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``: + +.. code-block:: bash + + $ 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 +:ref:`image_push`. + +.. _dockerfile_format: + +2. Format +========= + +The Dockerfile format is quite simple: + +:: + + # 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 +:ref:`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' + +.. _dockerfile_instructions: + +3. Instructions +=============== + +Here is the set of instructions you can use in a ``Dockerfile`` for +building images. + +.. _dockerfile_from: + +3.1 FROM +-------- + + ``FROM `` + +Or + + ``FROM :`` + +The ``FROM`` instruction sets the :ref:`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 +:ref:`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. + +.. _dockerfile_maintainer: + +3.2 MAINTAINER +-------------- + + ``MAINTAINER `` + +The ``MAINTAINER`` instruction allows you to set the *Author* field of +the generated images. + +.. _dockerfile_run: + +3.3 RUN +------- + + ``RUN `` + +The ``RUN`` instruction will execute any commands on 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. + +Known Issues (RUN) +.................. + +* :issue:`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` Locale will not be set automatically. + +.. _dockerfile_cmd: + +3.4 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. This is +functionally equivalent to running ``docker commit -run '{"Cmd": +}'`` outside the builder. + +If you use the *shell* form of the CMD, then the ```` will +execute in ``/bin/sh -c``: + +.. code-block:: bash + + 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: + +.. code-block:: bash + + 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 :ref:`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. + +.. _dockerfile_expose: + +3.5 EXPOSE +---------- + + ``EXPOSE [...]`` + +The ``EXPOSE`` instruction exposes ports for use within links. This is +functionally equivalent to running ``docker commit -run '{"PortSpecs": +["", ""]}'`` outside the builder. Refer to +:ref:`port_redirection` for detailed information. + +.. _dockerfile_env: + +3.6 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 ``=`` + +.. note:: + The environment variables will persist when a container is run + from the resulting image. + +.. _dockerfile_add: + +3.7 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 path at which the source will be copied in 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``), 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. + +.. _dockerfile_entrypoint: + +3.8 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``. 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``: + +.. code-block:: bash + + 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: + +.. code-block:: bash + + FROM ubuntu + CMD ["-l", "-"] + ENTRYPOINT ["/usr/bin/wc"] + +.. _dockerfile_volume: + +3.9 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 :ref:`volume_def` documentation. + +.. _dockerfile_user: + +3.10 USER +--------- + + ``USER daemon`` + +The ``USER`` instruction sets the username or UID to use when running +the image. + +.. _dockerfile_workdir: + +3.11 WORKDIR +------------ + + ``WORKDIR /path/to/workdir`` + +The ``WORKDIR`` instruction sets the working directory in which +the command given by ``CMD`` is executed. + +.. _dockerfile_examples: + +4. Dockerfile Examples +====================== + +.. code-block:: bash + + # 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 + +.. code-block:: bash + + # 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"] + +.. code-block:: bash + + # 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.rst b/docs/sources/reference/commandline/cli.rst new file mode 100644 index 0000000000..67c8b06189 --- /dev/null +++ b/docs/sources/reference/commandline/cli.rst @@ -0,0 +1,1258 @@ +:title: Command Line Interface +:description: Docker's CLI command description and usage +:keywords: Docker, Docker documentation, CLI, command line + +.. _cli: + +Command Line Help +----------------- + +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=[0.0.0.0], port=[4243] or path=[/var/run/docker.sock] is omitted, default values are used. + + A self-sufficient runtime for linux containers. + + ... + +.. _cli_daemon: + +``daemon`` +---------- + +:: + + Usage of docker: + -D=false: Enable debug mode + -H=[unix:///var/run/docker.sock]: tcp://[host[:port]] to bind or unix://[/path/to/socket] to use. When host=[0.0.0.0], port=[4243] or path=[/var/run/docker.sock] is omitted, default values are used. + -api-enable-cors=false: Enable CORS headers in the remote API + -b="": Attach containers to a pre-existing network bridge; use 'none' to disable container networking + -bip="": Use the provided CIDR notation address for the dynamically created bridge (docker0); Mutually exclusive of -b + -d=false: Enable daemon mode + -dns="": Force docker to use specific DNS servers + -g="/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 + -iptables=true: Disable docker's addition of iptables rules + -mtu=1500: Set the containers network mtu + -p="/var/run/docker.pid": Path to use for daemon PID file + -r=true: Restart previously running containers + -s="": Force the docker runtime to use a specific storage driver + -v=false: Print version information and quit + +The Docker daemon is the persistent process that manages containers. Docker uses the same binary for both the +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 run the daemon with debug output, use ``docker -d -D``. + +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 + + +.. _cli_attach: + +``attach`` +---------- + +:: + + Usage: docker attach CONTAINER + + Attach to a running container. + + -nostdin=false: Do not attach stdin + -sig-proxy=true: Proxify all received signal to the process (even in non-tty mode) + +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``. + +.. _cli_attach_examples: + +Examples: +~~~~~~~~~ + +.. code-block:: bash + + $ 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 + +.. _cli_build: + +``build`` +--------- + +:: + + Usage: docker build [OPTIONS] PATH | URL | - + Build a new container image from the source code at PATH + -t="": Repository name (and optionally a tag) to be applied + to the resulting image in case of success. + -q=false: Suppress verbose build output. + -no-cache: Do not use the cache when building the image. + -rm: Remove intermediate containers after a successful build + +The files at ``PATH`` or ``URL`` are called the "context" of the build. The +build process may refer to any of the files in the context, for example when +using an :ref:`ADD ` instruction. When a single ``Dockerfile`` +is given as ``URL``, then no context is set. When a Git repository is set as +``URL``, then the repository is used as the context + +.. _cli_build_examples: + +.. seealso:: :ref:`dockerbuilder`. + +Examples: +~~~~~~~~~ + +.. code-block:: bash + + $ 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 + +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 +:ref:`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 "Uploading context" +message. + + +.. code-block:: bash + + $ 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`` + + +.. code-block:: bash + + $ 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. + +.. code-block:: bash + + $ 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. + + +.. _cli_commit: + +``commit`` +---------- + +:: + + Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]] + + Create a new image from a container's changes + + -m="": Commit message + -author="": Author (eg. "John Hannibal Smith " + -run="": Configuration to be applied when the image is launched with `docker run`. + (ex: -run='{"Cmd": ["cat", "/world"], "PortSpecs": ["22"]}') + +.. _cli_commit_examples: + +Commit an existing container +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + $ 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 + +Change the command that a container runs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sometimes you have an application container running just a service and you need +to make a quick change and then change it back. + +In this example, we run a container with ``ls`` and then change the image to +run ``ls /etc``. + +.. code-block:: bash + + $ docker run -t -name test ubuntu ls + bin boot dev etc home lib lib64 media mnt opt proc root run sbin selinux srv sys tmp usr var + $ docker commit -run='{"Cmd": ["ls","/etc"]}' test test2 + 933d16de9e70005304c1717b5c6f2f39d6fd50752834c6f34a155c70790011eb + $ docker run -t test2 + adduser.conf gshadow login.defs rc0.d + alternatives gshadow- logrotate.d rc1.d + apt host.conf lsb-base rc2.d + ... + +Full -run example +................. + +The ``-run`` JSON hash changes the ``Config`` section when running ``docker inspect CONTAINERID`` +or ``config`` when running ``docker inspect IMAGEID``. + +(Multiline is okay within a single quote ``'``) + +.. code-block:: bash + + $ sudo docker commit -run=' + { + "Entrypoint" : null, + "Privileged" : false, + "User" : "", + "VolumesFrom" : "", + "Cmd" : ["cat", "-e", "/etc/resolv.conf"], + "Dns" : ["8.8.8.8", "8.8.4.4"], + "MemorySwap" : 0, + "AttachStdin" : false, + "AttachStderr" : false, + "CpuShares" : 0, + "OpenStdin" : false, + "Volumes" : null, + "Hostname" : "122612f45831", + "PortSpecs" : ["22", "80", "443"], + "Image" : "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", + "Tty" : false, + "Env" : [ + "HOME=/", + "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + ], + "StdinOnce" : false, + "Domainname" : "", + "WorkingDir" : "/", + "NetworkDisabled" : false, + "Memory" : 0, + "AttachStdout" : false + }' $CONTAINER_ID + +.. _cli_cp: + +``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. + +.. code-block:: bash + + $ sudo docker cp 7bb0e258aefe:/etc/debian_version . + $ sudo docker cp blue_frog:/etc/hosts . + +.. _cli_diff: + +``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: + +.. code-block:: bash + + $ 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 + .... + +.. _cli_events: + +``events`` +---------- + +:: + + Usage: docker events + + Get real time events from the server + + -since="": Show previously created events and then stream. + (either seconds since epoch, or date string as below) + +.. _cli_events_example: + +Examples +~~~~~~~~ + +You'll need two shells for this example. + +Shell 1: Listening for events +............................. + +.. code-block:: bash + + $ sudo docker events + +Shell 2: Start and Stop a Container +................................... + +.. code-block:: bash + + $ sudo docker start 4386fb97867d + $ sudo docker stop 4386fb97867d + +Shell 1: (Again .. now showing events) +...................................... + +.. code-block:: bash + + [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 +............................................. + +.. code-block:: bash + + $ 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 + +.. _cli_export: + +``export`` +---------- + +:: + + Usage: docker export CONTAINER + + Export the contents of a filesystem as a tar archive to STDOUT + +For example: + +.. code-block:: bash + + $ sudo docker export red_panda > latest.tar + +.. _cli_history: + +``history`` +----------- + +:: + + Usage: docker history [OPTIONS] IMAGE + + Show the history of an image + + -notrunc=false: Don't truncate output + -q=false: only show numeric IDs + +To see how the ``docker:latest`` image was built: + +.. code-block:: bash + + $ docker history docker + ID CREATED CREATED BY + docker:latest 19 hours ago /bin/sh -c #(nop) ADD . in /go/src/github.com/dotcloud/docker + cf5f2467662d 2 weeks ago /bin/sh -c #(nop) ENTRYPOINT ["hack/dind"] + 3538fbe372bf 2 weeks ago /bin/sh -c #(nop) WORKDIR /go/src/github.com/dotcloud/docker + 7450f65072e5 2 weeks ago /bin/sh -c #(nop) VOLUME /var/lib/docker + b79d62b97328 2 weeks ago /bin/sh -c apt-get install -y -q lxc + 36714852a550 2 weeks ago /bin/sh -c apt-get install -y -q iptables + 8c4c706df1d6 2 weeks ago /bin/sh -c /bin/echo -e '[default]\naccess_key=$AWS_ACCESS_KEY\nsecret_key=$AWS_SECRET_KEYn' > /.s3cfg + b89989433c48 2 weeks ago /bin/sh -c pip install python-magic + a23e640d85b5 2 weeks ago /bin/sh -c pip install s3cmd + 41f54fec7e79 2 weeks ago /bin/sh -c apt-get install -y -q python-pip + d9bc04add907 2 weeks ago /bin/sh -c apt-get install -y -q reprepro dpkg-sig + e74f4760fa70 2 weeks ago /bin/sh -c gem install --no-rdoc --no-ri fpm + 1e43224726eb 2 weeks ago /bin/sh -c apt-get install -y -q ruby1.9.3 rubygems libffi-dev + 460953ae9d7f 2 weeks ago /bin/sh -c #(nop) ENV GOPATH=/go:/go/src/github.com/dotcloud/docker/vendor + 8b63eb1d666b 2 weeks ago /bin/sh -c #(nop) ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/goroot/bin + 3087f3bcedf2 2 weeks ago /bin/sh -c #(nop) ENV GOROOT=/goroot + 635840d198e5 2 weeks ago /bin/sh -c cd /goroot/src && ./make.bash + 439f4a0592ba 2 weeks ago /bin/sh -c curl -s https://go.googlecode.com/files/go1.1.2.src.tar.gz | tar -v -C / -xz && mv /go /goroot + 13967ed36e93 2 weeks ago /bin/sh -c #(nop) ENV CGO_ENABLED=0 + bf7424458437 2 weeks ago /bin/sh -c apt-get install -y -q build-essential + a89ec997c3bf 2 weeks ago /bin/sh -c apt-get install -y -q mercurial + b9f165c6e749 2 weeks ago /bin/sh -c apt-get install -y -q git + 17a64374afa7 2 weeks ago /bin/sh -c apt-get install -y -q curl + d5e85dc5b1d8 2 weeks ago /bin/sh -c apt-get update + 13e642467c11 2 weeks ago /bin/sh -c echo 'deb http://archive.ubuntu.com/ubuntu precise main universe' > /etc/apt/sources.list + ae6dde92a94e 2 weeks ago /bin/sh -c #(nop) MAINTAINER Solomon Hykes + ubuntu:12.04 6 months ago + +.. _cli_images: + +``images`` +---------- + +:: + + Usage: docker images [OPTIONS] [NAME] + + List images + + -a=false: show all images (by default filter out the intermediate images used to build) + -notrunc=false: Don't truncate output + -q=false: only show numeric IDs + -tree=false: output graph in tree format + -viz=false: output graph in graphviz format + +Listing the most recently created images +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + $ 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + $ sudo docker images -notrunc | 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 + +Displaying images visually +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + $ sudo docker images -viz | dot -Tpng -o docker.png + +.. image:: docker_images.gif + :alt: Example inheritance graph of Docker images. + + +Displaying image hierarchy +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + $ sudo docker images -tree + + ├─8dbd9e392a96 Size: 131.5 MB (virtual 131.5 MB) Tags: ubuntu:12.04,ubuntu:latest,ubuntu:precise + └─27cf78414709 Size: 180.1 MB (virtual 180.1 MB) + └─b750fe79269d Size: 24.65 kB (virtual 180.1 MB) Tags: ubuntu:12.10,ubuntu:quantal + ├─f98de3b610d5 Size: 12.29 kB (virtual 180.1 MB) + │ └─7da80deb7dbf Size: 16.38 kB (virtual 180.1 MB) + │ └─65ed2fee0a34 Size: 20.66 kB (virtual 180.2 MB) + │ └─a2b9ea53dddc Size: 819.7 MB (virtual 999.8 MB) + │ └─a29b932eaba8 Size: 28.67 kB (virtual 999.9 MB) + │ └─e270a44f124d Size: 12.29 kB (virtual 999.9 MB) Tags: progrium/buildstep:latest + └─17e74ac162d8 Size: 53.93 kB (virtual 180.2 MB) + └─339a3f56b760 Size: 24.65 kB (virtual 180.2 MB) + └─904fcc40e34d Size: 96.7 MB (virtual 276.9 MB) + └─b1b0235328dd Size: 363.3 MB (virtual 640.2 MB) + └─7cb05d1acb3b Size: 20.48 kB (virtual 640.2 MB) + └─47bf6f34832d Size: 20.48 kB (virtual 640.2 MB) + └─f165104e82ed Size: 12.29 kB (virtual 640.2 MB) + └─d9cf85a47b7e Size: 1.911 MB (virtual 642.2 MB) + └─3ee562df86ca Size: 17.07 kB (virtual 642.2 MB) + └─b05fc2d00e4a Size: 24.96 kB (virtual 642.2 MB) + └─c96a99614930 Size: 12.29 kB (virtual 642.2 MB) + └─a6a357a48c49 Size: 12.29 kB (virtual 642.2 MB) Tags: ndj/mongodb:latest + +.. _cli_import: + +``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. + +At this time, the URL 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. + +.. code-block:: bash + + $ sudo docker import http://example.com/exampleimage.tgz + +Import from a local file +........................ + +Import to docker via pipe and *stdin*. + +.. code-block:: bash + + $ cat exampleimage.tgz | sudo docker import - exampleimagelocal:new + +Import from a local directory +............................. + +.. code-block:: bash + + $ sudo tar -c . | docker import - exampleimagedir + +Note the ``sudo`` in this example -- you must preserve the ownership of the +files (especially root ownership) during the archiving with tar. If you are not +root (or the sudo command) when you tar, then the ownerships might not get +preserved. + +.. _cli_info: + +``info`` +-------- + +:: + + Usage: docker info + + Display system-wide information. + +.. code-block:: bash + + $ 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 + + +.. _cli_insert: + +``insert`` +---------- + +:: + + Usage: docker insert IMAGE URL PATH + + Insert a file from URL in the IMAGE at PATH + +Use the specified ``IMAGE`` as the parent for a new image which adds a +:ref:`layer ` containing the new file. The ``insert`` command does +not modify the original image, and the new image has the contents of the parent +image, plus the new file. + + +Examples +~~~~~~~~ + +Insert file from GitHub +....................... + +.. code-block:: bash + + $ sudo docker insert 8283e18b24bc https://raw.github.com/metalivedev/django/master/postinstall /tmp/postinstall.sh + 06fd35556d7b + +.. _cli_inspect: + +``inspect`` +----------- + +:: + + Usage: docker inspect CONTAINER|IMAGE [CONTAINER|IMAGE...] + + Return low-level information on a container/image + + -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 `_ 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. + +.. code-block:: bash + + $ 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: + +.. code-block:: bash + + $ 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. + +.. code-block:: bash + + $ sudo docker inspect -format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID + +.. _cli_kill: + +``kill`` +-------- + +:: + + Usage: docker kill CONTAINER [CONTAINER...] + + Kill a running container (Send SIGKILL) + +The main process inside the container will be sent SIGKILL. + +Known Issues (kill) +~~~~~~~~~~~~~~~~~~~ + +* :issue:`197` indicates that ``docker kill`` may leave directories + behind and make it difficult to remove the container. + +.. _cli_load: + +``load`` +-------- + +:: + + Usage: docker load < repository.tar + + Loads a tarred repository from the standard input stream. + Restores both images and tags. + +.. _cli_login: + +``login`` +--------- + +:: + + Usage: docker login [OPTIONS] [SERVER] + + Register or Login to the docker registry server + + -e="": email + -p="": password + -u="": username + + If you want to login to a private registry you can + specify this by adding the server name. + + example: + docker login localhost:8080 + + +.. _cli_logs: + +``logs`` +-------- + +:: + + Usage: docker logs [OPTIONS] CONTAINER + + Fetch the logs of a container + +The ``docker logs`` command is a convenience which batch-retrieves whatever +logs are present at the time of execution. This does not guarantee execution +order when combined with a ``docker run`` (i.e. your run may not have generated +any logs at the time you execute ``docker logs``). + +The ``docker logs -f`` command combines ``docker logs`` and ``docker attach``: +it will first return all logs from the beginning and then continue streaming +new output from the container's stdout and stderr. + + +.. _cli_port: + +``port`` +-------- + +:: + + Usage: docker port [OPTIONS] CONTAINER PRIVATE_PORT + + Lookup the public-facing port which is NAT-ed to PRIVATE_PORT + + +.. _cli_ps: + +``ps`` +------ + +:: + + Usage: docker ps [OPTIONS] + + List containers + + -a=false: Show all containers. Only running containers are shown by default. + -notrunc=false: Don't truncate output + -q=false: Only display numeric IDs + +Running ``docker ps`` showing 2 linked containers. + +.. code-block:: bash + + $ 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 + +.. _cli_pull: + +``pull`` +-------- + +:: + + Usage: docker pull NAME + + Pull an image or a repository from the registry + + +.. _cli_push: + +``push`` +-------- + +:: + + Usage: docker push NAME + + Push an image or a repository to the registry + + +.. _cli_restart: + +``restart`` +----------- + +:: + + Usage: docker restart [OPTIONS] NAME + + Restart a running container + +.. _cli_rm: + +``rm`` +------ + +:: + + Usage: docker rm [OPTIONS] CONTAINER + + Remove one or more containers + -link="": Remove the link instead of the actual container + +Known Issues (rm) +~~~~~~~~~~~~~~~~~ + +* :issue:`197` indicates that ``docker kill`` may leave directories + behind and make it difficult to remove the container. + + +Examples: +~~~~~~~~~ + +.. code-block:: bash + + $ sudo docker rm /redis + /redis + + +This will remove the container referenced under the link ``/redis``. + + +.. code-block:: bash + + $ sudo docker rm -link /webapp/redis + /webapp/redis + + +This will remove the underlying link between ``/webapp`` and the ``/redis`` containers removing all +network communication. + +.. code-block:: bash + + $ 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. + +.. _cli_rmi: + +``rmi`` +------- + +:: + + Usage: docker rmi IMAGE [IMAGE...] + + Remove one or more images + +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. + +.. code-block:: bash + + $ 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 + + +.. _cli_run: + +``run`` +------- + +:: + + Usage: docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...] + + Run a command in a new container + + -a=map[]: Attach to stdin, stdout or stderr + -c=0: CPU shares (relative weight) + -cidfile="": Write the container ID to the file + -d=false: Detached mode: Run container in the background, print new container id + -e=[]: Set environment variables + -h="": Container host name + -i=false: Keep stdin open even if not attached + -privileged=false: Give extended privileges to this container + -m="": Memory limit (format: , where unit = b, k, m or g) + -n=true: Enable networking for this container + -p=[]: Map a network port to the container + -rm=false: Automatically remove the container when it exits (incompatible with -d) + -t=false: Allocate a pseudo-tty + -u="": Username or UID + -dns=[]: Set custom dns servers for the container + -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) + -entrypoint="": Overwrite the default entrypoint set by the image + -w="": Working directory inside the container + -lxc-conf=[]: 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=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``. + +The ``docker run`` command can be used in combination with ``docker commit`` to +:ref:`change the command that a container runs `. + +Known Issues (run -volumes-from) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* :issue:`2702`: "lxc-start: Permission denied - failed to mount" + could indicate a permissions problem with AppArmor. Please see the + issue for a workaround. + +Examples: +~~~~~~~~~ + +.. code-block:: bash + + $ 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. + +.. code-block:: bash + + $ 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: + +.. code-block:: bash + + $ 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. + +.. code-block:: bash + + $ 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. + +.. code-block:: bash + + $ 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. + +.. code-block:: bash + + $ 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. :ref:`port_redirection` explains in detail how to manipulate ports +in Docker. + +.. code-block:: bash + + $ 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. :ref:`port_redirection` +explains in detail how to manipulate ports in Docker. + +.. code-block:: bash + + $ sudo docker run -name console -t -i ubuntu bash + +This will create and run a new container with the container name +being ``console``. + +.. code-block:: bash + + $ 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. + +.. code-block:: bash + + $ 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 seperated +list or by repetitions of the ``-volumes-from`` argument. The container +ID may be optionally suffixed with ``:ro`` or ``:rw`` to mount the volumes in +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. + +A complete example +.................. + +.. code-block:: bash + + $ 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 -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``, 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. + + +.. _cli_save: + +``save`` +--------- + +:: + + Usage: docker save image > repository.tar + + Streams a tarred repository to the standard output stream. + Contains all parent layers, and all tags + versions. + +.. _cli_search: + +``search`` +---------- + +:: + + Usage: docker search TERM + + Search the docker index for images + + -notrunc=false: Don't truncate output + -stars=0: Only displays with at least xxx stars + -trusted=false: Only show trusted builds + +.. _cli_start: + +``start`` +--------- + +:: + + Usage: docker start [OPTIONS] CONTAINER + + Start a stopped container + + -a=false: Attach container's stdout/stderr and forward all signals to the process + -i=false: Attach container's stdin + +.. _cli_stop: + +``stop`` +-------- + +:: + + Usage: docker stop [OPTIONS] CONTAINER [CONTAINER...] + + Stop a running container (Send SIGTERM, and then SIGKILL after grace period) + + -t=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 + +.. _cli_tag: + +``tag`` +------- + +:: + + Usage: docker tag [OPTIONS] IMAGE REPOSITORY[:TAG] + + Tag an image into a repository + + -f=false: Force + +.. _cli_top: + +``top`` +------- + +:: + + Usage: docker top CONTAINER [ps OPTIONS] + + Lookup the running processes of a container + +.. _cli_version: + +``version`` +----------- + +Show the version of the Docker client, daemon, and latest released version. + + +.. _cli_wait: + +``wait`` +-------- + +:: + + Usage: docker wait [OPTIONS] NAME + + Block until a container stops, then print its exit code. diff --git a/docs/sources/reference/commandline/docker_images.gif b/docs/sources/reference/commandline/docker_images.gif new file mode 100644 index 0000000000..5894ca270e Binary files /dev/null and b/docs/sources/reference/commandline/docker_images.gif differ diff --git a/docs/sources/reference/commandline/index.rst b/docs/sources/reference/commandline/index.rst new file mode 100644 index 0000000000..5536e1012e --- /dev/null +++ b/docs/sources/reference/commandline/index.rst @@ -0,0 +1,14 @@ +:title: Commands +:description: docker command line interface +:keywords: commands, command line, help, docker + + +Commands +======== + +Contents: + +.. toctree:: + :maxdepth: 1 + + cli diff --git a/docs/sources/reference/index.rst b/docs/sources/reference/index.rst new file mode 100644 index 0000000000..49099d5621 --- /dev/null +++ b/docs/sources/reference/index.rst @@ -0,0 +1,17 @@ +:title: Docker Reference Manual +:description: References +:keywords: docker, references, api, command line, commands + +.. _references: + +Reference Manual +================ + +Contents: + +.. toctree:: + :maxdepth: 1 + + commandline/index + builder + api/index