1DOCKER(1) JUNE 2014 DOCKER(1)
2
6 docker-build - Build an image from a Dockerfile
7
11 docker build [--build-arg[=[]]] [--cpu-shares[=0]]
12 [--cgroup-parent[=CGROUP-PARENT]] [--help]
13 [-f|--file[=PATH/Dockerfile]] [-squash] Experimental [--force-rm]
14 [--isolation[=default]] [--label[=[]]] [--no-cache] [--pull]
15 [--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]]
18 [--cpuset-cpus[=CPUSET-CPUS]] [--cpuset-mems[=CPUSET-MEMS]]
19 [--ulimit[=[]]] [-v|--volume[=[]]] 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
26 directory to the Docker daemon. The contents of this directory would be
27 used 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
34 daemon" 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 squshed layers. This effectively makes
68 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
76 significantly 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 --build-arg=variable
88 name and value of a buildarg.
89 For example, if you want to pass a value for http_proxy, use
92 --build-arg=http_proxy="http://some.proxy.url"
93 Users pass these values at build-time. Docker uses the buildargs as the
96 environment context for command(s) run via the Dockerfile's RUN
97 instruction
98 or for variable expansion in other Dockerfile instructions. This is
99 not meant
100 for passing secret values. Read more about the buildargs instruction
101 ⟨https://docs.docker.com/engine/reference/builder/#arg⟩
102 --force-rm=true|false
105 Always remove intermediate containers, even after unsuccessful
106 builds. The default is false.
107 --isolation="default"
110 Isolation specifies the type of isolation technology used by
111 containers.
112 --label=label
115 Set metadata for an image
116 --no-cache=true|false
119 Do not use cache when building the image. The default is false.
120 --help
123 Print usage statement
124 --pull=true|false
127 Always attempt to pull a newer version of the image. The default is
128 false.
129 --compress=true|false
132 Compress the build context using gzip. The default is false.
133 -q, --quiet=true|false
136 Suppress the build output and print image ID on success. The default
137 is false.
138 --rm=true|false
141 Remove intermediate containers after a successful build. The default
142 is true.
143 -t, --tag=""
146 Repository names (and optionally with tags) to be applied to the
147 resulting
148 image in case of success. Refer to docker-tag(1) for more
149 information
150 about valid tag names.
151 -m, --memory=MEMORY
154 Memory limit
155 --memory-swap=LIMIT
158 A limit value equal to memory plus swap. Must be used with the -m
159 (--memory) flag. The swap LIMIT should always be larger than -m
160 (--memory) value.
161 The format of LIMIT is <number>[<unit>]. Unit can be b (bytes), k
164 (kilobytes), m (megabytes), or g (gigabytes). If you don't specify a
165 unit, b is used. Set LIMIT to -1 to enable unlimited swap.
166 --network=bridge
169 Set the networking mode for the RUN instructions during build.
170 Supported standard
171 values are: bridge, host, none and container:<name|id>. Any other
172 value
173 is taken as a custom network's name or ID which this container should
174 connect to.
175 --shm-size=SHM-SIZE
178 Size of /dev/shm. The format is <number><unit>. number must be
179 greater than 0.
180 Unit is optional and can be b (bytes), k (kilobytes), m (megabytes),
181 or g (gigabytes). If you omit the unit, the system uses bytes.
182 If you omit the size entirely, the system uses 64m.
183 --cpu-shares=0
186 CPU shares (relative weight).
187 By default, all containers get the same proportion of CPU cycles.
190 CPU shares is a 'relative weight', relative to the default setting of
191 1024.
192 This default value is defined here:
193 cat /sys/fs/cgroup/cpu/cpu.shares
196 1024
197 You can change this proportion by adjusting the container's CPU share
201 weighting relative to the weighting of all other running containers.
202 To modify the proportion from the default of 1024, use the --cpu-shares
205 flag to set the weighting to 2 or higher.
206 Container CPU share Flag
209 {C0} 60% of CPU --cpu-shares=614 (614 is 60% of 1024)
210 {C1} 40% of CPU --cpu-shares=410 (410 is 40% of 1024)
211 The proportion is only applied when CPU-intensive processes are
215 running.
216 When tasks in one container are idle, the other containers can use
217 the
218 left-over CPU time. The actual amount of CPU time used varies
219 depending on
220 the number of containers running on the system.
221 For example, consider three containers, where one has --cpu-shares=1024
224 and
225 two others have --cpu-shares=512. When processes in all three
226 containers attempt to use 100% of CPU, the first container would
227 receive
228 50% of the total CPU time. If you add a fourth container with
229 --cpu-shares=1024,
230 the first container only gets 33% of the CPU. The remaining
231 containers
232 receive 16.5%, 16.5% and 33% of the CPU.
233 Container CPU share Flag CPU time
236 {C0} 100% --cpu-shares=1024 33%
237 {C1} 50% --cpu-shares=512 16.5%
238 {C2} 50% --cpu-shares=512 16.5%
239 {C4} 100% --cpu-shares=1024 33%
240 On a multi-core system, the shares of CPU time are distributed across
244 the CPU
245 cores. Even if a container is limited to less than 100% of CPU time,
246 it can
247 use 100% of each individual CPU core.
248 For example, consider a system with more than three cores. If you start
251 one
252 container {C0} with --cpu-shares=512 running one process, and another
253 container
254 {C1} with --cpu-shares=1024 running two processes, this can result in
255 the following
256 division of CPU shares:
257 PID container CPU CPU share
260 100 {C0} 0 100% of CPU0
261 101 {C1} 1 100% of CPU1
262 102 {C1} 2 100% of CPU2
263 --cpu-period=0
267 Limit the CPU CFS (Completely Fair Scheduler) period.
268 Limit the container's CPU usage. This flag causes the kernel to
271 restrict the
272 container's CPU usage to the period you specify.
273 --cpu-quota=0
276 Limit the CPU CFS (Completely Fair Scheduler) quota.
277 By default, containers run with the full CPU resource. This flag causes
280 the kernel to restrict the container's CPU usage to the quota you
281 specify.
282 --cpuset-cpus=CPUSET-CPUS
285 CPUs in which to allow execution (0-3, 0,1).
286 --cpuset-mems=CPUSET-MEMS
289 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only
290 effective on
291 NUMA systems.
292 For example, if you have four memory nodes on your system (0-3), use
295 --cpuset-mems=0,1 to ensure the processes in your Docker container only
296 use memory from the first two memory nodes.
297 --cgroup-parent=CGROUP-PARENT
300 Path to cgroups under which the container's cgroup are created.
301 If the path is not absolute, the path is considered relative to the
304 cgroups path of the init process. Cgroups are created if they do not
305 already exist.
306 --ulimit=[]
309 Ulimit options
310 +-v, --volume=[] Create a bind mount + (format:
313 host-dir:container-dir[:<suffix options>], where suffix options +are
314 comma delimited and selected from [ro] and [z|Z].). Read-write mode
315 isn't supported at build time. +In case rw is specified a warning is
316 printed during the build and it will be changed to ro preserving any
317 SELinux mode provided. +
318 For more information about ulimit see Setting ulimits in a container
321 ⟨https://docs.docker.com/engine/reference/commandline/run/#set-ulimits-
322 in-container---ulimit⟩
323
328 Docker images can be built using the build command and a Dockerfile:
329 docker build .
332 During the build process Docker creates intermediate images. In order
336 to keep them, you must explicitly set --rm=false.
337 docker build --rm=false .
340 A good practice is to make a sub-directory with a related name and
344 create the Dockerfile in that directory. For example, a directory
345 called mongo may contain a Dockerfile to create a Docker MongoDB image.
346 Likewise, another directory called httpd may be used to store
347 Dockerfiles for Apache web server images.
348 It is also a good practice to add the files required for the image to
351 the sub-directory. These files will then be specified with the COPY or
352 ADD instructions in the Dockerfile.
353 Note: If you include a tar file (a good practice), then Docker will
356 automatically extract the contents of the tar file specified within the
357 ADD instruction into the specified target.
358
361 A good practice is to give a name to the image you are building. Note
362 that only a-z0-9-_. should be used for consistency. There are no hard
363 rules here but it is best to give the names consideration.
364 The -t/--tag flag is used to rename an image. Here are some examples:
367 Though it is not a good practice, image names can be arbitrary:
370 docker build -t myimage .
373 A better approach is to provide a fully qualified and meaningful
377 repository, name, and tag (where the tag in this context means the
378 qualifier after the ":"). In this example we build a JBoss image for
379 the Fedora repository and give it the version 1.0:
380 docker build -t fedora/jboss:1.0 .
383 The next example is for the "whenry" user repository and uses Fedora
387 and JBoss and gives it the version 2.1 :
388 docker build -t whenry/fedora-jboss:v2.1 .
391 If you do not provide a version tag then Docker will assign latest:
395 docker build -t whenry/fedora-jboss .
398 When you list the images, the image above will have the tag latest.
402 You can apply multiple tags to an image. For example, you can apply the
405 latest tag to a newly built image and add another tag that references a
406 specific version. For example, to tag an image both as
407 whenry/fedora-jboss:latest and whenry/fedora-jboss:v2.1, use the
408 following:
409 docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .
412 So renaming an image is arbitrary but consideration should be given to
416 a useful convention that makes sense for consumers and should also take
417 into account Docker community conventions.
418
421 This will clone the specified GitHub repository from the URL and use it
422 as context. The Dockerfile at the root of the repository is used as
423 Dockerfile. This only works if the GitHub repository is a dedicated
424 repository.
425 docker build github.com/scollier/purpletest
428 Note: You can set an arbitrary Git repository via the git:// scheme.
432
435 This will send the URL itself to the Docker daemon. The daemon will
436 fetch the tarball archive, decompress it and use its contents as the
437 build context. The Dockerfile at the root of the archive and the rest
438 of the archive will get used as the context of the build. If you pass
439 an -f PATH/Dockerfile option as well, the system will look for that
440 file inside the contents of the tarball.
441 docker build -f dev/Dockerfile https://10.10.10.1/docker/context.tar.gz
444 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and
448 'identity' (no compression).
449
452 This option is useful in situations where you are running Docker
453 containers on Windows. The --isolation=<value> option sets a
454 container's isolation technology. On Linux, the only supported is the
455 default option which uses Linux namespaces. On Microsoft Windows, you
456 can specify these values:
457 · default: Use the value specified by the Docker daemon's
460 --exec-opt . If the daemon does not specify an isolation
461 technology, Microsoft Windows uses process as its default
462 value.
463 · process: Namespace isolation only.
465 · hyperv: Hyper-V hypervisor partition-based isolation.
467 Specifying the --isolation flag without a value is the same as setting
471 --isolation="default".
472
476 March 2014, Originally compiled by William Henry (whenry at redhat dot
477 com) based on docker.com source material and internal work. June 2014,
478 updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩ June 2015, updated
479 by Sally O'Malley ⟨somalley@redhat.com⟩
480Docker Community Docker User Manuals DOCKER(1)