前回は、Docker の「イメージ」と「コンテナ」を分けて整理しました。

今回は Docker Compose を使って、コンテナの設定をファイルにまとめます。

Docker Compose を使うと、docker run に長く書いていた指定を compose.yaml に書けます。

この記事では、公式で優先されているファイル名に合わせて compose.yaml を使います。

Docker Compose とは

Docker Compose は、複数のコンテナや、その起動設定をまとめて扱うための Docker の機能です。

通常の docker run では、コンテナを起動するたびにオプションをコマンドに書きます。

たとえば、次のような指定です。

  • どのイメージを使うか
  • コンテナ名をどうするか
  • ポートをどうつなぐか
  • 環境変数をどう渡すか
  • ボリュームをどうマウントするか

Docker Compose では、これらの設定を compose.yaml に書きます。

そのうえで、次のようなコマンドでまとめて操作できます。

  • docker compose up: コンテナを作って起動する
  • docker compose ps: Compose で起動したコンテナを見る
  • docker compose exec: 起動中のコンテナに入る
  • docker compose down: Compose で作ったコンテナを削除する

1つのコンテナだけでも使えますが、Web アプリとデータベースのように複数のコンテナをまとめて起動したいときに特に便利です。

Docker Compose を使えるか確認する

まず、Docker Compose が使えるか確認します。

bash
docker compose version

バージョンが表示されれば、Docker Compose を使える状態です。

Ubuntu で Docker Compose プラグインが入っていない場合は、次のパッケージをインストールします。

bash
sudo apt install docker-compose-plugin

インストール後、もう一度確認します。

bash
docker compose version

ここで使っているのは、docker compose という Docker CLI のサブコマンドです。古い記事では docker-compose という別コマンドが出てくることがありますが、この記事では現在よく使われる docker compose で説明します。

compose.yaml とは

compose.yaml は、Docker Compose が読む設定ファイルです。

Dockerfile とは役割が違います。

  • Dockerfile: イメージの作り方を書く
  • compose.yaml: どのイメージを使い、どんなコンテナとして起動するかを書く

たとえば、次のような docker run コマンドがあるとします。

bash
docker run --name ubuntu-test -it ubuntu:24.04 bash

このコマンドでは、使うイメージ、コンテナ名、対話操作の指定、起動するコマンドをまとめて指定しています。

Compose では、それらを compose.yaml に書きます。

yaml
services:
  ubuntu-test:
    image: ubuntu:24.04
    container_name: ubuntu-compose-test
    tty: true
    stdin_open: true

対応関係は次の通りです。

  • services: 起動したいコンテナのまとまりを書く場所
  • ubuntu-test: Compose 内で使うサービス名
  • image: ubuntu:24.04: 使うイメージ
  • container_name: ubuntu-compose-test: 作成するコンテナ名
  • tty: true: ターミナル操作できるようにする
  • stdin_open: true: 標準入力を開いたままにする

compose.yaml を書いただけでは、まだイメージもコンテナも作られません。実際に作成や起動をするのは、docker compose up や docker compose build を実行したときです。

ファイル名について

Docker Compose のファイル名には、いくつか種類があります。

  • compose.yaml: 現在の標準的なファイル名
  • compose.yml: compose.yaml の拡張子違い
  • docker-compose.yaml: 古い形式との互換用として読み込める名前
  • docker-compose.yml: 昔からよく使われている名前。現在も読み込める

この記事では、公式で優先されている compose.yaml という名前を使います。

コマンド名にも似たものがあります。

  • docker compose: 現在よく使う Compose V2 のコマンド
  • docker-compose: 古い Compose V1 のコマンド

この記事では、コマンドも docker compose で説明します。

Step 1 コンテナを作成する

ここでは、compose.yaml を使ってコンテナを作成します。

コンテナを作る方法は、大きく分けて2つあります。

  • 方法1: 既存イメージを指定してコンテナを作る
  • 方法2: Dockerfile からイメージを作り、そのイメージでコンテナを作る

方法1 既存イメージでコンテナを作る

まずは、既存の ubuntu:24.04 イメージを使ってコンテナを起動します。

この方法では、自分でイメージを作りません。既存イメージからコンテナを作ります。

作業ディレクトリを作る

作業用のディレクトリを作ります。

bash
mkdir compose-sample
cd compose-sample

compose.yaml を作る

次に、compose.yaml を作ります。

yaml
services:
  ubuntu-test:
    image: ubuntu:24.04
    container_name: ubuntu-compose-test
    tty: true
    stdin_open: true

この段階では、まだコンテナは作られていません。compose.yaml という設定ファイルを書いただけです。

コンテナを起動する

コンテナを作って起動します。

bash
docker compose up -d

docker compose up -d は、compose.yaml を読んでコンテナを作成し、バックグラウンドで起動します。

手元に ubuntu:24.04 イメージがない場合は、このタイミングでイメージも取得されます。

起動状態を確認する

作成されたコンテナを確認します。

bash
docker compose ps
docker ps

方法2 Dockerfile からイメージを作ってコンテナを作る

次は、Dockerfile からイメージを作り、そのイメージでコンテナを起動します。

この方法では、compose.yaml の build: を使います。

作業ディレクトリを作る

作業用のディレクトリを作ります。

bash
mkdir compose-build-sample
cd compose-build-sample

Dockerfile を作る

Dockerfile を作ります。

Dockerfile
FROM ubuntu:24.04

RUN apt-get update && apt-get install -y curl

WORKDIR /app

RUN echo "hello from compose image" > hello.txt

CMD ["bash"]

この Dockerfile は、Ubuntu 24.04 を元にして、curl と /app/hello.txt を入れたイメージを作るための設計図です。

