docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #584 from boffbowsh/builder-documentation 

* Documentation: Updated Docker builder docs to clean up format and add new information and examples
This commit is contained in:
Ken Cochrane 2013-05-11 12:39:44 -07:00
parent dfbea4ad9f 9416574569
commit 908e4797a6
1 changed files with 95 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
docs/sources/builder/basics.rst
View File

@ -4,83 +4,120 @@ Docker Builder
.. contents:: Table of Contents .. contents:: Table of Contents
1. Format Docker Builder specifes a simple DSL which allows you to automate the steps you
would normally manually take to create an image. Docker Build will run your
steps and commit them along the way, giving you a final image.
1. Usage
========
To use Docker Builder, assemble the steps into a text file (commonly referred to
as a Dockerfile) and supply this to `docker build` on STDIN, like so:
``docker build < Dockerfile``
Docker will run your steps one-by-one, committing the result if necessary,
before finally outputting the ID of your new image.
2. Format
========= =========
The Docker builder format is quite simple: The Dockerfile format is quite simple:
``instruction arguments`` ``instruction arguments``
The first instruction must be `FROM` The Instruction is not case-sensitive, however convention is for them to be
UPPERCASE in order to distinguish them from arguments more easily.
All instruction are to be placed in a file named `Dockerfile` Dockerfiles are evaluated in order, therefore the first instruction must be
`FROM` in order to specify the base image from which you are building.
In order to place comments within a Dockerfile, simply prefix the line with "`#`" Docker will ignore lines in Dockerfiles prefixed with "`#`", so you may add
comment lines. A comment marker in the rest of the line will be treated as an
argument.
2. Instructions 2. Instructions
=============== ===============
Docker builder comes with a set of instructions: Docker builder comes with a set of instructions, described below.
1. FROM: Set from what image to build
2. RUN: Execute a command
3. INSERT: Insert a remote file (http) into the image
2.1 FROM 2.1 FROM
-------- --------
``FROM <image>`` ``FROM <image>``
The `FROM` instruction must be the first one in order for Builder to know from where to run commands. The `FROM` instruction sets the base image for subsequent instructions. As such,
a valid Dockerfile must have it as its first instruction.
`FROM` can also be used in order to build multiple images within a single Dockerfile `FROM` can be included 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.
2.2 MAINTAINER 2.2 MAINTAINER
-------------- --------------
``MAINTAINER <name>`` ``MAINTAINER <name>``
The `MAINTAINER` instruction allow you to set the Author field of the generated images. The `MAINTAINER` instruction allows you to set the Author field of the generated
This instruction is never automatically reset. images.
2.3 RUN 2.3 RUN
------- -------
``RUN <command>`` ``RUN <command>``
The `RUN` instruction is the main one, it allows you to execute any commands on the `FROM` image and to save the results. The `RUN` instruction will execute any commands on the current image and commit
You can use as many `RUN` as you want within a Dockerfile, the commands will be executed on the result of the previous command. 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.
2.4 CMD 2.4 CMD
------- -------
``CMD <command>`` ``CMD <command>``
The `CMD` instruction sets the command to be executed when running the image. The `CMD` instruction sets the command to be executed when running the image.
It is equivalent to do `docker commit -run '{"Cmd": <command>}'` outside the builder. This is functionally equivalent to running
`docker commit -run '{"Cmd": <command>}'` outside the builder.
.. note:: .. note::
Do not confuse `RUN` with `CMD`. `RUN` actually run a command and save the result, `CMD` does not execute anything. 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.
2.5 EXPOSE 2.5 EXPOSE
---------- ----------
``EXPOSE <port> [<port>...]`` ``EXPOSE <port> [<port>...]``
The `EXPOSE` instruction sets ports to be publicly exposed when running the image. The `EXPOSE` instruction sets ports to be publicly exposed when running the
This is equivalent to do `docker commit -run '{"PortSpecs": ["<port>", "<port2>"]}'` outside the builder. image. This is functionally equivalent to running
`docker commit -run '{"PortSpecs": ["<port>", "<port2>"]}'` outside the builder.
2.6 ENV 2.6 ENV
------- -------
``ENV <key> <value>`` ``ENV <key> <value>``
The `ENV` instruction set as environment variable `<key>` with the value `<value>`. This value will be passed to all future ``RUN`` instructions. The `ENV` instruction sets the environment variable `<key>` to the value
`<value>`. This value will be passed to all future ``RUN`` instructions. This is
functionally equivalent to prefixing the command with `<key>=<value>`
.. note:: .. note::
The environment variables are local to the Dockerfile, they will not be set as autorun. The environment variables are local to the Dockerfile, they will not persist
when a container is run from the resulting image.
2.7 INSERT 2.7 INSERT
---------- ----------
``INSERT <file url> <path>`` ``INSERT <file url> <path>``
The `INSERT` instruction will download the file at the given url and place it within the image at the given path. The `INSERT` instruction will download the file from the given url to the given
path within the image. It is similar to `RUN curl -o <path> <url>`, assuming
curl was installed within the image.
.. note:: .. note::
The path must include the file name. The path must include the file name.
@ -89,42 +126,57 @@ The `INSERT` instruction will download the file at the given url and place it wi
3. Dockerfile Examples 3. Dockerfile Examples
====================== ======================
:: .. code-block:: bash
# Nginx # Nginx
# #
# VERSION 0.0.1 # VERSION 0.0.1
# DOCKER-VERSION 0.2
from ubuntu FROM ubuntu
maintainer Guillaume J. Charmes "guillaume@dotcloud.com" MAINTAINER Guillaume J. Charmes "guillaume@dotcloud.com"
# make sure the package repository is up to date # 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 echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > /etc/apt/sources.list
run apt-get update RUN apt-get update
run apt-get install -y inotify-tools nginx apache2 openssh-server RUN apt-get install -y inotify-tools nginx apache2 openssh-server
insert https://raw.github.com/creack/docker-vps/master/nginx-wrapper.sh /usr/sbin/nginx-wrapper INSERT https://raw.github.com/creack/docker-vps/master/nginx-wrapper.sh /usr/sbin/nginx-wrapper
:: .. code-block:: bash
# Firefox over VNC # Firefox over VNC
# #
# VERSION 0.3 # VERSION 0.3
# DOCKER-VERSION 0.2
from ubuntu FROM ubuntu
# make sure the package repository is up to date # 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 echo "deb http://archive.ubuntu.com/ubuntu precise main universe" > /etc/apt/sources.list
run apt-get update RUN apt-get update
# Install vnc, xvfb in order to create a 'fake' display and firefox # Install vnc, xvfb in order to create a 'fake' display and firefox
run apt-get install -y x11vnc xvfb firefox RUN apt-get install -y x11vnc xvfb firefox
run mkdir /.vnc RUN mkdir /.vnc
# Setup a password # Setup a password
run x11vnc -storepasswd 1234 ~/.vnc/passwd RUN x11vnc -storepasswd 1234 ~/.vnc/passwd
# Autostart firefox (might not be the best way to do it, but it does the trick) # Autostart firefox (might not be the best way, but it does the trick)
run bash -c 'echo "firefox" >> /.bashrc' RUN bash -c 'echo "firefox" >> /.bashrc'
expose 5900 EXPOSE 5900
cmd ["x11vnc", "-forever", "-usepw", "-create"] 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.