run.rst 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353
  1. :title: Docker Run Reference
  2. :description: Configure containers at runtime
  3. :keywords: docker, run, configure, runtime
  4. .. _run_docker:
  5. ====================
  6. Docker Run Reference
  7. ====================
  8. **Docker runs processes in isolated containers**. When an operator
  9. executes ``docker run``, she starts a process with its own file
  10. system, its own networking, and its own isolated process tree. The
  11. :ref:`image_def` which starts the process may define defaults related
  12. to the binary to run, the networking to expose, and more, but ``docker
  13. run`` gives final control to the operator who starts the container
  14. from the image. That's the main reason :ref:`cli_run` has more options
  15. than any other ``docker`` command.
  16. Every one of the :ref:`example_list` shows running containers, and so
  17. here we try to give more in-depth guidance.
  18. .. contents:: Table of Contents
  19. .. _run_running:
  20. General Form
  21. ============
  22. As you've seen in the :ref:`example_list`, the basic `run` command
  23. takes this form::
  24. docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...]
  25. To learn how to interpret the types of ``[OPTIONS]``, see
  26. :ref:`cli_options`.
  27. The list of ``[OPTIONS]`` breaks down into two groups:
  28. * options that define the runtime behavior or environment, and
  29. * options that override image defaults.
  30. Since image defaults usually get set in :ref:`Dockerfiles
  31. <dockerbuilder>` (though they could also be set at :ref:`cli_commit`
  32. time too), we will group the runtime options here by their related
  33. Dockerfile commands so that it is easier to see how to override image
  34. defaults and set new behavior.
  35. We'll start, though, with the options that are unique to ``docker
  36. run``, the options which define the runtime behavior or the container
  37. environment.
  38. .. note:: The runtime operator always has final control over the
  39. behavior of a Docker container.
  40. Detached or Foreground
  41. ======================
  42. When starting a Docker container, you must first decide if you want to
  43. run the container in the background in a "detached" mode or in the
  44. default foreground mode::
  45. -d=false: Detached mode: Run container in the background, print new container id
  46. Detached (-d)
  47. .............
  48. In detached mode (``-d=true`` or just ``-d``), all IO should be done
  49. through network connections or shared volumes because the container is
  50. no longer listening to the commandline where you executed ``docker
  51. run``. You can reattach to a detached container with ``docker``
  52. :ref:`cli_attach`. If you choose to run a container in the detached
  53. mode, then you cannot use the ``-rm`` option.
  54. Foreground
  55. ..........
  56. In foreground mode (the default when ``-d`` is not specified),
  57. ``docker run`` can start the process in the container and attach the
  58. console to the process's standard input, output, and standard
  59. error. It can even pretend to be a TTY (this is what most commandline
  60. executables expect) and pass along signals. All of that is
  61. configurable::
  62. -a=[] : Attach to stdin, stdout and/or stderr
  63. -t=false : Allocate a pseudo-tty
  64. -sig-proxy=true: Proxify all received signal to the process (even in non-tty mode)
  65. -i=false : Keep stdin open even if not attached
  66. If you do not specify ``-a`` then Docker will `attach everything
  67. (stdin,stdout,stderr)
  68. <https://github.com/dotcloud/docker/blob/master/commands.go#L1797>`_. You
  69. can specify which of the three standard streams (stdin, stdout,
  70. stderr) you'd like to connect between your instead, as in::
  71. docker run -a stdin -a stdout -i -t ubuntu /bin/bash
  72. For interactive processes (like a shell) you will typically want a tty
  73. as well as persistent standard in, so you'll use ``-i -t`` together in
  74. most interactive cases.
  75. Clean Up (-rm)
  76. --------------
  77. By default a container's file system persists even after the container
  78. exits. This makes debugging a lot easier (since you can inspect the
  79. final state) and you retain all your data by default. But if you are
  80. running short-term **foreground** processes, these container file
  81. systems can really pile up. If instead you'd like Docker to
  82. **automatically clean up the container and remove the file system when
  83. the container exits**, you can add the ``-rm`` flag::
  84. -rm=false: Automatically remove the container when it exits (incompatible with -d)
  85. Name (-name)
  86. ============
  87. The operator can identify a container in three ways:
  88. * UUID long identifier ("f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778")
  89. * UUID short identifier ("f78375b1c487")
  90. * name ("evil_ptolemy")
  91. The UUID identifiers come from the Docker daemon, and if you do not
  92. assign a name to the container with ``-name`` then the daemon will
  93. also generate a random string name too. The name can become a handy
  94. way to add meaning to a container since you can use this name when
  95. defining :ref:`links <working_with_links_names>` (or any other place
  96. you need to identify a container). This works for both background and
  97. foreground Docker containers.
  98. PID Equivalent
  99. ==============
  100. And finally, to help with automation, you can have Docker write the
  101. container id out to a file of your choosing. This is similar to how
  102. some programs might write out their process ID to a file (you've seen
  103. them as .pid files)::
  104. -cidfile="": Write the container ID to the file
  105. Overriding Dockerfile Image Defaults
  106. ====================================
  107. When a developer builds an image from a :ref:`Dockerfile
  108. <dockerbuilder>` or when she commits it, the developer can set a
  109. number of default parameters that take effect when the image starts up
  110. as a container.
  111. Four of the Dockerfile commands cannot be overridden at runtime:
  112. ``FROM, MAINTAINER, RUN``, and ``ADD``. Everything else has a
  113. corresponding override in ``docker run``. We'll go through what the
  114. developer might have set in each Dockerfile instruction and how the
  115. operator can override that setting.
  116. CMD
  117. ...
  118. Remember the optional ``COMMAND`` in the Docker commandline::
  119. docker run [OPTIONS] IMAGE[:TAG] [COMMAND] [ARG...]
  120. This command is optional because the person who created the ``IMAGE``
  121. may have already provided a default ``COMMAND`` using the Dockerfile
  122. ``CMD``. As the operator (the person running a container from the
  123. image), you can override that ``CMD`` just by specifying a new
  124. ``COMMAND``.
  125. If the image also specifies an ``ENTRYPOINT`` then the ``CMD`` or
  126. ``COMMAND`` get appended as arguments to the ``ENTRYPOINT``.
  127. ENTRYPOINT
  128. ..........
  129. ::
  130. -entrypoint="": Overwrite the default entrypoint set by the image
  131. The ENTRYPOINT of an image is similar to a COMMAND because it
  132. specifies what executable to run when the container starts, but it is
  133. (purposely) more difficult to override. The ENTRYPOINT gives a
  134. container its default nature or behavior, so that when you set an
  135. ENTRYPOINT you can run the container *as if it were that binary*,
  136. complete with default options, and you can pass in more options via
  137. the COMMAND. But, sometimes an operator may want to run something else
  138. inside the container, so you can override the default ENTRYPOINT at
  139. runtime by using a string to specify the new ENTRYPOINT. Here is an
  140. example of how to run a shell in a container that has been set up to
  141. automatically run something else (like ``/usr/bin/redis-server``)::
  142. docker run -i -t -entrypoint /bin/bash example/redis
  143. or two examples of how to pass more parameters to that ENTRYPOINT::
  144. docker run -i -t -entrypoint /bin/bash example/redis -c ls -l
  145. docker run -i -t -entrypoint /usr/bin/redis-cli example/redis --help
  146. EXPOSE (``run`` Networking Options)
  147. ...................................
  148. The *Dockerfile* doesn't give much control over networking, only
  149. providing the EXPOSE instruction to give a hint to the operator about
  150. what incoming ports might provide services. At runtime, however,
  151. Docker provides a number of ``run`` options related to networking::
  152. -n=true : Enable networking for this container
  153. -dns=[] : Set custom dns servers for the container
  154. -expose=[]: Expose a port from the container
  155. without publishing it to your host
  156. -P=false : Publish all exposed ports to the host interfaces
  157. -p=[] : Publish a container's port to the host (format:
  158. ip:hostPort:containerPort | ip::containerPort |
  159. hostPort:containerPort)
  160. (use 'docker port' to see the actual mapping)
  161. -link="" : Add link to another container (name:alias)
  162. By default, all containers have networking enabled and they can make
  163. any outgoing connections. The operator can completely disable
  164. networking with ``run -n`` which disables all incoming and outgoing
  165. networking. In cases like this, you would perform IO through files or
  166. stdin/stdout only.
  167. Your container will use the same DNS servers as the host by default,
  168. but you can override this with ``-dns``.
  169. As mentioned previously, ``EXPOSE`` (and ``-expose``) make a port
  170. available **in** a container for incoming connections. The port number
  171. on the inside of the container (where the service listens) does not
  172. need to be the same number as the port exposed on the outside of the
  173. container (where clients connect), so inside the container you might
  174. have an HTTP service listening on port 80 (and so you ``EXPOSE 80`` in
  175. the Dockerfile), but outside the container the port might be 42800.
  176. To help a new client container reach the server container's internal
  177. port operator ``-expose'd`` by the operator or ``EXPOSE'd`` by the
  178. developer, the operator has three choices: start the server container
  179. with ``-P`` or ``-p,`` or start the client container with ``-link``.
  180. If the operator uses ``-P`` or ``-p`` then Docker will make the
  181. exposed port accessible on the host and the ports will be available to
  182. any client that can reach the host. To find the map between the host
  183. ports and the exposed ports, use ``docker port``)
  184. If the operator uses ``-link`` when starting the new client container,
  185. then the client container can access the exposed port via a private
  186. networking interface. Docker will set some environment variables in
  187. the client container to help indicate which interface and port to use.
  188. ENV (Environment Variables)
  189. ...........................
  190. The operator can **set any environment variable** in the container by
  191. using one or more ``-e``, even overriding those already defined by the
  192. developer with a Dockefile ``ENV``::
  193. $ docker run -e "deep=purple" -rm ubuntu /bin/bash -c export
  194. declare -x HOME="/"
  195. declare -x HOSTNAME="85bc26a0e200"
  196. declare -x OLDPWD
  197. declare -x PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
  198. declare -x PWD="/"
  199. declare -x SHLVL="1"
  200. declare -x container="lxc"
  201. declare -x deep="purple"
  202. Similarly the operator can set the **hostname** with ``-h``.
  203. ``-link name:alias`` also sets environment variables, using the
  204. *alias* string to define environment variables within the container
  205. that give the IP and PORT information for connecting to the service
  206. container. Let's imagine we have a container running Redis::
  207. # Start the service container, named redis-name
  208. $ docker run -d -name redis-name dockerfiles/redis
  209. 4241164edf6f5aca5b0e9e4c9eccd899b0b8080c64c0cd26efe02166c73208f3
  210. # The redis-name container exposed port 6379
  211. $ docker ps
  212. CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
  213. 4241164edf6f dockerfiles/redis:latest /redis-stable/src/re 5 seconds ago Up 4 seconds 6379/tcp redis-name
  214. # Note that there are no public ports exposed since we didn't use -p or -P
  215. $ docker port 4241164edf6f 6379
  216. 2014/01/25 00:55:38 Error: No public port '6379' published for 4241164edf6f
  217. Yet we can get information about the redis container's exposed ports with ``-link``. Choose an alias that will form a valid environment variable!
  218. ::
  219. $ docker run -rm -link redis-name:redis_alias -entrypoint /bin/bash dockerfiles/redis -c export
  220. declare -x HOME="/"
  221. declare -x HOSTNAME="acda7f7b1cdc"
  222. declare -x OLDPWD
  223. declare -x PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
  224. declare -x PWD="/"
  225. declare -x REDIS_ALIAS_NAME="/distracted_wright/redis"
  226. declare -x REDIS_ALIAS_PORT="tcp://172.17.0.32:6379"
  227. declare -x REDIS_ALIAS_PORT_6379_TCP="tcp://172.17.0.32:6379"
  228. declare -x REDIS_ALIAS_PORT_6379_TCP_ADDR="172.17.0.32"
  229. declare -x REDIS_ALIAS_PORT_6379_TCP_PORT="6379"
  230. declare -x REDIS_ALIAS_PORT_6379_TCP_PROTO="tcp"
  231. declare -x SHLVL="1"
  232. declare -x container="lxc"
  233. And we can use that information to connect from another container as a client::
  234. $ 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'
  235. 172.17.0.32:6379>
  236. VOLUME (Shared Filesystems)
  237. ...........................
  238. ::
  239. -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro].
  240. If "container-dir" is missing, then docker creates a new volume.
  241. -volumes-from="": Mount all volumes from the given container(s)
  242. The volumes commands are complex enough to have their own
  243. documentation in section :ref:`volume_def`. A developer can define one
  244. or more VOLUMEs associated with an image, but only the operator can
  245. give access from one container to another (or from a container to a
  246. volume mounted on the host).
  247. USER
  248. ....
  249. ::
  250. -u="": Username or UID
  251. WORKDIR
  252. .......
  253. ::
  254. -w="": Working directory inside the container
  255. Performance
  256. ===========
  257. The operator can also adjust the performance parameters of the container::
  258. -c=0 : CPU shares (relative weight)
  259. -m="": Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
  260. -lxc-conf=[]: Add custom lxc options -lxc-conf="lxc.cgroup.cpuset.cpus = 0,1"
  261. -privileged=false: Give extended privileges to this container