builder.rst 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193
  1. :title: Docker Builder
  2. :description: Docker Builder specifes a simple DSL which allows you to automate the steps you would normally manually take to create an image.
  3. :keywords: builder, docker, Docker Builder, automation, image creation
  4. ==============
  5. Docker Builder
  6. ==============
  7. .. contents:: Table of Contents
  8. Docker Builder specifes a simple DSL which allows you to automate the steps you
  9. would normally manually take to create an image. Docker Build will run your
  10. steps and commit them along the way, giving you a final image.
  11. 1. Usage
  12. ========
  13. To use Docker Builder, assemble the steps into a text file (commonly referred to
  14. as a Dockerfile) and supply this to `docker build` on STDIN, like so:
  15. ``docker build - < Dockerfile``
  16. Docker will run your steps one-by-one, committing the result if necessary,
  17. before finally outputting the ID of your new image.
  18. 2. Format
  19. =========
  20. The Dockerfile format is quite simple:
  21. ``instruction arguments``
  22. The Instruction is not case-sensitive, however convention is for them to be
  23. UPPERCASE in order to distinguish them from arguments more easily.
  24. Dockerfiles are evaluated in order, therefore the first instruction must be
  25. `FROM` in order to specify the base image from which you are building.
  26. Docker will ignore lines in Dockerfiles prefixed with "`#`", so you may add
  27. comment lines. A comment marker in the rest of the line will be treated as an
  28. argument.
  29. 2. Instructions
  30. ===============
  31. Docker builder comes with a set of instructions, described below.
  32. 2.1 FROM
  33. --------
  34. ``FROM <image>``
  35. The `FROM` instruction sets the base image for subsequent instructions. As such,
  36. a valid Dockerfile must have it as its first instruction.
  37. `FROM` can be included multiple times within a single Dockerfile in order to
  38. create multiple images. Simply make a note of the last image id output by the
  39. commit before each new `FROM` command.
  40. 2.2 MAINTAINER
  41. --------------
  42. ``MAINTAINER <name>``
  43. The `MAINTAINER` instruction allows you to set the Author field of the generated
  44. images.
  45. 2.3 RUN
  46. -------
  47. ``RUN <command>``
  48. The `RUN` instruction will execute any commands on the current image and commit
  49. the results. The resulting committed image will be used for the next step in the
  50. Dockerfile.
  51. Layering `RUN` instructions and generating commits conforms to the
  52. core concepts of Docker where commits are cheap and containers can be created
  53. from any point in an image's history, much like source control.
  54. 2.4 CMD
  55. -------
  56. ``CMD <command>``
  57. The `CMD` instruction sets the command to be executed when running the image.
  58. This is functionally equivalent to running
  59. `docker commit -run '{"Cmd": <command>}'` outside the builder.
  60. .. note::
  61. Don't confuse `RUN` with `CMD`. `RUN` actually runs a command and commits
  62. the result; `CMD` does not execute anything at build time, but specifies the
  63. intended command for the image.
  64. 2.5 EXPOSE
  65. ----------
  66. ``EXPOSE <port> [<port>...]``
  67. The `EXPOSE` instruction sets ports to be publicly exposed when running the
  68. image. This is functionally equivalent to running
  69. `docker commit -run '{"PortSpecs": ["<port>", "<port2>"]}'` outside the builder.
  70. 2.6 ENV
  71. -------
  72. ``ENV <key> <value>``
  73. The `ENV` instruction sets the environment variable `<key>` to the value
  74. `<value>`. This value will be passed to all future ``RUN`` instructions. This is
  75. functionally equivalent to prefixing the command with `<key>=<value>`
  76. .. note::
  77. The environment variables will persist when a container is run from the resulting image.
  78. 2.7 INSERT
  79. ----------
  80. ``INSERT <file url> <path>``
  81. The `INSERT` instruction will download the file from the given url to the given
  82. path within the image. It is similar to `RUN curl -o <path> <url>`, assuming
  83. curl was installed within the image.
  84. .. note::
  85. The path must include the file name.
  86. 2.8 ADD
  87. -------
  88. ``ADD <src> <dest>``
  89. The `ADD` instruction will insert the files from the `<src>` path of the context into `<dest>` path
  90. of the container.
  91. The context must be set in order to use this instruction. (see examples)
  92. 3. Dockerfile Examples
  93. ======================
  94. .. code-block:: bash
  95. # Nginx
  96. #
  97. # VERSION 0.0.1
  98. FROM ubuntu
  99. MAINTAINER Guillaume J. Charmes "guillaume@dotcloud.com"
  100. # make sure the package repository is up to date
  101. RUN echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > /etc/apt/sources.list
  102. RUN apt-get update
  103. RUN apt-get install -y inotify-tools nginx apache2 openssh-server
  104. INSERT https://raw.github.com/creack/docker-vps/master/nginx-wrapper.sh /usr/sbin/nginx-wrapper
  105. .. code-block:: bash
  106. # Firefox over VNC
  107. #
  108. # VERSION 0.3
  109. FROM ubuntu
  110. # make sure the package repository is up to date
  111. RUN echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > /etc/apt/sources.list
  112. RUN apt-get update
  113. # Install vnc, xvfb in order to create a 'fake' display and firefox
  114. RUN apt-get install -y x11vnc xvfb firefox
  115. RUN mkdir /.vnc
  116. # Setup a password
  117. RUN x11vnc -storepasswd 1234 ~/.vnc/passwd
  118. # Autostart firefox (might not be the best way, but it does the trick)
  119. RUN bash -c 'echo "firefox" >> /.bashrc'
  120. EXPOSE 5900
  121. CMD ["x11vnc", "-forever", "-usepw", "-create"]
  122. .. code-block:: bash
  123. # Multiple images example
  124. #
  125. # VERSION 0.1
  126. FROM ubuntu
  127. RUN echo foo > bar
  128. # Will output something like ===> 907ad6c2736f
  129. FROM ubuntu
  130. RUN echo moo > oink
  131. # Will output something like ===> 695d7793cbe4
  132. # You'll now have two images, 907ad6c2736f with /bar, and 695d7793cbe4 with
  133. # /oink.