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>