build¶

Usage: docker build [OPTIONS] PATH | URL | -

Build a new image from the source code at PATH

  --build-arg=[]                  Set build-time variables
  --cpu-shares                    CPU Shares (relative weight)
  --cgroup-parent=""              Optional parent cgroup for the container
  --cpu-period=0                  Limit the CPU CFS (Completely Fair Scheduler) period
  --cpu-quota=0                   Limit the CPU CFS (Completely Fair Scheduler) quota
  --cpuset-cpus=""                CPUs in which to allow execution, e.g. `0-3`, `0,1`
  --cpuset-mems=""                MEMs in which to allow execution, e.g. `0-3`, `0,1`
  --disable-content-trust=true    Skip image verification
  -f, --file=""                   Name of the Dockerfile (Default is 'PATH/Dockerfile')
  --force-rm=false                Always remove intermediate containers
  --help=false                    Print usage
  -m, --memory=""                 Memory limit for all build containers
  --memory-swap=""                Total memory (memory + swap), `-1` to disable swap
  --no-cache=false                Do not use cache when building the image
  --pull=false                    Always attempt to pull a newer version of the image
  -q, --quiet=false               Suppress the verbose output generated by the containers
  --rm=true                       Remove intermediate containers after a successful build
  -t, --tag=""                    Repository name (and optionally a tag) for the image
  --ulimit=[]                     Ulimit options

Docker イメージは Dockerfile と「コンテキスト」（context）を使って構築します。構築のコンテキストとは、特定の PATH や URL の場所にあるファイルのことです。構築の手順では、対象のコンテキスト内のファイルを参照できます。

URL パラメータは Git レポジトリの場所を指定できます。つまり、レポジトリの内容をコンテキストとして構築できます。システムでレポジトリの再帰的なクローンを作成するには git clone --depth 1 --recursive コマンドを使います。このコマンドはローカルホスト上の一時ディレクトリで実行されます。コマンドが成功すると、ディレクトリは Docker デーモンにコンテキストとして送信されます。ローカルのクローンであれば、ローカルなユーザ認証や VPN などを使うプライベートなレポジトリへのアクセスも可能にします。

Git の URL は、コロン : をコンテキストのセクションを分割する設定に使えます。１つめの場所は Git が調査用に参照します。これはブランチ、タグ、コミット SHA が使えます。２つめの場所はレポジトリ内にあるサブディレクトリであり、構築時のコンテキストとして使われます。

例えば、 container``ブランチを ``docker という名称のディレクトリでコマンドを実行するには：

$ docker build https://github.com/docker/rootfs.git#container:docker

次の表は構築コンテキストで有効なサフィックスの一覧です。

構築構文のサフィックス	コミットに利用	構築コンテキストに使用
`myrepo.git`	`refs/heads/master`	`/`
`myrepo.git#mytag`	`refs/heads/mytag`	`/`
`myrepo.git#mybranch`	`refs/heads/mybranch`	`/`
`myrepo.git#abcdef`	`sha1 = abcdef`	`/`
`myrepo.git#:myfolder`	`refs/heads/master`	`/myfolder`
`myrepo.git#master:myfolder`	`refs/heads/master`	`/myfolder`
`myrepo.git#mytag:myfolder`	`refs/heads/mytag`	`/myfolder`
`myrepo.git#mybranch:myfolder`	`refs/heads/mybranch`	`/myfolder`
`myrepo.git#abcdef:myfolder`	`sha1 = abcdef`	`/myfolder`

コンテキストを指定する代わりに、Dockerfile の URL や STDIN （標準入力）のファイルをパイプできます。 STDIN から Dockerfile をパイプするには：

docker build - < Dockerfile

STDIN や URL を指定すると、システムはコンテキストを Dockerfile という名称のファイルに入れられるため、 -f および --file オプションは無視されミズ合う。今回の例では、コンテキストは指定していません。

デフォルトの docker build コマンドは、構築コンテキストのルートにある Dockerfile を探します。 -f および --file オプションは、内容が含まれている代替ファイルのパスを指定します。これは複数のファイル群を使って、複数の構築をする場合に便利です。パスには構築コンテキスト用のファイルが必要です。相対パスを指定するときは、現在のディレクトリに対する相対パスを指定する必要があります。