compose.yaml を作る

同じディレクトリに、compose.yaml を作ります。

yaml
services:
  app:
    build: .
    image: my-compose-ubuntu:1.0
    container_name: my-compose-ubuntu-test
    tty: true
    stdin_open: true

この compose.yaml では、次の内容を書いています。

  • app: Compose 内で使うサービス名
  • build: .: 今いるディレクトリの Dockerfile からイメージを作る
  • image: my-compose-ubuntu:1.0: 作るイメージに名前を付ける
  • container_name: my-compose-ubuntu-test: 作成するコンテナ名
  • tty: true: ターミナル操作できるようにする
  • stdin_open: true: 標準入力を開いたままにする

イメージだけを作る

イメージだけを作る場合は、次のコマンドです。

bash
docker compose build

これはイメージを作る操作です。コンテナを起動する操作ではありません。

ただし、docker compose build は必ず先に実行しないといけないわけではありません。

compose.yaml に build: . が書かれている場合、後ほど登場する docker compose up -d だけでも、必要なイメージがまだ作られていなければ、自動でイメージを作ってからコンテナを起動します。

それでも docker compose build を単独で使う場面はあります。

  • コンテナを起動せずに、先にイメージだけ作りたい
  • ビルドが成功するかだけ確認したい
  • Dockerfile やビルド対象のファイルを変更したので、明示的に作り直したい

以下で作成されたイメージを確認できます。

bash
docker images

コンテナを起動する

コンテナを作って起動します。

bash
docker compose up -d

  • build: . が書かれている場合、docker compose up -d は必要に応じてイメージを作ってからコンテナを起動します。

  • そのため、イメージがまだない初回起動では、事前に docker compose build を実行しなくても動きます。

明示的にイメージの作成もコンテナの起動もまとめて行いたい場合は、次のように書けます。

bash
docker compose up --build -d

--build を付けると、起動前にイメージのビルドを明示的に行います。Dockerfile を変更したあとに、確実にビルドし直してから起動したい場合に使います。

Step 2 コンテナの中に入る

コンテナの中に入るには、サービス名を指定して docker compose exec を使います。

bash
docker compose exec <サービス名> bash

<サービス名> は、compose.yaml の services: の下に書いた名前です。たとえば、この記事の例では ubuntu-test や app がサービス名です。

通常の docker exec と同じように、コンテナ内でコマンドを実行できます。

docker exec と docker compose exec の違いは、指定する相手です。

  • docker exec -it <コンテナIDまたはコンテナ名> bash: コンテナIDやコンテナ名を直接指定して入る
  • docker compose exec <サービス名> bash: Compose のサービス名を指定して入る

Compose を使っている場合は、compose.yaml に書いたサービス名で入れるので、毎回コンテナIDを調べなくて済みます。

この記事の例で入る

この記事の例なら、次のように入れます。

  • 方法1のコンテナに入る: docker compose exec ubuntu-test bash
  • 方法2のコンテナに入る: docker compose exec app bash

方法1のコンテナで確認する

方法1の ubuntu-test に入った場合は、Ubuntu コンテナの中にいるか確認できます。

bash
cat /etc/os-release
exit

方法2のコンテナで確認する

方法2の app に入った場合は、Dockerfile で作った内容を確認できます。

bash
pwd
cat hello.txt
curl --version
exit

pwd が /app になり、hello.txt が表示されれば、Dockerfile から作ったイメージでコンテナを起動できています。

Step 3 停止と削除

コンテナを停止する

Compose で起動したコンテナを停止します。

bash
docker compose stop

コンテナを削除する

コンテナを削除する場合は、down を使います。

bash
docker compose down

docker compose down は、基本的には Compose で作ったコンテナやネットワークを削除します。作ったイメージは通常そのまま残ります。

イメージも削除する

イメージも削除したい場合は、次のようにします。

bash
docker compose down --rmi local

コマンドごとに対象を整理する

Compose のコマンドも、イメージ操作とコンテナ操作に分けると分かりやすいです。

コマンド主な対象何をしているか
docker compose buildイメージbuild: に書かれた Dockerfile からイメージを作る
docker compose up -dコンテナcompose.yaml をもとにコンテナを作って起動する。必要なイメージがなければ作成や取得も行う
docker compose up --build -dイメージとコンテナイメージを作り直してからコンテナを作って起動する
docker compose psコンテナCompose で起動したコンテナを見る
docker compose exec <サービス名> bashコンテナ起動中のコンテナに入る
docker compose stopコンテナCompose で起動したコンテナを停止する
docker compose downコンテナCompose で作ったコンテナやネットワークを削除する

特に混乱しやすいのは、docker compose build と docker compose up の違いです。

  • docker compose build: イメージだけを作る。コンテナは起動しない
  • docker compose up: コンテナを作って起動する。必要なイメージがなければ、先に作成や取得も行う
  • docker compose up --build: 起動前にイメージをビルドしてから、コンテナを作って起動する

まとめ

Compose を使う場合は、次のように分けて考えると整理しやすいです。

  • compose.yaml にコンテナの設定を書く
  • 既存イメージを使う場合は、image: に使うイメージを書く
  • Dockerfile から作る場合は、build: に Dockerfile の場所を書く
  • docker compose build はイメージだけを作る。初回起動前に必須ではない
  • docker compose up -d はコンテナを作って起動する。必要なイメージがなければ先に作成や取得も行う
  • docker compose down はコンテナを削除する

compose.yaml は、コンテナの起動設定をファイルとして残せるのが大きな利点です。同じ設定で何度も起動したい場合や、複数のコンテナをまとめて扱いたい場合に使いやすくなります。

ページの先頭へ ↑