|
1 .TH "DOCKER" "1" " Docker User Manuals" "Docker Community" "JUNE 2014" "" |
|
2 |
|
3 |
|
4 .SH NAME |
|
5 .PP |
|
6 docker\-build \- Build a new image from the source code at PATH |
|
7 |
|
8 |
|
9 .SH SYNOPSIS |
|
10 .PP |
|
11 \fBdocker build\fP |
|
12 [\fB\-\-build\-arg\fP[=\fI[]\fP]] |
|
13 [\fB\-\-cpu\-shares\fP[=\fI0\fP]] |
|
14 [\fB\-\-cgroup\-parent\fP[=\fICGROUP\-PARENT\fP]] |
|
15 [\fB\-\-help\fP] |
|
16 [\fB\-f\fP|\fB\-\-file\fP[=\fIPATH/Dockerfile\fP]] |
|
17 [\fB\-\-force\-rm\fP] |
|
18 [\fB\-\-isolation\fP[=\fIdefault\fP]] |
|
19 [\fB\-\-no\-cache\fP] |
|
20 [\fB\-\-pull\fP] |
|
21 [\fB\-q\fP|\fB\-\-quiet\fP] |
|
22 [\fB\-\-rm\fP[=\fItrue\fP]] |
|
23 [\fB\-t\fP|\fB\-\-tag\fP[=\fI[]\fP]] |
|
24 [\fB\-m\fP|\fB\-\-memory\fP[=\fIMEMORY\fP]] |
|
25 [\fB\-\-memory\-swap\fP[=\fILIMIT\fP]] |
|
26 [\fB\-\-shm\-size\fP[=\fISHM\-SIZE\fP]] |
|
27 [\fB\-\-cpu\-period\fP[=\fI0\fP]] |
|
28 [\fB\-\-cpu\-quota\fP[=\fI0\fP]] |
|
29 [\fB\-\-cpuset\-cpus\fP[=\fICPUSET\-CPUS\fP]] |
|
30 [\fB\-\-cpuset\-mems\fP[=\fICPUSET\-MEMS\fP]] |
|
31 [\fB\-\-ulimit\fP[=\fI[]\fP]] |
|
32 PATH | URL | \- |
|
33 |
|
34 |
|
35 .SH DESCRIPTION |
|
36 .PP |
|
37 This will read the Dockerfile from the directory specified in \fBPATH\fP. |
|
38 It also sends any other files and directories found in the current |
|
39 directory to the Docker daemon. The contents of this directory would |
|
40 be used by \fBADD\fP commands found within the Dockerfile. |
|
41 |
|
42 .PP |
|
43 Warning, this will send a lot of data to the Docker daemon depending |
|
44 on the contents of the current directory. The build is run by the Docker |
|
45 daemon, not by the CLI, so the whole context must be transferred to the daemon. |
|
46 The Docker CLI reports "Sending build context to Docker daemon" when the context is sent to |
|
47 the daemon. |
|
48 |
|
49 .PP |
|
50 When the URL to a tarball archive or to a single Dockerfile is given, no context is sent from |
|
51 the client to the Docker daemon. In this case, the Dockerfile at the root of the archive and |
|
52 the rest of the archive will get used as the context of the build. When a Git repository is |
|
53 set as the \fBURL\fP, the repository is cloned locally and then sent as the context. |
|
54 |
|
55 |
|
56 .SH OPTIONS |
|
57 .PP |
|
58 \fB\-f\fP, \fB\-\-file\fP=\fIPATH/Dockerfile\fP |
|
59 Path to the Dockerfile to use. If the path is a relative path and you are |
|
60 building from a local directory, then the path must be relative to that |
|
61 directory. If you are building from a remote URL pointing to either a |
|
62 tarball or a Git repository, then the path must be relative to the root of |
|
63 the remote context. In all cases, the file must be within the build context. |
|
64 The default is \fIDockerfile\fP. |
|
65 |
|
66 .PP |
|
67 \fB\-\-build\-arg\fP=\fIvariable\fP |
|
68 name and value of a \fBbuildarg\fP. |
|
69 |
|
70 .PP |
|
71 For example, if you want to pass a value for \fB\fChttp\_proxy\fR, use |
|
72 \fB\fC\-\-build\-arg=http\_proxy="http://some.proxy.url"\fR |
|
73 |
|
74 .PP |
|
75 Users pass these values at build\-time. Docker uses the \fB\fCbuildargs\fR as the |
|
76 environment context for command(s) run via the Dockerfile's \fB\fCRUN\fR instruction |
|
77 or for variable expansion in other Dockerfile instructions. This is not meant |
|
78 for passing secret values. |
|
79 \[la]/reference/builder/#arg\[ra] |
|
80 |
|
81 .PP |
|
82 \fB\-\-force\-rm\fP=\fItrue\fP|\fIfalse\fP |
|
83 Always remove intermediate containers, even after unsuccessful builds. The default is \fIfalse\fP. |
|
84 |
|
85 .PP |
|
86 \fB\-\-isolation\fP="\fIdefault\fP" |
|
87 Isolation specifies the type of isolation technology used by containers. |
|
88 |
|
89 .PP |
|
90 \fB\-\-no\-cache\fP=\fItrue\fP|\fIfalse\fP |
|
91 Do not use cache when building the image. The default is \fIfalse\fP. |
|
92 |
|
93 .PP |
|
94 \fB\-\-help\fP |
|
95 Print usage statement |
|
96 |
|
97 .PP |
|
98 \fB\-\-pull\fP=\fItrue\fP|\fIfalse\fP |
|
99 Always attempt to pull a newer version of the image. The default is \fIfalse\fP. |
|
100 |
|
101 .PP |
|
102 \fB\-q\fP, \fB\-\-quiet\fP=\fItrue\fP|\fIfalse\fP |
|
103 Suppress the build output and print image ID on success. The default is \fIfalse\fP. |
|
104 |
|
105 .PP |
|
106 \fB\-\-rm\fP=\fItrue\fP|\fIfalse\fP |
|
107 Remove intermediate containers after a successful build. The default is \fItrue\fP. |
|
108 |
|
109 .PP |
|
110 \fB\-t\fP, \fB\-\-tag\fP="" |
|
111 Repository names (and optionally with tags) to be applied to the resulting image in case of success. |
|
112 |
|
113 .PP |
|
114 \fB\-m\fP, \fB\-\-memory\fP=\fIMEMORY\fP |
|
115 Memory limit |
|
116 |
|
117 .PP |
|
118 \fB\-\-memory\-swap\fP=\fILIMIT\fP |
|
119 A limit value equal to memory plus swap. Must be used with the \fB\-m\fP |
|
120 (\fB\-\-memory\fP) flag. The swap \fB\fCLIMIT\fR should always be larger than \fB\-m\fP |
|
121 (\fB\-\-memory\fP) value. |
|
122 |
|
123 .PP |
|
124 The format of \fB\fCLIMIT\fR is \fB\fC<number>[<unit>]\fR. Unit can be \fB\fCb\fR (bytes), |
|
125 \fB\fCk\fR (kilobytes), \fB\fCm\fR (megabytes), or \fB\fCg\fR (gigabytes). If you don't specify a |
|
126 unit, \fB\fCb\fR is used. Set LIMIT to \fB\fC\-1\fR to enable unlimited swap. |
|
127 |
|
128 .PP |
|
129 \fB\-\-shm\-size\fP=\fISHM\-SIZE\fP |
|
130 Size of \fB\fC/dev/shm\fR. The format is \fB\fC<number><unit>\fR. \fB\fCnumber\fR must be greater than \fB\fC0\fR. |
|
131 Unit is optional and can be \fB\fCb\fR (bytes), \fB\fCk\fR (kilobytes), \fB\fCm\fR (megabytes), or \fB\fCg\fR (gigabytes). If you omit the unit, the system uses bytes. |
|
132 If you omit the size entirely, the system uses \fB\fC64m\fR. |
|
133 |
|
134 .PP |
|
135 \fB\-\-cpu\-shares\fP=\fI0\fP |
|
136 CPU shares (relative weight). |
|
137 |
|
138 .PP |
|
139 By default, all containers get the same proportion of CPU cycles. |
|
140 CPU shares is a 'relative weight', relative to the default setting of 1024. |
|
141 This default value is defined here: |
|
142 |
|
143 .PP |
|
144 .RS |
|
145 |
|
146 .nf |
|
147 cat /sys/fs/cgroup/cpu/cpu.shares |
|
148 1024 |
|
149 |
|
150 .fi |
|
151 .RE |
|
152 |
|
153 .PP |
|
154 You can change this proportion by adjusting the container's CPU share |
|
155 weighting relative to the weighting of all other running containers. |
|
156 |
|
157 .PP |
|
158 To modify the proportion from the default of 1024, use the \fB\-\-cpu\-shares\fP |
|
159 flag to set the weighting to 2 or higher. |
|
160 |
|
161 .PP |
|
162 .RS |
|
163 |
|
164 .nf |
|
165 Container CPU share Flag |
|
166 {C0} 60% of CPU \-\-cpu\-shares=614 (614 is 60% of 1024) |
|
167 {C1} 40% of CPU \-\-cpu\-shares=410 (410 is 40% of 1024) |
|
168 |
|
169 .fi |
|
170 .RE |
|
171 |
|
172 .PP |
|
173 The proportion is only applied when CPU\-intensive processes are running. |
|
174 When tasks in one container are idle, the other containers can use the |
|
175 left\-over CPU time. The actual amount of CPU time used varies depending on |
|
176 the number of containers running on the system. |
|
177 |
|
178 .PP |
|
179 For example, consider three containers, where one has \fB\-\-cpu\-shares=1024\fP and |
|
180 two others have \fB\-\-cpu\-shares=512\fP. When processes in all three |
|
181 containers attempt to use 100% of CPU, the first container would receive |
|
182 50% of the total CPU time. If you add a fourth container with \fB\-\-cpu\-shares=1024\fP, |
|
183 the first container only gets 33% of the CPU. The remaining containers |
|
184 receive 16.5%, 16.5% and 33% of the CPU. |
|
185 |
|
186 .PP |
|
187 .RS |
|
188 |
|
189 .nf |
|
190 Container CPU share Flag CPU time |
|
191 {C0} 100% \-\-cpu\-shares=1024 33% |
|
192 {C1} 50% \-\-cpu\-shares=512 16.5% |
|
193 {C2} 50% \-\-cpu\-shares=512 16.5% |
|
194 {C4} 100% \-\-cpu\-shares=1024 33% |
|
195 |
|
196 .fi |
|
197 .RE |
|
198 |
|
199 .PP |
|
200 On a multi\-core system, the shares of CPU time are distributed across the CPU |
|
201 cores. Even if a container is limited to less than 100% of CPU time, it can |
|
202 use 100% of each individual CPU core. |
|
203 |
|
204 .PP |
|
205 For example, consider a system with more than three cores. If you start one |
|
206 container \fB{C0}\fP with \fB\-\-cpu\-shares=512\fP running one process, and another container |
|
207 \fB{C1}\fP with \fB\-\-cpu\-shares=1024\fP running two processes, this can result in the following |
|
208 division of CPU shares: |
|
209 |
|
210 .PP |
|
211 .RS |
|
212 |
|
213 .nf |
|
214 PID container CPU CPU share |
|
215 100 {C0} 0 100% of CPU0 |
|
216 101 {C1} 1 100% of CPU1 |
|
217 102 {C1} 2 100% of CPU2 |
|
218 |
|
219 .fi |
|
220 .RE |
|
221 |
|
222 .PP |
|
223 \fB\-\-cpu\-period\fP=\fI0\fP |
|
224 Limit the CPU CFS (Completely Fair Scheduler) period. |
|
225 |
|
226 .PP |
|
227 Limit the container's CPU usage. This flag causes the kernel to restrict the |
|
228 container's CPU usage to the period you specify. |
|
229 |
|
230 .PP |
|
231 \fB\-\-cpu\-quota\fP=\fI0\fP |
|
232 Limit the CPU CFS (Completely Fair Scheduler) quota. |
|
233 |
|
234 .PP |
|
235 By default, containers run with the full CPU resource. This flag causes the |
|
236 kernel to restrict the container's CPU usage to the quota you specify. |
|
237 |
|
238 .PP |
|
239 \fB\-\-cpuset\-cpus\fP=\fICPUSET\-CPUS\fP |
|
240 CPUs in which to allow execution (0\-3, 0,1). |
|
241 |
|
242 .PP |
|
243 \fB\-\-cpuset\-mems\fP=\fICPUSET\-MEMS\fP |
|
244 Memory nodes (MEMs) in which to allow execution (0\-3, 0,1). Only effective on |
|
245 NUMA systems. |
|
246 |
|
247 .PP |
|
248 For example, if you have four memory nodes on your system (0\-3), use \fB\fC\-\-cpuset\-mems=0,1\fR |
|
249 to ensure the processes in your Docker container only use memory from the first |
|
250 two memory nodes. |
|
251 |
|
252 .PP |
|
253 \fB\-\-cgroup\-parent\fP=\fICGROUP\-PARENT\fP |
|
254 Path to \fB\fCcgroups\fR under which the container's \fB\fCcgroup\fR are created. |
|
255 |
|
256 .PP |
|
257 If the path is not absolute, the path is considered relative to the \fB\fCcgroups\fR path of the init process. |
|
258 Cgroups are created if they do not already exist. |
|
259 |
|
260 .PP |
|
261 \fB\-\-ulimit\fP=[] |
|
262 Ulimit options |
|
263 |
|
264 .PP |
|
265 For more information about \fB\fCulimit\fR see |
|
266 \[la]https://docs.docker.com/reference/commandline/run/#setting-ulimits-in-a-container\[ra] |
|
267 |
|
268 |
|
269 .SH EXAMPLES |
|
270 .SH Building an image using a Dockerfile located inside the current directory |
|
271 .PP |
|
272 Docker images can be built using the build command and a Dockerfile: |
|
273 |
|
274 .PP |
|
275 .RS |
|
276 |
|
277 .nf |
|
278 docker build . |
|
279 |
|
280 .fi |
|
281 .RE |
|
282 |
|
283 .PP |
|
284 During the build process Docker creates intermediate images. In order to |
|
285 keep them, you must explicitly set \fB\fC\-\-rm=false\fR. |
|
286 |
|
287 .PP |
|
288 .RS |
|
289 |
|
290 .nf |
|
291 docker build \-\-rm=false . |
|
292 |
|
293 .fi |
|
294 .RE |
|
295 |
|
296 .PP |
|
297 A good practice is to make a sub\-directory with a related name and create |
|
298 the Dockerfile in that directory. For example, a directory called mongo may |
|
299 contain a Dockerfile to create a Docker MongoDB image. Likewise, another |
|
300 directory called httpd may be used to store Dockerfiles for Apache web |
|
301 server images. |
|
302 |
|
303 .PP |
|
304 It is also a good practice to add the files required for the image to the |
|
305 sub\-directory. These files will then be specified with the \fB\fCCOPY\fR or \fB\fCADD\fR |
|
306 instructions in the \fB\fCDockerfile\fR. |
|
307 |
|
308 .PP |
|
309 Note: If you include a tar file (a good practice), then Docker will |
|
310 automatically extract the contents of the tar file specified within the \fB\fCADD\fR |
|
311 instruction into the specified target. |
|
312 |
|
313 .SH Building an image and naming that image |
|
314 .PP |
|
315 A good practice is to give a name to the image you are building. Note that |
|
316 only a\-z0\-9\-\_. should be used for consistency. There are no hard rules here but it is best to give the names consideration. |
|
317 |
|
318 .PP |
|
319 The \fB\-t\fP/\fB\-\-tag\fP flag is used to rename an image. Here are some examples: |
|
320 |
|
321 .PP |
|
322 Though it is not a good practice, image names can be arbitrary: |
|
323 |
|
324 .PP |
|
325 .RS |
|
326 |
|
327 .nf |
|
328 docker build \-t myimage . |
|
329 |
|
330 .fi |
|
331 .RE |
|
332 |
|
333 .PP |
|
334 A better approach is to provide a fully qualified and meaningful repository, |
|
335 name, and tag (where the tag in this context means the qualifier after |
|
336 the ":"). In this example we build a JBoss image for the Fedora repository |
|
337 and give it the version 1.0: |
|
338 |
|
339 .PP |
|
340 .RS |
|
341 |
|
342 .nf |
|
343 docker build \-t fedora/jboss:1.0 . |
|
344 |
|
345 .fi |
|
346 .RE |
|
347 |
|
348 .PP |
|
349 The next example is for the "whenry" user repository and uses Fedora and |
|
350 JBoss and gives it the version 2.1 : |
|
351 |
|
352 .PP |
|
353 .RS |
|
354 |
|
355 .nf |
|
356 docker build \-t whenry/fedora\-jboss:v2.1 . |
|
357 |
|
358 .fi |
|
359 .RE |
|
360 |
|
361 .PP |
|
362 If you do not provide a version tag then Docker will assign \fB\fClatest\fR: |
|
363 |
|
364 .PP |
|
365 .RS |
|
366 |
|
367 .nf |
|
368 docker build \-t whenry/fedora\-jboss . |
|
369 |
|
370 .fi |
|
371 .RE |
|
372 |
|
373 .PP |
|
374 When you list the images, the image above will have the tag \fB\fClatest\fR. |
|
375 |
|
376 .PP |
|
377 You can apply multiple tags to an image. For example, you can apply the \fB\fClatest\fR |
|
378 tag to a newly built image and add another tag that references a specific |
|
379 version. |
|
380 For example, to tag an image both as \fB\fCwhenry/fedora\-jboss:latest\fR and |
|
381 \fB\fCwhenry/fedora\-jboss:v2.1\fR, use the following: |
|
382 |
|
383 .PP |
|
384 .RS |
|
385 |
|
386 .nf |
|
387 docker build \-t whenry/fedora\-jboss:latest \-t whenry/fedora\-jboss:v2.1 . |
|
388 |
|
389 .fi |
|
390 .RE |
|
391 |
|
392 .PP |
|
393 So renaming an image is arbitrary but consideration should be given to |
|
394 a useful convention that makes sense for consumers and should also take |
|
395 into account Docker community conventions. |
|
396 |
|
397 .SH Building an image using a URL |
|
398 .PP |
|
399 This will clone the specified GitHub repository from the URL and use it |
|
400 as context. The Dockerfile at the root of the repository is used as |
|
401 Dockerfile. This only works if the GitHub repository is a dedicated |
|
402 repository. |
|
403 |
|
404 .PP |
|
405 .RS |
|
406 |
|
407 .nf |
|
408 docker build github.com/scollier/purpletest |
|
409 |
|
410 .fi |
|
411 .RE |
|
412 |
|
413 .PP |
|
414 Note: You can set an arbitrary Git repository via the \fB\fCgit://\fR schema. |
|
415 |
|
416 .SH Building an image using a URL to a tarball'ed context |
|
417 .PP |
|
418 This will send the URL itself to the Docker daemon. The daemon will fetch the |
|
419 tarball archive, decompress it and use its contents as the build context. The |
|
420 Dockerfile at the root of the archive and the rest of the archive will get used |
|
421 as the context of the build. If you pass an \fB\-f PATH/Dockerfile\fP option as well, |
|
422 the system will look for that file inside the contents of the tarball. |
|
423 |
|
424 .PP |
|
425 .RS |
|
426 |
|
427 .nf |
|
428 docker build \-f dev/Dockerfile https://10.10.10.1/docker/context.tar.gz |
|
429 |
|
430 .fi |
|
431 .RE |
|
432 |
|
433 .PP |
|
434 Note: supported compression formats are 'xz', 'bzip2', 'gzip' and 'identity' (no compression). |
|
435 |
|
436 .SH Specify isolation technology for container (\-\-isolation) |
|
437 .PP |
|
438 This option is useful in situations where you are running Docker containers on |
|
439 Windows. The \fB\fC\-\-isolation=<value>\fR option sets a container's isolation |
|
440 technology. On Linux, the only supported is the \fB\fCdefault\fR option which uses |
|
441 Linux namespaces. On Microsoft Windows, you can specify these values: |
|
442 .IP \n+[step] |
|
443 |
|
444 \item \fB\fCdefault\fR: Use the value specified by the Docker daemon's \fB\fC\-\-exec\-opt\fR . If the \fB\fCdaemon\fR does not specify an isolation technology, Microsoft Windows uses \fB\fCprocess\fR as its default value. |
|
445 \item \fB\fCprocess\fR: Namespace isolation only. |
|
446 \item \fB\fChyperv\fR: Hyper\-V hypervisor partition\-based isolation. |
|
447 .PP |
|
448 Specifying the \fB\fC\-\-isolation\fR flag without a value is the same as setting \fB\fC\-\-isolation="default"\fR. |
|
449 |
|
450 |
|
451 .SH HISTORY |
|
452 .PP |
|
453 March 2014, Originally compiled by William Henry (whenry at redhat dot com) |
|
454 based on docker.com source material and internal work. |
|
455 June 2014, updated by Sven Dowideit |
|
456 \[la][email protected]\[ra] |
|
457 June 2015, updated by Sally O'Malley |
|
458 \[la][email protected]\[ra] |