多くの場合、それぞれの Dockerfile を空のディレクトに入れるのがベストな方法です。それから、ディレクトリ内には Dockerfile の構築に必要なものしか置きません。構築のパフォーマンスを向上するには、 .dockerignore ファイルを設置し、特定のファイルやディレクトリを除外する設定が使えます。このファイルを作るための詳しい方法は、 .dockerignore ファイルをご覧ください。

Docker クライアントがデーモンと通信できなければ、構築はキャンセルされます。Docker クライアントで ctrl-c を使うか、何らかの理由により Docker クライアントが停止されても、構築は中断されます。

注釈

現時点で中断できるのは構築を「実行中」の段階のみです（pull の中断が実装されるまで）。

戻り値（リターンコード）¶

構築に成功すると、成功の 0 という戻り値を返します。構築に失敗すると、ゼロ以外の戻り値を返しミズ合う。

失敗理由に関する情報は STDERR に表示されます。

$ docker build -t fail .
Sending build context to Docker daemon 2.048 kB
Sending build context to Docker daemon
Step 1 : FROM busybox
 ---> 4986bf8c1536
Step 2 : RUN exit 13
 ---> Running in e26670ec7a0a
INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13
$ echo $?
1

こちらもご覧ください：

Dockerfile リファレンス

例¶

PATH で構築¶

$ docker build .
Uploading context 10240 bytes
Step 1 : FROM busybox
Pulling repository busybox
 ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
Step 2 : RUN ls -lh /
 ---> Running in 9c9e81692ae9
total 24
drwxr-xr-x    2 root     root        4.0K Mar 12  2013 bin
drwxr-xr-x    5 root     root        4.0K Oct 19 00:19 dev
drwxr-xr-x    2 root     root        4.0K Oct 19 00:19 etc
drwxr-xr-x    2 root     root        4.0K Nov 15 23:34 lib
lrwxrwxrwx    1 root     root           3 Mar 12  2013 lib64 -> lib
dr-xr-xr-x  116 root     root           0 Nov 15 23:34 proc
lrwxrwxrwx    1 root     root           3 Mar 12  2013 sbin -> bin
dr-xr-xr-x   13 root     root           0 Nov 15 23:34 sys
drwxr-xr-x    2 root     root        4.0K Mar 12  2013 tmp
drwxr-xr-x    2 root     root        4.0K Nov 15 23:34 usr
 ---> b35f4035db3f
Step 3 : CMD echo Hello world
 ---> Running in 02071fceb21b
 ---> f52f38b7823e
Successfully built f52f38b7823e
Removing intermediate container 9c9e81692ae9
Removing intermediate container 02071fceb21b

こに例では PATH に . を指定しています。このローカルディレクトリにある全てのファイルは tar 化され、Docker デーモンに送られます。 PATH が示すのは、Docker デーモンが構築時に使う「コンテキスト」（内容物）としてのファイルを見つけるための場所です。デーモンはリモート上のマシンでも操作できるのを思い出してください。これは、クライアント側（ docker build コマンドを実行した場所）では Dockerfile は何らパース（解析）されません。つまり、 PATH に含まれる すべて のファイルが送信されるだけでなく、Dockerfile の ADD 命令で追加した場所も含みます。

ローカルのマシンから Docker デーモンにコンテキストを送信時、docker クライアントには「Sending build context（構築コンテキストの送信中）」メッセージが表示されます。

構築が完了しても中間コンテナをそのまま維持したい場合は、 --rm=false の指定が必要です。こちらを指定すると構築キャッシュに何もしません。

URL で構築¶

$ docker build github.com/creack/docker-firefox

これは GitHub レポジトリのクローンを作成し、クローンしたレポジトリをコンテキストとして利用します。レポジトリのルートにある Dockerfile を、構築時の Dockerfile として使います。 git:// や git@ など、その他の Git レポジトリのスキーマを使っても指定可能です。

- で構築¶

$ docker build - < Dockerfile

これはコンテキストを使わずに STDIN から Dockerfile を読み込みます。コンテキストが無く、内容物のないローカルのディレクトリが Docker デーモンに送信されます。コンテキストがありませんので、 Dockerfile の ADD はリモートの URL の参照に使えます。

