1DOCKER(1) Docker User Manuals DOCKER(1)
2
6 docker-build - Build an image from a Dockerfile
7
11 docker build [--add-host[=[]]] [--build-arg[=[]]] [--cache-from[=[]]]
12 [--cpu-shares[=0]] [--cgroup-parent[=CGROUP-PARENT]] [--help] [--iid‐
13 file[=CIDFILE]] [-f|--file[=PATH/Dockerfile]] [-squash] Experimental
14 [--force-rm] [--isolation[=default]] [--label[=[]]] [--no-cache]
15 [--pull] [--compress] [-q|--quiet] [--rm[=true]] [-t|--tag[=[]]]
16 [-m|--memory[=MEMORY]] [--memory-swap[=LIMIT]] [--network[="default"]]
17 [--shm-size[=SHM-SIZE]] [--cpu-period[=0]] [--cpu-quota[=0]] [--cpuset-
18 cpus[=CPUSET-CPUS]] [--cpuset-mems[=CPUSET-MEMS]] [--target[=[]]]
19 [--ulimit[=[]]] PATH | URL | -
20
24 This will read the Dockerfile from the directory specified in PATH. It
25 also sends any other files and directories found in the current direc‐
26 tory to the Docker daemon. The contents of this directory would be used
27 by ADD commands found within the Dockerfile.
28 Warning, this will send a lot of data to the Docker daemon depending on
31 the contents of the current directory. The build is run by the Docker
32 daemon, not by the CLI, so the whole context must be transferred to the
33 daemon. The Docker CLI reports "Sending build context to Docker dae‐
34 mon" when the context is sent to the daemon.
35 When the URL to a tarball archive or to a single Dockerfile is given,
38 no context is sent from the client to the Docker daemon. In this case,
39 the Dockerfile at the root of the archive and the rest of the archive
40 will get used as the context of the build. When a Git repository is
41 set as the URL, the repository is cloned locally and then sent as the
42 context.
43
47 -f, --file PATH/Dockerfile
48 Path to the Dockerfile to use. If the path is a relative path and
49 you are
50 building from a local directory, then the path must be relative to
51 that
52 directory. If you are building from a remote URL pointing to either
53 a
54 tarball or a Git repository, then the path must be relative to the
55 root of
56 the remote context. In all cases, the file must be within the build
57 context.
58 The default is Dockerfile.
59 --squash true|false
62 Experimental Only
63 Once the image is built, squash the new layers into a new image with
64 a single
65 new layer. Squashing does not destroy any existing image, rather it
66 creates a new
67 image with the content of the squashed layers. This effectively
68 makes it look
69 like all Dockerfile commands were created with a single layer. The
70 build
71 cache is preserved with this method.
72 Note: using this option means the new image will not be able to take
75 advantage of layer sharing with other images and may use signifi‐
76 cantly more
77 space.
78 Note: using this option you may see significantly more space used due
81 to
82 storing two copies of the image, one for the build cache with all
83 the cache
84 layers in tact, and one for the squashed version.
85 --add-host []
88 Add a custom host-to-IP mapping (host:ip)
89 Add a line to /etc/hosts. The format is hostname:ip. The --add-host
92 option can be set multiple times.
93 --build-arg variable
96 name and value of a buildarg.
97 For example, if you want to pass a value for http_proxy, use
100 --build-arg=http_proxy="http://some.proxy.url"
101 Users pass these values at build-time. Docker uses the buildargs as the
104 environment context for command(s) run via the Dockerfile's RUN in‐
105 struction
106 or for variable expansion in other Dockerfile instructions. This is
107 not meant
108 for passing secret values. Read more about the buildargs instruction
109 ⟨https://docs.docker.com/engine/reference/builder/#arg⟩
110 --cache-from ""
113 Set image that will be used as a build cache source.
114 --force-rm true|false
117 Always remove intermediate containers, even after unsuccessful
118 builds. The default is false.
119 --isolation "default"
122 Isolation specifies the type of isolation technology used by con‐
123 tainers.
124 --label label
127 Set metadata for an image
128 --no-cache true|false
131 Do not use cache when building the image. The default is false.
132 --iidfile ""
135 Write the image ID to the file
136 --help
139 Print usage statement
140 --pull true|false
143 Always attempt to pull a newer version of the image. The default is
144 false.
145 --compress true|false
148 Compress the build context using gzip. The default is false.
149 -q, --quiet true|false
152 Suppress the build output and print image ID on success. The default
153 is false.
154 --rm true|false
157 Remove intermediate containers after a successful build. The default
158 is true.
159 -t, --tag ""
162 Repository names (and optionally with tags) to be applied to the re‐
163 sulting
164 image in case of success. Refer to docker-tag(1) for more informa‐
165 tion
166 about valid tag names.
167 -m, --memory MEMORY
170 Memory limit
171 --memory-swap number[S]
174 Combined memory plus swap limit; S is an optional suffix which can
175 be one
176 of b (bytes), k (kilobytes), m (megabytes), or g (gigabytes).
177 This option can only be used together with --memory. The argument
180 should always be larger than that of --memory. Default is double the
181 value of --memory. Set to -1 to enable unlimited swap.
182 --network type
185 Set the networking mode for the RUN instructions during build. Sup‐
186 ported standard
187 values are: none, bridge, host and container:<name|id>. Any other
188 value
189 is taken as a custom network's name or ID which this container should
190 connect to.
191 In Linux, default is bridge.
194 --shm-size SHM-SIZE
197 Size of /dev/shm. The format is <number><unit>. number must be
198 greater than 0.
199 Unit is optional and can be b (bytes), k (kilobytes), m (megabytes),
200 or g (gigabytes). If you omit the unit, the system uses bytes.
201 If you omit the size entirely, the system uses 64m.
202 --cpu-shares 0
205 CPU shares (relative weight).
206 By default, all containers get the same proportion of CPU cycles.
209 CPU shares is a 'relative weight', relative to the default setting of
210 1024.
211 This default value is defined here:
212 cat /sys/fs/cgroup/cpu/cpu.shares
215 1024
216 You can change this proportion by adjusting the container's CPU share
220 weighting relative to the weighting of all other running containers.
221 To modify the proportion from the default of 1024, use the --cpu-shares
224 flag to set the weighting to 2 or higher.
225 Container CPU share Flag
228 {C0} 60% of CPU --cpu-shares 614 (614 is 60% of 1024)
229 {C1} 40% of CPU --cpu-shares 410 (410 is 40% of 1024)
230 The proportion is only applied when CPU-intensive processes are run‐
234 ning.
235 When tasks in one container are idle, the other containers can use
236 the
237 left-over CPU time. The actual amount of CPU time used varies depend‐
238 ing on
239 the number of containers running on the system.
240 For example, consider three containers, where one has --cpu-shares 1024
243 and
244 two others have --cpu-shares 512. When processes in all three
245 containers attempt to use 100% of CPU, the first container would re‐
246 ceive
247 50% of the total CPU time. If you add a fourth container with --cpu-
248 shares 1024,
249 the first container only gets 33% of the CPU. The remaining contain‐
250 ers
251 receive 16.5%, 16.5% and 33% of the CPU.
252 Container CPU share Flag CPU time
255 {C0} 100% --cpu-shares 1024 33%
256 {C1} 50% --cpu-shares 512 16.5%
257 {C2} 50% --cpu-shares 512 16.5%
258 {C4} 100% --cpu-shares 1024 33%
259 On a multi-core system, the shares of CPU time are distributed across
263 the CPU
264 cores. Even if a container is limited to less than 100% of CPU time,
265 it can
266 use 100% of each individual CPU core.
267 For example, consider a system with more than three cores. If you start
270 one
271 container {C0} with --cpu-shares 512 running one process, and another
272 container
273 {C1} with --cpu-shares 1024 running two processes, this can result in
274 the following
275 division of CPU shares:
276 PID container CPU CPU share
279 100 {C0} 0 100% of CPU0
280 101 {C1} 1 100% of CPU1
281 102 {C1} 2 100% of CPU2
282 --cpu-period 0
286 Limit the CPU CFS (Completely Fair Scheduler) period.
287 Limit the container's CPU usage. This flag causes the kernel to re‐
290 strict the
291 container's CPU usage to the period you specify.
292 --cpu-quota 0
295 Limit the CPU CFS (Completely Fair Scheduler) quota.
296 By default, containers run with the full CPU resource. This flag causes
299 the kernel to restrict the container's CPU usage to the quota you spec‐
300 ify.
301 --cpuset-cpus CPUSET-CPUS
304 CPUs in which to allow execution (0-3, 0,1).
305 --cpuset-mems CPUSET-MEMS
308 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only ef‐
309 fective on
310 NUMA systems.
311 For example, if you have four memory nodes on your system (0-3), use
314 --cpuset-mems 0,1 to ensure the processes in your Docker container only
315 use memory from the first two memory nodes.
316 --cgroup-parent CGROUP-PARENT
319 Path to cgroups under which the container's cgroup are created.
320 If the path is not absolute, the path is considered relative to the
323 cgroups path of the init process. Cgroups are created if they do not
324 already exist.
325 --target ""
328 Set the target build stage name.
329 --ulimit []
332 Ulimit options
333 For more information about ulimit see Setting ulimits in a container
336 ⟨https://docs.docker.com/engine/reference/commandline/run/#set-ulimits-
337 in-container---ulimit⟩
338
343 Docker images can be built using the build command and a Dockerfile:
344 docker build .
347 During the build process Docker creates intermediate images. In order
351 to keep them, you must explicitly set --rm false.
352 docker build --rm false .
355 A good practice is to make a sub-directory with a related name and cre‐
359 ate the Dockerfile in that directory. For example, a directory called
360 mongo may contain a Dockerfile to create a Docker MongoDB image. Like‐
361 wise, another directory called httpd may be used to store Dockerfiles
362 for Apache web server images.
363 It is also a good practice to add the files required for the image to
366 the sub-directory. These files will then be specified with the COPY or
367 ADD instructions in the Dockerfile.
368 Note: If you include a tar file (a good practice), then Docker will au‐
371 tomatically extract the contents of the tar file specified within the
372 ADD instruction into the specified target.
373
376 A good practice is to give a name to the image you are building. Note
377 that only a-z0-9-_. should be used for consistency. There are no hard
378 rules here but it is best to give the names consideration.
379 The -t/--tag flag is used to rename an image. Here are some examples:
382 Though it is not a good practice, image names can be arbitrary:
385 docker build -t myimage .
388 A better approach is to provide a fully qualified and meaningful repos‐
392 itory, name, and tag (where the tag in this context means the qualifier
393 after the ":"). In this example we build a JBoss image for the Fedora
394 repository and give it the version 1.0:
395 docker build -t fedora/jboss:1.0 .
398 The next example is for the "whenry" user repository and uses Fedora
402 and JBoss and gives it the version 2.1 :
403 docker build -t whenry/fedora-jboss:v2.1 .
406 If you do not provide a version tag then Docker will assign latest:
410 docker build -t whenry/fedora-jboss .
413 When you list the images, the image above will have the tag latest.
417 You can apply multiple tags to an image. For example, you can apply the
420 latest tag to a newly built image and add another tag that references a
421 specific version. For example, to tag an image both as whenry/fedora-
422 jboss:latest and whenry/fedora-jboss:v2.1, use the following:
423 docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
426 So renaming an image is arbitrary but consideration should be given to
430 a useful convention that makes sense for consumers and should also take
431 into account Docker community conventions.
432
435 This will clone the specified GitHub repository from the URL and use it
436 as context. The Dockerfile at the root of the repository is used as
437 Dockerfile. This only works if the GitHub repository is a dedicated
438 repository.
439 docker build github.com/scollier/purpletest
442 Note: You can set an arbitrary Git repository via the git:// scheme.
446
449 This will send the URL itself to the Docker daemon. The daemon will
450 fetch the tarball archive, decompress it and use its contents as the
451 build context. The Dockerfile at the root of the archive and the rest
452 of the archive will get used as the context of the build. If you pass
453 an -f PATH/Dockerfile option as well, the system will look for that
454 file inside the contents of the tarball.
455 docker build -f dev/Dockerfile https://10.10.10.1/docker/context.tar.gz
458 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and
462 'identity' (no compression).
463
466 This option is useful in situations where you are running Docker con‐
467 tainers on Windows. The --isolation <value> option sets a container's
468 isolation technology. On Linux, the only supported is the default op‐
469 tion which uses Linux namespaces. On Microsoft Windows, you can specify
470 these values:
471 • default: Use the value specified by the Docker daemon's
474 --exec-opt . If the daemon does not specify an isolation tech‐
475 nology, Microsoft Windows uses process as its default value.
476 • process: Namespace isolation only.
478 • hyperv: Hyper-V hypervisor partition-based isolation.
480 Specifying the --isolation flag without a value is the same as setting
484 --isolation "default".
485
489 March 2014, Originally compiled by William Henry (whenry at redhat dot
490 com) based on docker.com source material and internal work. June 2014,
491 updated by Sven Dowideit SvenDowideit@home.org.au ⟨mailto:Sven‐
492 Dowideit@home.org.au⟩ June 2015, updated by Sally O'Malley somal‐
493 ley@redhat.com ⟨mailto:somalley@redhat.com⟩ August 2020, Updated by Des
494 Preston despreston@gmail.com ⟨mailto:despreston@gmail.com⟩
495Docker Community JUNE 2014 DOCKER(1)