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