run¶
Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
Run a command in a new container
-a, --attach=[] Attach to STDIN, STDOUT or STDERR
--add-host=[] Add a custom host-to-IP mapping (host:ip)
--blkio-weight=0 Block IO weight (relative weight)
--blkio-weight-device=[] Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`)
--cpu-shares=0 CPU shares (relative weight)
--cap-add=[] Add Linux capabilities
--cap-drop=[] Drop Linux capabilities
--cgroup-parent="" Optional parent cgroup for the container
--cidfile="" Write the container ID to the file
--cpu-period=0 Limit CPU CFS (Completely Fair Scheduler) period
--cpu-quota=0 Limit CPU CFS (Completely Fair Scheduler) quota
--cpuset-cpus="" CPUs in which to allow execution (0-3, 0,1)
--cpuset-mems="" Memory nodes (MEMs) in which to allow execution (0-3, 0,1)
-d, --detach Run container in background and print container ID
--detach-keys Specify the escape key sequence used to detach a container
--device=[] Add a host device to the container
--device-read-bps=[] Limit read rate (bytes per second) from a device (e.g., --device-read-bps=/dev/sda:1mb)
--device-read-iops=[] Limit read rate (IO per second) from a device (e.g., --device-read-iops=/dev/sda:1000)
--device-write-bps=[] Limit write rate (bytes per second) to a device (e.g., --device-write-bps=/dev/sda:1mb)
--device-write-iops=[] Limit write rate (IO per second) to a device (e.g., --device-write-bps=/dev/sda:1000)
--disable-content-trust=true Skip image verification
--dns=[] Set custom DNS servers
--dns-opt=[] Set custom DNS options
--dns-search=[] Set custom DNS search domains
-e, --env=[] Set environment variables
--entrypoint="" Overwrite the default ENTRYPOINT of the image
--env-file=[] Read in a file of environment variables
--expose=[] Expose a port or a range of ports
--group-add=[] Add additional groups to run as
-h, --hostname="" Container host name
--help Print usage
-i, --interactive Keep STDIN open even if not attached
--ip="" Container IPv4 address (e.g. 172.30.100.104)
--ip6="" Container IPv6 address (e.g. 2001:db8::33)
--ipc="" IPC namespace to use
--isolation="" Container isolation technology
--kernel-memory="" Kernel memory limit
-l, --label=[] Set metadata on the container (e.g., --label=com.example.key=value)
--label-file=[] Read in a file of labels (EOL delimited)
--link=[] Add link to another container
--log-driver="" Logging driver for container
--log-opt=[] Log driver specific options
-m, --memory="" Memory limit
--mac-address="" Container MAC address (e.g. 92:d0:c6:0a:29:33)
--memory-reservation="" Memory soft limit
--memory-swap="" A positive integer equal to memory plus swap. Specify -1 to enable unlimited swap.
--memory-swappiness="" Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
--name="" Assign a name to the container
--net="bridge" Connect a container to a network
'bridge': create a network stack on the default Docker bridge
'none': no networking
'container:<name|id>': reuse another container's network stack
'host': use the Docker host network stack
'<network-name>|<network-id>': connect to a user-defined network
--net-alias=[] Add network-scoped alias for the container
--oom-kill-disable Whether to disable OOM Killer for the container or not
--oom-score-adj=0 Tune the host's OOM preferences for containers (accepts -1000 to 1000)
-P, --publish-all Publish all exposed ports to random ports
-p, --publish=[] Publish a container's port(s) to the host
--pid="" PID namespace to use
--privileged Give extended privileges to this container
--read-only Mount the container's root filesystem as read only
--restart="no" Restart policy (no, on-failure[:max-retry], always, unless-stopped)
--rm Automatically remove the container when it exits
--shm-size=[] Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`.
--security-opt=[] Security Options
--sig-proxy=true Proxy received signals to the process
--stop-signal="SIGTERM" Signal to stop a container
-t, --tty Allocate a pseudo-TTY
-u, --user="" Username or UID (format: <name|uid>[:<group|gid>])
--ulimit=[] Ulimit options
--uts="" UTS namespace to use
-v, --volume=[host-src:]container-dest[:<options>]
Bind mount a volume. The comma-delimited
`options` are [rw|ro], [z|Z], or
[[r]shared|[r]slave|[r]private]. The
'host-src' is an absolute path or a name
value.
--volume-driver="" Container's volume driver
--volumes-from=[] Mount volumes from the specified container(s)
-w, --workdir="" Working directory inside the container
docker run コマンドは、まず指定されたイメージ上に書き込み可能なコンテナ・レイヤを create （作成）します。それから、指定されたコマンドを使って start （開始）します。この docker run は、 API の /containers/create のあとで /containers/(id)/start を実行するのと同じです。以前に使っていたコンテナは docker start で再起動できます。全てのコンテナを表示するには docker ps -a を使います。
docker run コマンドは、 コンテナの内容を確定するため docker commit コマンドと連携して使えます。
コンテナをネットワークで接続する詳細については、 Docker ネットワーク概要 をご覧ください。
例¶
名前と疑似 TTY の割り当て（–name、-it）¶
$ docker run --name test -it debian
root@d6c0fe130dba:/# exit 13
$ echo $?
13
$ docker ps -a | grep test
d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test
この例は debian:latest イメージを使い、 test という名称のコンテナを実行します。 -it は疑似 TTY（pseudo-TTY）をコンテナの標準入力に接続するよう、 Docker に対して命令します。つまり、コンテナ内でインタラクティブな bash シェルを作成します。例の中で、 bash シェルを終了コード 13 で終了しています。この終了コードは docker run を呼び出したもの（docker）にも送られ、 test コンテナのメタデータに記録されます。
コンテナ ID の取得（–cidfile）
$ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
これはコンテナを作成し、コンソール上に test を表示します。 cidfile フラグは Docker に新しいファイルを作成させ、そこにコンテナ ID を書かせるものです。もしファイルが既に存在している場合、Docker はエラーを返します。 docker run を終了すると、Docker はこのファイルを閉じます。
コンテナの完全能力（–privileged）¶
$ docker run -t -i --rm ubuntu bash
root@bc338942ef20:/# mount -t tmpfs none /mnt
mount: permission denied
これは動作 しません 。デフォルトでは、カーネルに対して潜在的に危険になりうる処理を破棄します。これには cap_sys_admin も含まれます（ファイルシステムのマウントに必要なものです）。しかしながら、 --privileged フラグがあれば、実行できるようになります。
$ docker run -t -i --privileged ubuntu bash
root@50e3f57e16e6:/# mount -t tmpfs none /mnt
root@50e3f57e16e6:/# df -h
Filesystem Size Used Avail Use% Mounted on
none 1.9G 0 1.9G 0% /mnt
--privileged フラグはコンテナに対して 全ての 能力を与えます。また、そのために device cgroup コントローラの制限を昇進します。言い換えると、コンテナはホスト上であらゆる処理が可能となります。このフラグが存在するとき、 Docker の中で Docker を動かすように、特別な使い方ができます。
作業ディレクトリを指定（-w）¶
$ docker run -w /path/to/dir/ -i -t ubuntu pwd
-w は、指定したディレクトリの中でコマンドを実行します。この例では /path/to/dir で実行します。コンテナ内にパスが存在しなければ、作成されます。
tmpfs のマウント（–tmpfs）¶
$ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image
--tmpfs フラグはコンテナに対して空っぽの tmfps をマウントします。このとき、オプション rw 、 noexec 、nosuid 、 size=65536k オプションを指定しています。
ボリュームのマウント（-v, –read-only）¶
$ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd
-v フラグは現在の作業ディレクトリをコンテナ内にマウントします。 -w によって、コマンドは現在の作業用ディレクトリの中で実行されます。ディレクトリとは、 pwd を実行して得られるディレクトリが該当します。このコマンドを組みあわせてコンテナを実行しても、現在の作業ディレクトリの中で実行されるのです。
$ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash
ボリュームとしてマウントするホスト側のディレクトリが存在しなければ、Docker は自動的にホスト上にディレクトリを作成します。先ほどの例では、Docker はコンテナ起動前に /doesnt/exit ディレクトリを作成します。
$ docker run --read-only -v /icanwrite busybox touch /icanwrite here
ボリュームで --read-only を指定して使うことで、コンテナの書き込み可能なファイルを制御できます。 --read-only フラグはコンテナのルート・ファイルシステムを読み込み専用としてマウントし、コンテナで指定したボリューム以外での書き込みを禁止します。
$ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh
Docker Unix ソケットと docker バイナリ（ https://get.docker.com から入手）に対するマウントにより、コンテナはホスト側の Docker デーモンに対して作成や各種操作といった完全アクセスをもたらします。
ポートの公開と露出（-p、–expose）
$ docker run -p 127.0.0.1:80:8080 ubuntu bash
コンテナのポート 8080 を 127.0.0.1 上のポート 80 にバインド（割り当て）します。 Docker ユーザ・ガイド で Docker がどのようにポートを操作するか詳細を説明しています。
$ docker run --expose 80 ubuntu bash
コンテナのポート 80 を露出（expose）しますが、ホストシステム側のインターフェースには公開しません。
環境変数の設定（-e、–env、–env-file）¶
$ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
これはコンテナ内におけるシンプルな（配列ではない）環境変数を設定します。この３つのフラグについて説明します。 -e と --env は環境変数と値を指定する場所です。あるいは、もし = が指定されなければ、現在の環境変数がそのまま送られます（例： ホスト上の $MYVAR1 がコンテナ内の $MYVAR1 にセットされます ）。 = が指定されず、クライアント側の環境変数がない場合は、コンテナ内の環境変数からは削除されます。この３つのフラグ -e 、 --env 、--env-file は何度でも指定できます。
これらの３つのフラグに関係なく、 --env-file が始めに処理され、その後 -e と --env フラグが処理されます。この方法は、必要な時に -e と --env で変数を上書きするために使えます。
$ cat ./env.list
TEST_FOO=BAR
$ docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO
TEST_FOO=This is a test
--env-file フラグは、ファイル名を引数として使います。ファイルの内容は、それぞれの行が VAR=VAL の形式であり、 --env のようなものです。コメント行は、行頭に # を付けます。
$ cat ./env.list
TEST_FOO=BAR
# this is a comment
TEST_APP_DEST_HOST=10.10.0.127
TEST_APP_DEST_PORT=8888
_TEST_BAR=FOO
TEST_APP_42=magic
helloWorld=true
123qwe=bar
org.spring.config=something
# pass through this variable from the caller
TEST_PASSTHROUGH
$ TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=5198e0745561
TEST_FOO=BAR
TEST_APP_DEST_HOST=10.10.0.127
TEST_APP_DEST_PORT=8888
_TEST_BAR=FOO
TEST_APP_42=magic
helloWorld=true
TEST_PASSTHROUGH=howdy
HOME=/root
123qwe=bar
org.spring.config=something
$ docker run --env-file ./env.list busybox env
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
HOSTNAME=5198e0745561
TEST_FOO=BAR
TEST_APP_DEST_HOST=10.10.0.127
TEST_APP_DEST_PORT=8888
_TEST_BAR=FOO
TEST_APP_42=magic
helloWorld=true
TEST_PASSTHROUGH=
HOME=/root
123qwe=bar
org.spring.config=something
メタデータをコンテナに設定（-l、–label、–label-file）¶
ラベルとは key=value のペアであり、コンテナにメタデータを提供します。コンテナに２つのラベルをラベル付けします：
$ docker run -l my-label --label com.example.foo=bar ubuntu bash
my-label キーが値を指定しなければ、対象のラベルは空の文字列（ "" ）がデフォルトで割り当てられます。複数のラベルを追加するには、ラベルのフラグ（ -l か --label ）を繰り返します。
key=value はラベル値を上書きしないよう、ユニークにする必要があります。ラベルが値の違う特定のキーを指定した場合は、以前の値が新しい値に上書きされます。Docker は最新の key=value 指定を使います。
--label-file フラグはファイルから複数のラベルを読み込みます。ラベルとしての句切りは各行の EOL マークが現れるまでです。
$ docker run --label-file ./labels ubuntu bash
label-file の書式は、環境変数の読み込み書式と似ています（環境変数との違いは、ラベルはコンテナ内で実行中のプロセスから見えません）。以下は label-file 形式の記述例です。
com.example.label1="a label"
# これはコメントです
com.example.label2=another\ label
com.example.label3
複数のラベル用ファイルを読み込むには、複数回 --label-file フラグを使います。
ラベルの動作に関する詳しい情報は、Docker ユーザ・ガイドの Label - Docker でカスタム・メタデータを使う をご覧ください。
コンテナをネットワークに接続（–net）¶
コンテナ実行時に --net フラグを付けるとネットワークに接続します。次の例は busybox コンテナに my-net ネットワークを追加します。
$ docker run -itd --net=my-net busybox
また、ユーザ定義ネットワーク上でコンテナを起動時、 --ip と --ipv6 フラグを使い、コンテナに対して IP アドレスを割り当て可能です。
$ docker run -itd --net=my-net --ip=10.10.9.75 busybox
実行中のコンテナに対してネットワークを追加する時は、 docker network connect サブコマンドを使います。
同じネットワークに複数のコンテナを接続できます。接続すると、コンテナは別のコンテナの IP アドレスや名前で簡単に通信できるようになります。 overlay ネットワークやカスタム・プラグインは複数のホストへの接続をサポートしています。異なった Docker エンジンが起動していても、コンテナが同じマルチホスト・ネットワーク上であれば、相互に通信できます。
注釈
サービス・ディスカバリはデフォルトの bridge ネットワークで利用できません。そのため、デフォルトでは、コンテナは IP アドレスで通信します。コンテナ名で通信するには、リンクされている必要があります。
ネットワークからコンテナを切断するには、 docker network disconnect コマンドを使います。
コンテナからボリュームをマウント（–volumes-from）¶
$ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd
--volumes-from フラグは、参照するコンテナで定義されたボリュームをマウントできます。コンテナは --volumes-from 引数を何度も指定できます。コンテナ ID はオプションで末尾に :ro か :rw を指定し、読み込み専用か読み書き可能なモードを個々に指定できます。デフォルトでは、ボリュームは参照しているコンテナと同じモード（読み書き可能か読み込み専用）です。
SELinux のようなラベリング・システムは、コンテナ内にボリューム内容をマウントするにあたり、適切なラベルを必要とします。ラベルがなければ、対象の領域を使ったコンテナの中では、セキュリティ・システムがプロセスの実行を阻止します。デフォルトでは、Docker は OS によってセットされるラベルを変更しません。
コンテナ内にあるラベルを変更するには、ボリュームのマウントに :z か :Z の２つを末尾に追加できます。これらのサフィックスは、Docker に対して共有ボリューム上のファイル・オブジェクトに対して再度ラベル付けするように伝えます。その結果、Docker は共有コンテントのラベルを使ってラベル付けします。共有ボリュームのラベルは、全てのコンテナを読み書き可能なコンテントにします。 Z オプションは Docker に対してプライベートな共有されないラベルであると伝えます。現在のコンテナのみ、プライベート・ボリュームが使えます。
STDIN・STDOUT・STDERRのアタッチ（-a）¶
-a フラグは docker run 時にコンテナの STDIN 、 STDOUT 、 STDERR をバインドします。これにより、必要に応じて入出力を操作できるようにします。
$ echo "test" | docker run -i -a stdin ubuntu cat -
これはコンテナの中にデータをパイプし、コンテナ ID をコンテナの STDIN にアタッチして表示します。
$ docker run -a stderr ubuntu echo test
これはエラーでない限り、何も表示しません。これはコンテナの STDIRR にしかアタッチしていないためです。コンテナのログに STDERR と STDOUT が書き込まれます。
$ cat somefile | docker run -i -a stdin mybuilder dobuild
これはファイルの内容をコンテナにパイプし、構築するものです。構築が完了するとコンテナ ID が表示され、構築ログは docker logs で取得できます。これはファイルや何かをコンテナ内にパイプし、コンテナで処理が終わるとコンテナ ID を表示するので便利です。
ホスト・デバイスをコンテナに追加（–device）¶
$ docker run --device=/dev/sdc:/dev/xvdc --device=/dev/sdd --device=/dev/zero:/dev/nulo -i -t ubuntu ls -l /dev/{xvdc,sdd,nulo}
brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc
brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd
crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/nulo
しばしばデバイスをコンテナに直接晒す必要があります。 --device オプションは、これを可能にします。例えば、特定のブロック・ストレージ・デバイス、ループ・デバイス、オーディオ・デバイスを使うにあたり、コンテナに特権を与えなくても（ --privileged フラグを使わずに ）追加でき、アプリケーションが直接使えるようになります。
デフォルトでは、コンテナは read 、write 、 mknod を各デバイスに指定できます。各 --device フラグのオプション設定で、３つの :rwm を利用できます。
$ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc
Command (m for help): q
$ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc
You will not be able to write the partition table.
Command (m for help): q
$ docker run --device=/dev/sda:/dev/xvdc:rw -it ubuntu fdisk /dev/xvdc
Command (m for help): q
$ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc
fdisk: unable to open /dev/xvdc: Operation not permitted
注釈
--device はエフェメラルな（短命な）デバイスでは使うべきではありません。信頼できないコンテナが --device を追加しようとしても、ブロック・デバイスは除外されるでしょう。
再起動ポリシー¶
Docker の --restart はコンテナの 再起動ポリシー を指定します。再起動ポリシーは、コンテナの終了後、Docker デーモンが再起動するかどうかを管理します。Docker は次の再起動ポリシーをサポートしています。
| ポリシー | 結果 |
|---|---|
| no | 終了してもコンテナを自動的に再起動しません。これがデフォルトです。 |
| on-failure [:最大リトライ数] | コンテナが 0 以外のステータスで終了すると、再起動します。オプションで Docker デーモンが何度再起動するかを指定できます。 |
| always | 終了コードの状態に関わらず、常に再起動します。always を指定すると、 Docker デーモンは無制限に再起動を試みます。また、現在の状況に関わらず、デーモンの起動時にもコンテナの起動を試みます。 |
| unless-stopped | 終了コードの状態に関わらず、常に再起動します。しかし、以前に停止した状態であれば、Docker デーモンの起動時にコンテナを開始しません。 |
$ docker run --restart=always redis
これは redis コンテナを再起動ポリシー always で起動するものであり、コンテナが終了すると Docker がコンテナを再起動します。
再起動ポリシーに関するより詳しい情報は、 Docker run リファレンス・ページ の 再起動ポリシー（–restart） をご覧ください。
コンテナの host ファイルにエントリ追加（–add-host）¶
--add-host フラグを使い、コンテナの /etc/hosts ファイルに１つもしくは複数のホストを追加できます。次の例はホスト名 docker に静的なアドレスを追加しています。
$ docker run --add-host=docker:10.180.0.1 --rm -it debian
$$ ping docker
PING docker (10.180.0.1): 48 data bytes
56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms
56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms
^C--- docker ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms
時々、コンテナ内から Docker ホストに対して接続する必要があります。接続のためには、 --add-host フラグをコンテナに使い、Docker ホストの IP アドレスを与えます。ホスト側の IP アドレスを確認するには、 ip addr show コマンドを使います。
コンテナどの IPv4 ないし IPv6 ネットワークを使っているかは、 ip addr show の結果次第です。次のフラグは、ネットワーク・デバイス eth0 の IPv4 アドレスを指定します。
$ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print \$2}' | cut -d / -f 1`
$ docker run --add-host=docker:${HOSTIP} --rm -it debian
IPv6 は -4 フラグにかわって -6 を指定します。他のネットワーク・デバイスの場合は eth0 を適切なデバイス名に置き換えます（例えば docker0 ブリッジ・デバイス ）。
コンテナ内の ulimits を指定（–ulimit）¶
コンテナ内で ulimit 設定をするには追加特権が必要であり、デフォルトのコンテナでは指定できません。そこで --ulimit フラグを指定できます。 --ulimit はソフト・リミットとハード・リミットを指定できます。 <type>=<ソフト・リミット>[:<ハード・リミット>] の形式です。例：
$ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
1024
注釈
ハード・リミット を指定しなければ、 ソフト・リミット が両方の値として使われます。 ulimits が設定されなければ、デーモンのデフォルトの ulimits が継承されます。 as オプションは無効化されました。言い換えると、次のようなスクリプトはサポートされていません： $ docker run -it --ulimit as=1024 fedora /bin/bash
設定されると適切な syscall が送信されます。Docker は転送に何ら介在しません。値が設定された時のみ処理されます。
nproc を使うには¶
ulimit フラグに nproc を設定するときは、 nproc は Linux が利用者が利用可能な最大プロセス数をセットするものであり、コンテナに対してではないので注意してください。次の例は、 daemon ユーザとして４つのコンテナを起動します。
docker run -d -u daemon --ulimit nproc=3 busybox top
docker run -d -u daemon --ulimit nproc=3 busybox top
docker run -d -u daemon --ulimit nproc=3 busybox top
docker run -d -u daemon --ulimit nproc=3 busybox top
４番目のコンテナは失敗し、“[8] System error: resource temporarily unavailable” エラーを表示します。これが失敗するのは、実行時に nproc=3 を指定しているので、３つのコンテナが起動してしまうと、 daemon ユーザに指定されたプロセスの上限（quota）に達してしまうからです。
コンテナをシグナルで停止¶
--stop-signal フラグは、システムコールのシグナルを設定します。これは、コンテナを終了するときに送るものです。このシグナルはカーネルの syscall テーブルにある適切な数値と一致する必要があります。例えば 9 や、SIGNAME のような形式のシグナル名（例：SIGKILL）です。