github.com/tsuna/docker@v1.7.0-rc3/man/docker-build.1.md (about)

     1  % DOCKER(1) Docker User Manuals
     2  % Docker Community
     3  % JUNE 2014
     4  # NAME
     5  docker-build - Build a new image from the source code at PATH
     6  
     7  # SYNOPSIS
     8  **docker build**
     9  [**--help**]
    10  [**-f**|**--file**[=*PATH/Dockerfile*]]
    11  [**--force-rm**[=*false*]]
    12  [**--no-cache**[=*false*]]
    13  [**--pull**[=*false*]]
    14  [**-q**|**--quiet**[=*false*]]
    15  [**--rm**[=*true*]]
    16  [**-t**|**--tag**[=*TAG*]]
    17  [**-m**|**--memory**[=*MEMORY*]]
    18  [**--memory-swap**[=*MEMORY-SWAP*]]
    19  [**-c**|**--cpu-shares**[=*0*]]
    20  [**--cpu-period**[=*0*]]
    21  [**--cpu-quota**[=*0*]]
    22  [**--cpuset-cpus**[=*CPUSET-CPUS*]]
    23  [**--cpuset-mems**[=*CPUSET-MEMS*]]
    24  [**--cgroup-parent**[=*CGROUP-PARENT*]]
    25  
    26  PATH | URL | -
    27  
    28  # DESCRIPTION
    29  This will read the Dockerfile from the directory specified in **PATH**.
    30  It also sends any other files and directories found in the current
    31  directory to the Docker daemon. The contents of this directory would
    32  be used by **ADD** commands found within the Dockerfile.
    33  
    34  Warning, this will send a lot of data to the Docker daemon depending
    35  on the contents of the current directory. The build is run by the Docker 
    36  daemon, not by the CLI, so the whole context must be transferred to the daemon. 
    37  The Docker CLI reports "Sending build context to Docker daemon" when the context is sent to 
    38  the daemon.
    39  
    40  When a single Dockerfile is given as the URL, then no context is set.
    41  When a Git repository is set as the **URL**, the repository is used
    42  as context.
    43  
    44  # OPTIONS
    45  **-f**, **--file**=*PATH/Dockerfile*
    46     Path to the Dockerfile to use. If the path is a relative path then it must be relative to the current directory. The file must be within the build context. The default is *Dockerfile*.
    47  
    48  **--force-rm**=*true*|*false*
    49     Always remove intermediate containers, even after unsuccessful builds. The default is *false*.
    50  
    51  **--no-cache**=*true*|*false*
    52     Do not use cache when building the image. The default is *false*.
    53  
    54  **--help**
    55    Print usage statement
    56  
    57  **--pull**=*true*|*false*
    58     Always attempt to pull a newer version of the image. The default is *false*.
    59  
    60  **-q**, **--quiet**=*true*|*false*
    61     Suppress the verbose output generated by the containers. The default is *false*.
    62  
    63  **--rm**=*true*|*false*
    64     Remove intermediate containers after a successful build. The default is *true*.
    65  
    66  **-t**, **--tag**=""
    67     Repository name (and optionally a tag) to be applied to the resulting image in case of success
    68  
    69  **-m**, **--memory**=*MEMORY*
    70    Memory limit
    71  
    72  **--memory-swap**=*MEMORY-SWAP*
    73    Total memory (memory + swap), '-1' to disable swap.
    74  
    75  **-c**, **--cpu-shares**=*0*
    76    CPU shares (relative weight).
    77  
    78    By default, all containers get the same proportion of CPU cycles. You can
    79    change this proportion by adjusting the container's CPU share weighting
    80    relative to the weighting of all other running containers.
    81  
    82    To modify the proportion from the default of 1024, use the **-c** or
    83    **--cpu-shares** flag to set the weighting to 2 or higher.
    84  
    85    The proportion is only applied when CPU-intensive processes are running.
    86    When tasks in one container are idle, the other containers can use the
    87    left-over CPU time. The actual amount of CPU time used varies depending on
    88    the number of containers running on the system.
    89  
    90    For example, consider three containers, one has a cpu-share of 1024 and
    91    two others have a cpu-share setting of 512. When processes in all three
    92    containers attempt to use 100% of CPU, the first container would receive
    93    50% of the total CPU time. If you add a fourth container with a cpu-share
    94    of 1024, the first container only gets 33% of the CPU. The remaining containers
    95    receive 16.5%, 16.5% and 33% of the CPU.
    96  
    97    On a multi-core system, the shares of CPU time are distributed across the CPU
    98    cores. Even if a container is limited to less than 100% of CPU time, it can
    99    use 100% of each individual CPU core.
   100  
   101    For example, consider a system with more than three cores. If you start one
   102    container **{C0}** with **-c=512** running one process, and another container
   103    **{C1}** with **-c=1024** running two processes, this can result in the following
   104    division of CPU shares:
   105  
   106        PID    container    CPU    CPU share
   107        100    {C0}         0      100% of CPU0
   108        101    {C1}         1      100% of CPU1
   109        102    {C1}         2      100% of CPU2
   110  
   111  **--cpu-period**=*0*
   112    Limit the CPU CFS (Completely Fair Scheduler) period.
   113  
   114    Limit the container's CPU usage. This flag causes the kernel to restrict the
   115    container's CPU usage to the period you specify.
   116  
   117  **--cpu-quota**=*0*
   118    Limit the CPU CFS (Completely Fair Scheduler) quota. 
   119  
   120    By default, containers run with the full CPU resource. This flag causes the
   121  kernel to restrict the container's CPU usage to the quota you specify.
   122  
   123  **--cpuset-cpus**=*CPUSET-CPUS*
   124    CPUs in which to allow execution (0-3, 0,1).
   125  
   126  **--cpuset-mems**=*CPUSET-MEMS*
   127    Memory nodes (MEMs) in which to allow execution (-1-3, 0,1). Only effective on
   128    NUMA systems.
   129  
   130    For example, if you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1`
   131  to ensure the processes in your Docker container only use memory from the first
   132  two memory nodes.
   133  
   134  **--cgroup-parent**=*CGROUP-PARENT*
   135    Path to `cgroups` under which the container's `cgroup` are created.
   136  
   137    If the path is not absolute, the path is considered relative to the `cgroups` path of the init process.
   138  Cgroups are created if they do not already exist.
   139  
   140  # EXAMPLES
   141  
   142  ## Building an image using a Dockerfile located inside the current directory
   143  
   144  Docker images can be built using the build command and a Dockerfile:
   145  
   146      docker build .
   147  
   148  During the build process Docker creates intermediate images. In order to
   149  keep them, you must explicitly set `--rm=false`.
   150  
   151      docker build --rm=false .
   152  
   153  A good practice is to make a sub-directory with a related name and create
   154  the Dockerfile in that directory. For example, a directory called mongo may
   155  contain a Dockerfile to create a Docker MongoDB image. Likewise, another
   156  directory called httpd may be used to store Dockerfiles for Apache web
   157  server images.
   158  
   159  It is also a good practice to add the files required for the image to the
   160  sub-directory. These files will then be specified with the `COPY` or `ADD`
   161  instructions in the `Dockerfile`.
   162  
   163  Note: If you include a tar file (a good practice), then Docker will
   164  automatically extract the contents of the tar file specified within the `ADD`
   165  instruction into the specified target.
   166  
   167  ## Building an image and naming that image
   168  
   169  A good practice is to give a name to the image you are building. There are
   170  no hard rules here but it is best to give the names consideration. 
   171  
   172  The **-t**/**--tag** flag is used to rename an image. Here are some examples:
   173  
   174  Though it is not a good practice, image names can be arbitrary:
   175  
   176      docker build -t myimage .
   177  
   178  A better approach is to provide a fully qualified and meaningful repository,
   179  name, and tag (where the tag in this context means the qualifier after 
   180  the ":"). In this example we build a JBoss image for the Fedora repository 
   181  and give it the version 1.0:
   182  
   183      docker build -t fedora/jboss:1.0
   184  
   185  The next example is for the "whenry" user repository and uses Fedora and
   186  JBoss and gives it the version 2.1 :
   187  
   188      docker build -t whenry/fedora-jboss:V2.1
   189  
   190  If you do not provide a version tag then Docker will assign `latest`:
   191  
   192      docker build -t whenry/fedora-jboss
   193  
   194  When you list the images, the image above will have the tag `latest`.
   195  
   196  So renaming an image is arbitrary but consideration should be given to 
   197  a useful convention that makes sense for consumers and should also take
   198  into account Docker community conventions.
   199  
   200  
   201  ## Building an image using a URL
   202  
   203  This will clone the specified Github repository from the URL and use it
   204  as context. The Dockerfile at the root of the repository is used as
   205  Dockerfile. This only works if the Github repository is a dedicated
   206  repository.
   207  
   208      docker build github.com/scollier/Fedora-Dockerfiles/tree/master/apache
   209  
   210  Note: You can set an arbitrary Git repository via the `git://` schema.
   211  
   212  # HISTORY
   213  March 2014, Originally compiled by William Henry (whenry at redhat dot com)
   214  based on docker.com source material and internal work.
   215  June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>