$ docker build - < context.tar.gz

これは STDIN から圧縮されたコンテキストを読み込み、イメージを構築しています。サポートしているフォーマットは、bzip2、gzip、xz です。

.dockerignore の使い方¶

$ docker build .
Uploading context 18.829 MB
Uploading context
Step 1 : FROM busybox
 ---> 769b9341d937
Step 2 : CMD echo Hello world
 ---> Using cache
 ---> 99cc1ad10469
Successfully built 99cc1ad10469
$ echo ".git" > .dockerignore
$ docker build .
Uploading context  6.76 MB
Uploading context
Step 1 : FROM busybox
 ---> 769b9341d937
Step 2 : CMD echo Hello world
 ---> Using cache
 ---> 99cc1ad10469
Successfully built 99cc1ad10469

この例で表示しているのは、 .dockerignore ファイルを使い、コンテキストから .git ディレクトリを除外しています。この効果により、アップロードされるコンテキストの容量を小さくしています。構築時のリファレンス .dockerignore ファイルの作成に、より詳しい情報があります。

イメージのタグ（-t）¶

$ docker build -t vieux/apache:2.0 .

これまでの例のように構築していますが、作成されるイメージに対してタグ付けをしています。レポジトリ名は vieux/apache になり、タグは 2.0 にないます。

Dockerfile の指定（-f）¶

$ docker build -f Dockerfile.debug .

構築時の命令に Dockerfile ではなく、 Dockerfile.debug を使うように呼び出しています。

$ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug .
$ docker build -f dockerfiles/Dockerfile.prod  -t myapp_prod .

上記のコマンドは、どちらも現在のディレクトリにあるコンテント（ . で場所を指定）を使い構築するものです。デバッグ用とプロダクション用で別々の Dockerfile を使いますが、コンテキストは同じです。

$ cd /home/me/myapp/some/dir/really/deep
$ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp
$ docker build -f ../../../../dockerfiles/debug /home/me/myapp

２つの docker bulid コマンドは同じ事をしています。いずれの Dockerfile にも debug ファイルが含まれており、構築コンテキストのルートとして /home/me/myapp を使います。なお注意点として、 debug は構築コンテキストのサブディレクトリにあるもので、先ほどのコマンドライン上では指定の必要がありませんでした。

注釈

docker build が no such file or directory エラーを返すのは、アップロードすべきコンテキストとしてのファイルやディレクトリが存在しない時です。これは、コンテキストが存在しないか、指定したファイルがホストシステム上に存在していない可能性があります。コンテキストははカレント・ディレクトリ（と、その子ディレクトリ）のみに安全上の理由で制限されています。これはリモートの Docker ホスト上でも、繰り返し構築できるようにするためです。これが ADD ../file が動作しない理由でもあります。

親 cgroup のオプション（–cgroup-parent）¶

docker build に --cgroup-parent オプションを付けて構築すると、構築時の docker run 実行時に適切なフラグを付けて実行します。

コンテナの ulimit をセット（–ulimit）¶

docker build に --ulimit オプションを付けて実行すると、コンテナの構築ステップを開始する時、都度 --ulimit フラグの値を設定します。

構築時の変数を指定（–build-arg）¶

Dockerfile の``ENV`` 命令を使い、変数を定義できます。これらの値は構築時に一定のものです。しかし、一定の値が必要でない場合もあります。ユーザがイメージを構築するホストによっては、依存性に対する変数が必要になるかもしれません。

良い例が http_proxy や中間ファイルの取得に使うソースのバージョン指定です。 ARG 命令は Dockerfile の作者が定義する値であり、ユーザが構築時に --build-arg フラグを指定できます。

$ docker build --build-arg HTTP_PROXY=http://10.20.30.2:1234 .

このフラグを使うことで、構築時の変数が Dockerfile の RUN 命令で通常の環境変数のように扱えます。それだけでなく、これらの値は ENV のように使えますが、中間ファイルや最終的なイメージでは一定ではありません。

ARG と ENV 命令の詳細については、 Dockerfile リファレンス をご覧ください。