1DOCKER(1) JUNE 2014 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]
13 [--iidfile[=CIDFILE]] [-f|--file[=PATH/Dockerfile]] [-squash]
14 Experimental [--force-rm] [--isolation[=default]] [--label[=[]]]
15 [--no-cache] [--pull] [--compress] [-q|--quiet] [--rm[=true]]
16 [-t|--tag[=[]]] [-m|--memory[=MEMORY]] [--memory-swap[=LIMIT]]
17 [--network[="default"]] [--shm-size[=SHM-SIZE]] [--cpu-period[=0]]
18 [--cpu-quota[=0]] [--cpuset-cpus[=CPUSET-CPUS]]
19 [--cpuset-mems[=CPUSET-MEMS]] [--target[=[]]] [--ulimit[=[]]] PATH |
20 URL | -
21
25 This will read the Dockerfile from the directory specified in PATH. It
26 also sends any other files and directories found in the current
27 directory to the Docker daemon. The contents of this directory would be
28 used by ADD commands found within the Dockerfile.
29 Warning, this will send a lot of data to the Docker daemon depending on
32 the contents of the current directory. The build is run by the Docker
33 daemon, not by the CLI, so the whole context must be transferred to the
34 daemon. The Docker CLI reports "Sending build context to Docker
35 daemon" when the context is sent to the daemon.
36 When the URL to a tarball archive or to a single Dockerfile is given,
39 no context is sent from the client to the Docker daemon. In this case,
40 the Dockerfile at the root of the archive and the rest of the archive
41 will get used as the context of the build. When a Git repository is
42 set as the URL, the repository is cloned locally and then sent as the
43 context.
44
48 -f, --file=PATH/Dockerfile
49 Path to the Dockerfile to use. If the path is a relative path and
50 you are
51 building from a local directory, then the path must be relative to
52 that
53 directory. If you are building from a remote URL pointing to either
54 a
55 tarball or a Git repository, then the path must be relative to the
56 root of
57 the remote context. In all cases, the file must be within the build
58 context.
59 The default is Dockerfile.
60 --squash=true|false
63 Experimental Only
64 Once the image is built, squash the new layers into a new image with
65 a single
66 new layer. Squashing does not destroy any existing image, rather it
67 creates a new
68 image with the content of the squashed layers. This effectively
69 makes it look
70 like all Dockerfile commands were created with a single layer. The
71 build
72 cache is preserved with this method.
73 Note: using this option means the new image will not be able to take
76 advantage of layer sharing with other images and may use
77 significantly more
78 space.
79 Note: using this option you may see significantly more space used due
82 to
83 storing two copies of the image, one for the build cache with all
84 the cache
85 layers in tact, and one for the squashed version.
86 --add-host=[]
89 Add a custom host-to-IP mapping (host:ip)
90 Add a line to /etc/hosts. The format is hostname:ip. The --add-host
93 option can be set multiple times.
94 --build-arg=variable
97 name and value of a buildarg.
98 For example, if you want to pass a value for http_proxy, use
101 --build-arg=http_proxy="http://some.proxy.url"
102 Users pass these values at build-time. Docker uses the buildargs as the
105 environment context for command(s) run via the Dockerfile's RUN
106 instruction
107 or for variable expansion in other Dockerfile instructions. This is
108 not meant
109 for passing secret values. Read more about the buildargs instruction
110 ⟨https://docs.docker.com/engine/reference/builder/#arg⟩
111 --cache-from=""
114 Set image that will be used as a build cache source.
115 --force-rm=true|false
118 Always remove intermediate containers, even after unsuccessful
119 builds. The default is false.
120 --isolation="default"
123 Isolation specifies the type of isolation technology used by
124 containers.
125 --label=label
128 Set metadata for an image
129 --no-cache=true|false
132 Do not use cache when building the image. The default is false.
133 --iidfile=""
136 Write the image ID to the file
137 --help
140 Print usage statement
141 --pull=true|false
144 Always attempt to pull a newer version of the image. The default is
145 false.
146 --compress=true|false
149 Compress the build context using gzip. The default is false.
150 -q, --quiet=true|false
153 Suppress the build output and print image ID on success. The default
154 is false.
155 --rm=true|false
158 Remove intermediate containers after a successful build. The default
159 is true.
160 -t, --tag=""
163 Repository names (and optionally with tags) to be applied to the
164 resulting
165 image in case of success. Refer to docker-tag(1) for more
166 information
167 about valid tag names.
168 -m, --memory=MEMORY
171 Memory limit
172 --memory-swap=LIMIT
175 A limit value equal to memory plus swap. Must be used with the -m
176 (--memory) flag. The swap LIMIT should always be larger than -m
177 (--memory) value.
178 The format of LIMIT is <number>[<unit>]. Unit can be b (bytes), k
181 (kilobytes), m (megabytes), or g (gigabytes). If you don't specify a
182 unit, b is used. Set LIMIT to -1 to enable unlimited swap.
183 --network=bridge
186 Set the networking mode for the RUN instructions during build.
187 Supported standard
188 values are: bridge, host, none and container:<name|id>. Any other
189 value
190 is taken as a custom network's name or ID which this container should
191 connect to.
192 --shm-size=SHM-SIZE
195 Size of /dev/shm. The format is <number><unit>. number must be
196 greater than 0.
197 Unit is optional and can be b (bytes), k (kilobytes), m (megabytes),
198 or g (gigabytes). If you omit the unit, the system uses bytes.
199 If you omit the size entirely, the system uses 64m.
200 --cpu-shares=0
203 CPU shares (relative weight).
204 By default, all containers get the same proportion of CPU cycles.
207 CPU shares is a 'relative weight', relative to the default setting of
208 1024.
209 This default value is defined here:
210 cat /sys/fs/cgroup/cpu/cpu.shares
213 1024
214 You can change this proportion by adjusting the container's CPU share
218 weighting relative to the weighting of all other running containers.
219 To modify the proportion from the default of 1024, use the --cpu-shares
222 flag to set the weighting to 2 or higher.
223 Container CPU share Flag
226 {C0} 60% of CPU --cpu-shares=614 (614 is 60% of 1024)
227 {C1} 40% of CPU --cpu-shares=410 (410 is 40% of 1024)
228 The proportion is only applied when CPU-intensive processes are
232 running.
233 When tasks in one container are idle, the other containers can use
234 the
235 left-over CPU time. The actual amount of CPU time used varies
236 depending on
237 the number of containers running on the system.
238 For example, consider three containers, where one has --cpu-shares=1024
241 and
242 two others have --cpu-shares=512. When processes in all three
243 containers attempt to use 100% of CPU, the first container would
244 receive
245 50% of the total CPU time. If you add a fourth container with
246 --cpu-shares=1024,
247 the first container only gets 33% of the CPU. The remaining
248 containers
249 receive 16.5%, 16.5% and 33% of the CPU.
250 Container CPU share Flag CPU time
253 {C0} 100% --cpu-shares=1024 33%
254 {C1} 50% --cpu-shares=512 16.5%
255 {C2} 50% --cpu-shares=512 16.5%
256 {C4} 100% --cpu-shares=1024 33%
257 On a multi-core system, the shares of CPU time are distributed across
261 the CPU
262 cores. Even if a container is limited to less than 100% of CPU time,
263 it can
264 use 100% of each individual CPU core.
265 For example, consider a system with more than three cores. If you start
268 one
269 container {C0} with --cpu-shares=512 running one process, and another
270 container
271 {C1} with --cpu-shares=1024 running two processes, this can result in
272 the following
273 division of CPU shares:
274 PID container CPU CPU share
277 100 {C0} 0 100% of CPU0
278 101 {C1} 1 100% of CPU1
279 102 {C1} 2 100% of CPU2
280 --cpu-period=0
284 Limit the CPU CFS (Completely Fair Scheduler) period.
285 Limit the container's CPU usage. This flag causes the kernel to
288 restrict the
289 container's CPU usage to the period you specify.
290 --cpu-quota=0
293 Limit the CPU CFS (Completely Fair Scheduler) quota.
294 By default, containers run with the full CPU resource. This flag causes
297 the kernel to restrict the container's CPU usage to the quota you
298 specify.
299 --cpuset-cpus=CPUSET-CPUS
302 CPUs in which to allow execution (0-3, 0,1).
303 --cpuset-mems=CPUSET-MEMS
306 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only
307 effective on
308 NUMA systems.
309 For example, if you have four memory nodes on your system (0-3), use
312 --cpuset-mems=0,1 to ensure the processes in your Docker container only
313 use memory from the first two memory nodes.
314 --cgroup-parent=CGROUP-PARENT
317 Path to cgroups under which the container's cgroup are created.
318 If the path is not absolute, the path is considered relative to the
321 cgroups path of the init process. Cgroups are created if they do not
322 already exist.
323 --target=""
326 Set the target build stage name.
327 --ulimit=[]
330 Ulimit options
331 For more information about ulimit see Setting ulimits in a container
334 ⟨https://docs.docker.com/engine/reference/commandline/run/#set-ulimits-
335 in-container---ulimit⟩
336
341 Docker images can be built using the build command and a Dockerfile:
342 docker build .
345 During the build process Docker creates intermediate images. In order
349 to keep them, you must explicitly set --rm=false.
350 docker build --rm=false .
353 A good practice is to make a sub-directory with a related name and
357 create the Dockerfile in that directory. For example, a directory
358 called mongo may contain a Dockerfile to create a Docker MongoDB image.
359 Likewise, another directory called httpd may be used to store
360 Dockerfiles for Apache web server images.
361 It is also a good practice to add the files required for the image to
364 the sub-directory. These files will then be specified with the COPY or
365 ADD instructions in the Dockerfile.
366 Note: If you include a tar file (a good practice), then Docker will
369 automatically extract the contents of the tar file specified within the
370 ADD instruction into the specified target.
371
374 A good practice is to give a name to the image you are building. Note
375 that only a-z0-9-_. should be used for consistency. There are no hard
376 rules here but it is best to give the names consideration.
377 The -t/--tag flag is used to rename an image. Here are some examples:
380 Though it is not a good practice, image names can be arbitrary:
383 docker build -t myimage .
386 A better approach is to provide a fully qualified and meaningful
390 repository, name, and tag (where the tag in this context means the
391 qualifier after the ":"). In this example we build a JBoss image for
392 the Fedora repository and give it the version 1.0:
393 docker build -t fedora/jboss:1.0 .
396 The next example is for the "whenry" user repository and uses Fedora
400 and JBoss and gives it the version 2.1 :
401 docker build -t whenry/fedora-jboss:v2.1 .
404 If you do not provide a version tag then Docker will assign latest:
408 docker build -t whenry/fedora-jboss .
411 When you list the images, the image above will have the tag latest.
415 You can apply multiple tags to an image. For example, you can apply the
418 latest tag to a newly built image and add another tag that references a
419 specific version. For example, to tag an image both as
420 whenry/fedora-jboss:latest and whenry/fedora-jboss:v2.1, use the
421 following:
422 docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
425 So renaming an image is arbitrary but consideration should be given to
429 a useful convention that makes sense for consumers and should also take
430 into account Docker community conventions.
431
434 This will clone the specified GitHub repository from the URL and use it
435 as context. The Dockerfile at the root of the repository is used as
436 Dockerfile. This only works if the GitHub repository is a dedicated
437 repository.
438 docker build github.com/scollier/purpletest
441 Note: You can set an arbitrary Git repository via the git:// scheme.
445
448 This will send the URL itself to the Docker daemon. The daemon will
449 fetch the tarball archive, decompress it and use its contents as the
450 build context. The Dockerfile at the root of the archive and the rest
451 of the archive will get used as the context of the build. If you pass
452 an -f PATH/Dockerfile option as well, the system will look for that
453 file inside the contents of the tarball.
454 docker build -f dev/Dockerfile https://10.10.10.1/docker/context.tar.gz
457 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and
461 'identity' (no compression).
462
465 This option is useful in situations where you are running Docker
466 containers on Windows. The --isolation=<value> option sets a
467 container's isolation technology. On Linux, the only supported is the
468 default option which uses Linux namespaces. On Microsoft Windows, you
469 can specify these values:
470 · default: Use the value specified by the Docker daemon's
473 --exec-opt . If the daemon does not specify an isolation
474 technology, Microsoft Windows uses process as its default
475 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⟩ June 2015, updated
492 by Sally O'Malley ⟨somalley@redhat.com⟩
493Docker Community Docker User Manuals DOCKER(1)