build¶

使い方: docker build [オプション] パス | URL | -

パスにあるソースコードから新しいイメージを構築

  --build-arg=[]                  構築時の変数を指定
  --cpu-shares                    CPU 共有 (相対ウエイト)
  --cgroup-parent=""              コンテナ用のオプション親 cgroup
  --cpu-period=0                  CPU CFS (Completely Fair Scheduler) 間隔の制限
  --cpu-quota=0                   CPU CFS (Completely Fair Scheduler) クォータの制限
  --cpuset-cpus=""                実行時に許可する CPU。例 `0-3`, `0,1`
  --cpuset-mems=""                実行時に許可するメモリ。例 `0-3`, `0,1`
  --disable-content-trust=true    イメージの認証をスキップ
  -f, --file=""                   Dockerfileの名前 (デフォルトは 'PATH/Dockerfile')
  --force-rm                      常に中間コンテナを削除
  --help                          使い方を表示
  --isolation=""                  コンテナの隔離（独立）技術
  --label=[]                      イメージ用のメタデータを指定
  -m, --memory=""                 構築コンテナのメモリ上限を指定
  --memory-swap=""                整数値の指定はメモリにスワップ値を追加。-1は無制限スワップを有効化
  --no-cache                      イメージ構築時にキャッシュを使わない
  --pull                          常に新しいイメージのダウンロードを試みる
  -q, --quiet                     構築時の表示を抑制し、成功時はイメージ ID を表示
  --rm=true                       構築に成功したら、全ての中間コンテナを削除
  --shm-size=[]                   `/dev/shm` のサイズ。書式は `<数値><単位>`。 `数値` は `0` 以上。単位は `b` (bytes)、`k` (kilobytes)、 `m` (megabytes)、 `g` (gigabytes) のどれか。単位を省略するとバイトになる。サイズを省略すると `64m` になる。
  -t, --tag=[]                    '名前:タグ' 形式で名前とオプションのタグを指定
  --ulimit=[]                     Ulimit オプション

Docker イメージは Dockerfile と「コンテクスト」（context）を使って構築します。構築時のコンテクストとは、特定の パス や 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

Windows 上の Powershell では、次のように実行します：

Get-Content Dockerfile | docker build -

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 になります。詳細は有効なタグについてをご覧ください。

イメージに対して複数のタグを適用できます。例えば、最も新しい構築イメージに対して latest タグを付け、他にもバージョンを参照用タグも付けられます。例えば、イメージに対して whenry/fedora-jboss:latest と whenry/fedora-jboss:v2.1 をタグ付けするには、次のコマンドを実行します。

$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1 .

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 build コマンドは同じことをしています。いずれの 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 のように使えますが、中間ファイルや最終的なイメージでは一定ではありません。

フラグ使用時、Dockerfile で構築プロセスが進行しても ARG 行は画面には表示されません。

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

参考

build: https://docs.docker.com/engine/reference/commandline/build/