github.com/robertojrojas/docker@v1.9.1/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 [**--build-arg**[=*[]*]] 10 [**--cpu-shares**[=*0*]] 11 [**--cgroup-parent**[=*CGROUP-PARENT*]] 12 [**--help**] 13 [**-f**|**--file**[=*PATH/Dockerfile*]] 14 [**--force-rm**[=*false*]] 15 [**--no-cache**[=*false*]] 16 [**--pull**[=*false*]] 17 [**-q**|**--quiet**[=*false*]] 18 [**--rm**[=*true*]] 19 [**-t**|**--tag**[=*TAG*]] 20 [**-m**|**--memory**[=*MEMORY*]] 21 [**--memory-swap**[=*MEMORY-SWAP*]] 22 [**--cpu-period**[=*0*]] 23 [**--cpu-quota**[=*0*]] 24 [**--cpuset-cpus**[=*CPUSET-CPUS*]] 25 [**--cpuset-mems**[=*CPUSET-MEMS*]] 26 [**--ulimit**[=*[]*]] 27 PATH | URL | - 28 29 # DESCRIPTION 30 This will read the Dockerfile from the directory specified in **PATH**. 31 It also sends any other files and directories found in the current 32 directory to the Docker daemon. The contents of this directory would 33 be used by **ADD** commands found within the Dockerfile. 34 35 Warning, this will send a lot of data to the Docker daemon depending 36 on the contents of the current directory. The build is run by the Docker 37 daemon, not by the CLI, so the whole context must be transferred to the daemon. 38 The Docker CLI reports "Sending build context to Docker daemon" when the context is sent to 39 the daemon. 40 41 When the URL to a tarball archive or to a single Dockerfile is given, no context is sent from 42 the client to the Docker daemon. In this case, the Dockerfile at the root of the archive and 43 the rest of the archive will get used as the context of the build. When a Git repository is 44 set as the **URL**, the repository is cloned locally and then sent as the context. 45 46 # OPTIONS 47 **-f**, **--file**=*PATH/Dockerfile* 48 Path to the Dockerfile to use. If the path is a relative path and you are 49 building from a local directory, then the path must be relative to that 50 directory. If you are building from a remote URL pointing to either a 51 tarball or a Git repository, then the path must be relative to the root of 52 the remote context. In all cases, the file must be within the build context. 53 The default is *Dockerfile*. 54 55 **--build-arg**=*variable* 56 name and value of a **buildarg**. 57 58 For example, if you want to pass a value for `http_proxy`, use 59 `--build-arg=http_proxy="http://some.proxy.url"` 60 61 Users pass these values at build-time. Docker uses the `buildargs` as the 62 environment context for command(s) run via the Dockerfile's `RUN` instruction 63 or for variable expansion in other Dockerfile instructions. This is not meant 64 for passing secret values. [Read more about the buildargs instruction](/reference/builder/#arg) 65 66 **--force-rm**=*true*|*false* 67 Always remove intermediate containers, even after unsuccessful builds. The default is *false*. 68 69 **--no-cache**=*true*|*false* 70 Do not use cache when building the image. The default is *false*. 71 72 **--help** 73 Print usage statement 74 75 **--pull**=*true*|*false* 76 Always attempt to pull a newer version of the image. The default is *false*. 77 78 **-q**, **--quiet**=*true*|*false* 79 Suppress the verbose output generated by the containers. The default is *false*. 80 81 **--rm**=*true*|*false* 82 Remove intermediate containers after a successful build. The default is *true*. 83 84 **-t**, **--tag**="" 85 Repository name (and optionally a tag) to be applied to the resulting image in case of success 86 87 **-m**, **--memory**=*MEMORY* 88 Memory limit 89 90 **--memory-swap**=*MEMORY-SWAP* 91 Total memory (memory + swap), '-1' to disable swap. 92 93 **--cpu-shares**=*0* 94 CPU shares (relative weight). 95 96 By default, all containers get the same proportion of CPU cycles. 97 CPU shares is a 'relative weight', relative to the default setting of 1024. 98 This default value is defined here: 99 ``` 100 cat /sys/fs/cgroup/cpu/cpu.shares 101 1024 102 ``` 103 You can change this proportion by adjusting the container's CPU share 104 weighting relative to the weighting of all other running containers. 105 106 To modify the proportion from the default of 1024, use the **--cpu-shares** 107 flag to set the weighting to 2 or higher. 108 109 Container CPU share Flag 110 {C0} 60% of CPU --cpu-shares=614 (614 is 60% of 1024) 111 {C1} 40% of CPU --cpu-shares=410 (410 is 40% of 1024) 112 113 The proportion is only applied when CPU-intensive processes are running. 114 When tasks in one container are idle, the other containers can use the 115 left-over CPU time. The actual amount of CPU time used varies depending on 116 the number of containers running on the system. 117 118 For example, consider three containers, where one has **--cpu-shares=1024** and 119 two others have **--cpu-shares=512**. When processes in all three 120 containers attempt to use 100% of CPU, the first container would receive 121 50% of the total CPU time. If you add a fourth container with **--cpu-shares=1024**, 122 the first container only gets 33% of the CPU. The remaining containers 123 receive 16.5%, 16.5% and 33% of the CPU. 124 125 126 Container CPU share Flag CPU time 127 {C0} 100% --cpu-shares=1024 33% 128 {C1} 50% --cpu-shares=512 16.5% 129 {C2} 50% --cpu-shares=512 16.5% 130 {C4} 100% --cpu-shares=1024 33% 131 132 133 On a multi-core system, the shares of CPU time are distributed across the CPU 134 cores. Even if a container is limited to less than 100% of CPU time, it can 135 use 100% of each individual CPU core. 136 137 For example, consider a system with more than three cores. If you start one 138 container **{C0}** with **--cpu-shares=512** running one process, and another container 139 **{C1}** with **--cpu-shares=1024** running two processes, this can result in the following 140 division of CPU shares: 141 142 PID container CPU CPU share 143 100 {C0} 0 100% of CPU0 144 101 {C1} 1 100% of CPU1 145 102 {C1} 2 100% of CPU2 146 147 **--cpu-period**=*0* 148 Limit the CPU CFS (Completely Fair Scheduler) period. 149 150 Limit the container's CPU usage. This flag causes the kernel to restrict the 151 container's CPU usage to the period you specify. 152 153 **--cpu-quota**=*0* 154 Limit the CPU CFS (Completely Fair Scheduler) quota. 155 156 By default, containers run with the full CPU resource. This flag causes the 157 kernel to restrict the container's CPU usage to the quota you specify. 158 159 **--cpuset-cpus**=*CPUSET-CPUS* 160 CPUs in which to allow execution (0-3, 0,1). 161 162 **--cpuset-mems**=*CPUSET-MEMS* 163 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on 164 NUMA systems. 165 166 For example, if you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1` 167 to ensure the processes in your Docker container only use memory from the first 168 two memory nodes. 169 170 **--cgroup-parent**=*CGROUP-PARENT* 171 Path to `cgroups` under which the container's `cgroup` are created. 172 173 If the path is not absolute, the path is considered relative to the `cgroups` path of the init process. 174 Cgroups are created if they do not already exist. 175 176 **--ulimit**=[] 177 Ulimit options 178 179 For more information about `ulimit` see [Setting ulimits in a 180 container](https://docs.docker.com/reference/commandline/run/#setting-ulimits-in-a-container) 181 182 # EXAMPLES 183 184 ## Building an image using a Dockerfile located inside the current directory 185 186 Docker images can be built using the build command and a Dockerfile: 187 188 docker build . 189 190 During the build process Docker creates intermediate images. In order to 191 keep them, you must explicitly set `--rm=false`. 192 193 docker build --rm=false . 194 195 A good practice is to make a sub-directory with a related name and create 196 the Dockerfile in that directory. For example, a directory called mongo may 197 contain a Dockerfile to create a Docker MongoDB image. Likewise, another 198 directory called httpd may be used to store Dockerfiles for Apache web 199 server images. 200 201 It is also a good practice to add the files required for the image to the 202 sub-directory. These files will then be specified with the `COPY` or `ADD` 203 instructions in the `Dockerfile`. 204 205 Note: If you include a tar file (a good practice), then Docker will 206 automatically extract the contents of the tar file specified within the `ADD` 207 instruction into the specified target. 208 209 ## Building an image and naming that image 210 211 A good practice is to give a name to the image you are building. Note that 212 only a-z0-9-_. should be used for consistency. There are no hard rules here but it is best to give the names consideration. 213 214 The **-t**/**--tag** flag is used to rename an image. Here are some examples: 215 216 Though it is not a good practice, image names can be arbitrary: 217 218 docker build -t myimage . 219 220 A better approach is to provide a fully qualified and meaningful repository, 221 name, and tag (where the tag in this context means the qualifier after 222 the ":"). In this example we build a JBoss image for the Fedora repository 223 and give it the version 1.0: 224 225 docker build -t fedora/jboss:1.0 . 226 227 The next example is for the "whenry" user repository and uses Fedora and 228 JBoss and gives it the version 2.1 : 229 230 docker build -t whenry/fedora-jboss:v2.1 . 231 232 If you do not provide a version tag then Docker will assign `latest`: 233 234 docker build -t whenry/fedora-jboss . 235 236 When you list the images, the image above will have the tag `latest`. 237 238 So renaming an image is arbitrary but consideration should be given to 239 a useful convention that makes sense for consumers and should also take 240 into account Docker community conventions. 241 242 243 ## Building an image using a URL 244 245 This will clone the specified GitHub repository from the URL and use it 246 as context. The Dockerfile at the root of the repository is used as 247 Dockerfile. This only works if the GitHub repository is a dedicated 248 repository. 249 250 docker build github.com/scollier/purpletest 251 252 Note: You can set an arbitrary Git repository via the `git://` schema. 253 254 ## Building an image using a URL to a tarball'ed context 255 256 This will send the URL itself to the Docker daemon. The daemon will fetch the 257 tarball archive, decompress it and use its contents as the build context. The 258 Dockerfile at the root of the archive and the rest of the archive will get used 259 as the context of the build. If you pass an **-f PATH/Dockerfile** option as well, 260 the system will look for that file inside the contents of the tarball. 261 262 docker build -f dev/Dockerfile https://10.10.10.1/docker/context.tar.gz 263 264 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and 'identity' (no compression). 265 266 # HISTORY 267 March 2014, Originally compiled by William Henry (whenry at redhat dot com) 268 based on docker.com source material and internal work. 269 June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> 270 June 2015, updated by Sally O'Malley <somalley@redhat.com>