diff --git a/man/docker-build.1.md b/man/docker-build.1.md index bcf8ed2f..4bfadcbe 100644 --- a/man/docker-build.1.md +++ b/man/docker-build.1.md @@ -39,8 +39,9 @@ The Docker CLI reports "Sending build context to Docker daemon" when the context the daemon. When the URL to a tarball archive or to a single Dockerfile is given, no context is sent from -the client to the Docker daemon. When a Git repository is set as the **URL**, the repository is -cloned locally and then sent as the context. +the client to the Docker daemon. In this case, the Dockerfile at the root of the archive and +the rest of the archive will get used as the context of the build. When a Git repository is +set as the **URL**, the repository is cloned locally and then sent as the context. # OPTIONS **-f**, **--file**=*PATH/Dockerfile* @@ -92,32 +93,50 @@ cloned locally and then sent as the context. **-c**, **--cpu-shares**=*0* CPU shares (relative weight). - By default, all containers get the same proportion of CPU cycles. You can - change this proportion by adjusting the container's CPU share weighting - relative to the weighting of all other running containers. + By default, all containers get the same proportion of CPU cycles. + CPU shares is a 'relative weight', relative to the default setting of 1024. + This default value is defined here: + ``` + cat /sys/fs/cgroup/cpu/cpu.shares + 1024 + ``` + You can change this proportion by adjusting the container's CPU share + weighting relative to the weighting of all other running containers. - To modify the proportion from the default of 1024, use the **-c** or - **--cpu-shares** flag to set the weighting to 2 or higher. + To modify the proportion from the default of 1024, use the **--cpu-shares** + flag to set the weighting to 2 or higher. + + Container CPU share Flag + {C0} 60% of CPU --cpu-shares=614 (614 is 60% of 1024) + {C1} 40% of CPU --cpu-shares=410 (410 is 40% of 1024) The proportion is only applied when CPU-intensive processes are running. When tasks in one container are idle, the other containers can use the left-over CPU time. The actual amount of CPU time used varies depending on the number of containers running on the system. - For example, consider three containers, one has a cpu-share of 1024 and - two others have a cpu-share setting of 512. When processes in all three + For example, consider three containers, where one has **--cpu-shares=1024** and + two others have **--cpu-shares=512**. When processes in all three containers attempt to use 100% of CPU, the first container would receive - 50% of the total CPU time. If you add a fourth container with a cpu-share - of 1024, the first container only gets 33% of the CPU. The remaining containers + 50% of the total CPU time. If you add a fourth container with **--cpu-shares=1024**, + the first container only gets 33% of the CPU. The remaining containers receive 16.5%, 16.5% and 33% of the CPU. + + Container CPU share Flag CPU time + {C0} 100% --cpu-shares=1024 33% + {C1} 50% --cpu-shares=512 16.5% + {C2} 50% --cpu-shares=512 16.5% + {C4} 100% --cpu-shares=1024 33% + + On a multi-core system, the shares of CPU time are distributed across the CPU cores. Even if a container is limited to less than 100% of CPU time, it can use 100% of each individual CPU core. For example, consider a system with more than three cores. If you start one - container **{C0}** with **-c=512** running one process, and another container - **{C1}** with **-c=1024** running two processes, this can result in the following + container **{C0}** with **--cpu-shares=512** running one process, and another container + **{C1}** with **--cpu-shares=1024** running two processes, this can result in the following division of CPU shares: PID container CPU CPU share @@ -141,7 +160,7 @@ kernel to restrict the container's CPU usage to the quota you specify. CPUs in which to allow execution (0-3, 0,1). **--cpuset-mems**=*CPUSET-MEMS* - Memory nodes (MEMs) in which to allow execution (-1-3, 0,1). Only effective on + Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. For example, if you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1` @@ -203,16 +222,16 @@ name, and tag (where the tag in this context means the qualifier after the ":"). In this example we build a JBoss image for the Fedora repository and give it the version 1.0: - docker build -t fedora/jboss:1.0 + docker build -t fedora/jboss:1.0 . The next example is for the "whenry" user repository and uses Fedora and JBoss and gives it the version 2.1 : - docker build -t whenry/fedora-jboss:v2.1 + docker build -t whenry/fedora-jboss:v2.1 . If you do not provide a version tag then Docker will assign `latest`: - docker build -t whenry/fedora-jboss + docker build -t whenry/fedora-jboss . When you list the images, the image above will have the tag `latest`. @@ -228,16 +247,17 @@ as context. The Dockerfile at the root of the repository is used as Dockerfile. This only works if the GitHub repository is a dedicated repository. - docker build github.com/scollier/Fedora-Dockerfiles/tree/master/apache + docker build github.com/scollier/purpletest Note: You can set an arbitrary Git repository via the `git://` schema. ## Building an image using a URL to a tarball'ed context This will send the URL itself to the Docker daemon. The daemon will fetch the -tarball archive, decompress it and use its contents as the build context. If you -pass an *-f PATH/Dockerfile* option as well, the system will look for that file -inside the contents of the tarball. +tarball archive, decompress it and use its contents as the build context. The +Dockerfile at the root of the archive and the rest of the archive will get used +as the context of the build. If you pass an **-f PATH/Dockerfile** option as well, +the system will look for that file inside the contents of the tarball. docker build -f dev/Dockerfile https://10.10.10.1/docker/context.tar.gz