Docker Composeの依存と環境変数 — depends_onを書いても落ちる

Docker Composeの依存と環境変数。コンテナとデータベース、準備確認のチェックリスト、環境設定の書類。

はじめて「Web + アプリ + データベース」の3つを Compose で書いたとき、こう書きました。

前回: docker runのオプションを5つに分ける — 長い1行が読めない

これは【深掘り】の記事です。本線の順路ではありません。 読まなくても先へ進めます。 本線の Composeなら1コマンド — 複数コンテナをまとめる の続きとして、そこで「depends_on は待ってくれない」と一言で片づけた部分を、実際に落として、直して、それでも足りないところまで確かめる回です。

この記事のコマンドは、すべてVMの中(Ubuntu Server)で打ちます。 前提: Dockerの導入を終えて、docker ps が sudo なしで通ること。 本線で作った ~/stack には触りません。 練習用に ~/complab を新しく作って、そこだけで完結させます。

  app:
    depends_on:
      - db

「db を先に立ち上げてから app を立ち上げる」と書いたつもりでした。 起動します。

app-1 exited with code 1

ログを見ると、

Error: connect ECONNREFUSED db:3306

db は動いています。 docker compose ps にも出ています。なのに繋がりません。

このとき私は depends_on のつづりを疑い、ネットワークを疑い、最後にはポート番号を疑って2時間溶かしました。どれも合っていました。 間違っていたのは、depends_on が何を待つのかという理解のほうです。

対象レベル: 中級〜上級 / 区分: 発展

目次

この記事でわかること

  • depends_on は「コンテナが起動したか」しか見ない。中のサービスが受付を始めたかは見ていない
  • healthcheck で直せるのは起動時の事故だけ。再起動やネットワークの瞬断では healthcheck は助けてくれないので、アプリ側のリトライは別に要る
  • 環境変数には「2つの世界」がある。.env はコンテナに届かない(Compose ファイルを組み立てるためだけに使われる)
  • ${VAR} が展開されるのは Compose ファイルを読むときであって、コンテナの中ではない
  • up と up --build と up --force-recreate は直す対象が違う。「イメージを変えたのに反映されない」はここで起きる
  • down と down -v と stop は消えるものが違う。-v はデータを消す

この記事でやること

  1. ~/complab に Web・アプリ・データベースの3つを書いて、アプリが ECONNREFUSED で落ちるところを再現する
  2. healthcheck と condition: service_healthy を書いて直す
  3. db を再起動して、healthcheck では防げないことを確かめ、アプリ側にリトライを入れる
  4. 同じ変数名を4か所すべてに書いて、どれが勝つかを1つずつ潰す
  5. docker compose config で展開後を読む
  6. プロファイルと複数ファイルの重ね方で、開発と本番の差分を分ける
  7. up --build / --force-recreate / logs --tail / down -v の違いを確かめて、片づける

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
ECONNREFUSED「その番号で待っている人がいない」というエラー。宛先までは届いている。届いていないなら別のエラーになる
healthcheckコンテナの中で定期的にコマンドを実行して、成功したら「健康」と判定する設定
補間(interpolation)Compose ファイルの中の ${VAR} を、読み込むときに文字列へ置き換えること
env_file変数をまとめて書いたファイルを、コンテナの環境変数として読み込ませる設定
プロファイルサービスに付けるラベル。指定したときだけそのサービスを起動する
マージ(merge)複数の Compose ファイルを重ねて1つの設定にすること
リトライ失敗したら間を置いて何度かやり直すこと。アプリ側で書く

① 3つのサービスを立てる

練習用のフォルダを作ります。本線の ~/stack とは別物です。

bash
$ mkdir -p ~/complab/app ~/complab/web && cd ~/complab

アプリを書く

データベースに繋ぎに行って、繋がったらHTTPで応答するだけのアプリです。ライブラリは使いません(npm install が要らないので、この記事の中で完結します)。

bash
$ nano ~/complab/app/app.js
const net = require("net");
const http = require("http");

const DB_HOST = process.env.DB_HOST || "db";
const DB_PORT = Number(process.env.DB_PORT || 3306);
const APP_NAME = process.env.APP_NAME || "(未設定)";

function tryConnect() {
  return new Promise((resolve, reject) => {
    const s = net.connect({ host: DB_HOST, port: DB_PORT });
    s.setTimeout(3000);
    s.on("connect", () => { s.end(); resolve(); });
    s.on("timeout", () => { s.destroy(); reject(new Error("ETIMEDOUT")); });
    s.on("error", (e) => reject(e));
  });
}

tryConnect().then(() => {
  console.log("db に繋がりました");
  http.createServer((req, res) => {
    res.end("APP_NAME=" + APP_NAME + "\n");
  }).listen(3000, () => console.log("listening on 3000"));
}).catch((e) => {
  console.error("Error: connect " + (e.code || e.message) + " " + DB_HOST + ":" + DB_PORT);
  process.exit(1);
});

起動したときに1回だけ繋ぎに行き、失敗したら終了します。 これはわざとです。世の中のアプリの多くが最初はこう書かれています。

bash
$ nano ~/complab/app/Dockerfile
FROM node:22-alpine
WORKDIR /app
COPY app.js .
CMD ["node", "app.js"]

Webサーバーの設定を書く

nginx が受けて、後ろの app へ渡すだけです。リバースプロキシの回で 127.0.0.1:3000 と書いたところが、Compose では app:3000 になります。

bash
$ nano ~/complab/web/default.conf
server {
    listen 80;
    location / {
        proxy_pass http://app:3000;
        proxy_set_header Host $host;
    }
}

compose.yaml を書く

bash
$ nano ~/complab/compose.yaml
services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:8090:80"
    volumes:
      - ./web/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - app

  app:
    build: ./app
    environment:
      DB_HOST: db
      DB_PORT: 3306

  db:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: labpass
      MYSQL_DATABASE: appdb
    volumes:
      - db-data:/var/lib/mysql

volumes:
  db-data:

labpass は練習用のダミーです。 本番のパスワードをここに書かないでください。あとで .env に追い出します。 公開先を 127.0.0.1:8090 にしています。 ネットワークの回でやったとおり、8090:80 と書くとVMの外に開きます。 練習台を世界に公開しないための書き方です。確認はVMの中の curl で行います。

書いたら、起動する前に検査します。

bash
$ docker compose config > /dev/null && echo OK

OK が出れば YAML として読めています。


② depends_on は「起動順」であって「準備完了」ではない

app にはまだ depends_on を書いていません。まず、書かない状態で落とします。

bash
$ cd ~/complab
$ docker compose up -d --build
[+] Running 5/5
 ✔ Network complab_default   Created
 ✔ Volume "complab_db-data"  Created
 ✔ Container complab-db-1    Started
 ✔ Container complab-app-1   Started
 ✔ Container complab-web-1   Started

「Started」と出ています。 状態を見ます。

bash
$ docker compose ps -a
NAME              IMAGE            STATUS
complab-app-1     complab-app      Exited (1) 4 seconds ago
complab-db-1      mysql:8.4        Up 5 seconds
complab-web-1     nginx:alpine     Up 5 seconds

docker compose ps だけだと、落ちた app は表示されません。 止まったものまで見るには -a が要ります。「サービスが一覧に出てこない」と焦る前に -a を付けてください。

bash
$ docker compose logs app
complab-app-1  | Error: connect ECONNREFUSED db:3306
complab-app-1 exited with code 1

冒頭のエラーが再現しました。

[スクリーンショット: 01_ECONNREFUSED再現.png] docker compose ps -a で app が Exited (1) になっている画面と、docker compose logs app の ECONNREFUSED を並べて撮ってください。

depends_on を足しても直らない

ここが本題です。 compose.yaml の app に depends_on を足します。

  app:
    build: ./app
    environment:
      DB_HOST: db
      DB_PORT: 3306
    depends_on:
      - db
bash
$ docker compose down
$ docker compose up -d
$ docker compose ps -a
NAME              IMAGE            STATUS
complab-app-1     complab-app      Exited (1) 3 seconds ago
complab-db-1      mysql:8.4        Up 4 seconds
complab-web-1     nginx:alpine     Up 3 seconds

同じです。

depends_on: [db] の意味は「db のコンテナを先に開始する」だけです。 コンテナの開始(started)と、中の MySQL が接続を受け付ける状態(ready)は、別の出来事です。

MySQL は初回起動でデータベースの初期化をするので、受付を始めるまでに十数秒〜数十秒かかります。その間、3306番では誰も待っていません。 だから ECONNREFUSED です。

ECONNREFUSED は「届いていない」ではありません。 届いたうえで「その番号は空いている」と返ってきた状態です。名前が引けなければ EAI_AGAIN や ENOTFOUND、経路が無ければタイムアウトになります。エラーの種類が切り分けの半分をやってくれます(エラーの読み方)。

healthcheck を書いて直す

「受付を始めたか」を自分で判定して、Compose に教えます。

下は compose.yaml の全文です。 追記ではなく丸ごと置き換えてください。部分だけ貼り足すと key "app" already defined で失敗します。

services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:8090:80"
    volumes:
      - ./web/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      app:
        condition: service_started

  app:
    build: ./app
    environment:
      DB_HOST: db
      DB_PORT: 3306
    depends_on:
      db:
        condition: service_healthy

  db:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: labpass
      MYSQL_DATABASE: appdb
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 --silent"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 40s

volumes:
  db-data:
bash
$ docker compose down
$ docker compose up -d
$ docker compose ps
NAME              IMAGE            STATUS
complab-app-1     complab-app      Up 2 seconds
complab-db-1      mysql:8.4        Up 25 seconds (healthy)
complab-web-1     nginx:alpine     Up 1 second

(healthy) が付き、app の起動が後ろにずれました。 確認します。

bash
$ curl -s http://127.0.0.1:8090/
APP_NAME=(未設定)

nginx → app → db が通りました。

[スクリーンショット: 02_healthy待ち.png] docker compose ps で db に (healthy) が付き、app が Up になっている画面を撮ってください。

healthcheck の各項目

この5つで全部です。

項目意味決め方
test判定に使うコマンド。終了コード0なら健康、1なら不健康そのコンテナの中に入っているコマンドを選ぶ。無ければ必ず失敗する
interval何秒おきに実行するか短すぎると負荷になる。5〜30秒
timeout1回の試行の待ち時間の上限。超えたら失敗扱いinterval より短くする
retries何回続けて失敗したら unhealthy にするかinterval × retries が「諦めるまでの時間」
start_period起動直後の猶予時間。この間の失敗は retries に数えない初期化に時間がかかるもの(データベース)には必ず付ける

test の書き方は2種類あります。

書き方実行のされ方
["CMD", "mysqladmin", "ping"]シェルを通さずそのまま実行。パイプもリダイレクトも使えない
["CMD-SHELL", "mysqladmin ping ... || exit 1"]シェルを通す。パイプ・&&・|| が使える

素の文字列で書くと CMD-SHELL 扱いです。 上の例で CMD-SHELL にしたのは、--silent で出力を消しつつシェルの終了コードを使いたかったからです。

判定の履歴は残っています。

bash
$ docker inspect --format '{{json .State.Health}}' complab-db-1
{"Status":"healthy","FailingStreak":0,"Log":[{"ExitCode":1,"Output":"mysqladmin: connect to server at '127.0.0.1' failed"},{"ExitCode":0,"Output":""}]}

「healthcheck を書いたのにずっと starting のまま」のときは、まずここを読んでください。 ほとんどが test のコマンドがそのイメージに入っていない(curl が無い、など)です。

condition: に書けるものは3つです。

条件待つもの
service_startedコンテナが開始した(既定。- db と書いたときと同じ)
service_healthyhealthcheck が通った
service_completed_successfullyそのサービスが終了コード0で終わった(初期化専用のサービスに使う)

それでも、アプリ側のリトライは要る

ここが一番の落とし穴です。 healthcheck は「up するときの順番」しか面倒を見ません。

db を再起動してみます。

bash
$ docker compose restart db
$ sleep 3
$ curl -s http://127.0.0.1:8090/
$ docker compose ps -a app
APP_NAME=(未設定)
NAME              IMAGE          STATUS
complab-app-1     complab-app    Up 3 minutes

アプリは生きたままです。 起動時に1回繋いだきりで、その後は何も確かめていないからです。この状態で db にクエリを投げれば、当然エラーになります。

healthcheck が守るのは「起動の瞬間」だけです。 運用中の再起動・ネットワークの瞬断・データベースのフェイルオーバーでは、誰も app を待たせてくれません。 繋ぎ直すのはアプリの仕事であって、Compose の仕事ではありません。

アプリにリトライを入れます。

bash
$ nano ~/complab/app/app.js
const net = require("net");
const http = require("http");

const DB_HOST = process.env.DB_HOST || "db";
const DB_PORT = Number(process.env.DB_PORT || 3306);
const APP_NAME = process.env.APP_NAME || "(未設定)";

function tryConnect() {
  return new Promise((resolve, reject) => {
    const s = net.connect({ host: DB_HOST, port: DB_PORT });
    s.setTimeout(3000);
    s.on("connect", () => { s.end(); resolve(); });
    s.on("timeout", () => { s.destroy(); reject(new Error("ETIMEDOUT")); });
    s.on("error", (e) => reject(e));
  });
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function connectWithRetry(max) {
  for (let i = 1; i <= max; i++) {
    try {
      await tryConnect();
      console.log("db に繋がりました (" + i + "回目)");
      return;
    } catch (e) {
      console.log("db に繋がらない " + (e.code || e.message) + " " + i + "/" + max + " 回目、2秒後に再試行");
      await sleep(2000);
    }
  }
  throw new Error("db に繋がらないまま上限に達しました");
}

connectWithRetry(30).then(() => {
  http.createServer(async (req, res) => {
    try {
      await tryConnect();
      res.end("APP_NAME=" + APP_NAME + " db=OK\n");
    } catch (e) {
      res.statusCode = 503;
      res.end("APP_NAME=" + APP_NAME + " db=NG " + (e.code || e.message) + "\n");
    }
  }).listen(3000, () => console.log("listening on 3000"));
}).catch((e) => {
  console.error(e.message);
  process.exit(1);
});

変えたのは2か所です。 起動時に30回まで2秒おきにやり直すのと、リクエストのたびに繋ぎ直すようにしたところです。

bash
$ docker compose up -d --build
$ sleep 20
$ curl -s http://127.0.0.1:8090/
APP_NAME=(未設定) db=OK

db を止めている間はどうなるか、確かめます。

bash
$ docker compose stop db
$ curl -s -w " [HTTP %{http_code}]\n" http://127.0.0.1:8090/
$ docker compose start db
APP_NAME=(未設定) db=NG ENOTFOUND [HTTP 503]

アプリは落ちずに、503 を返して生き残りました。 しばらく待ってもう一度叩けば db=OK に戻ります。 止まったコンテナは Docker の内部 DNS から外れるので、エラーは「名前が引けない」ENOTFOUND(環境によっては EAI_AGAIN)になります。

healthcheck を消していい、という話ではありません。 healthcheck は「起動時に無駄に1回落ちる」のを防ぐもの。リトライは「運用中に落ちない」ためのもの。 両方要ります。


③ 環境変数はどれが勝つのか

.env に書いたのに反映されない。environment: に書いたのに反映されない。 ここは全員が一度混乱します。同じ変数名を4か所すべてに書いて、1つずつ潰します。

まず、世界が2つあることを分ける

世界何をするか使われるもの
A:Compose ファイルを組み立てる世界${VAR} を文字列に置き換える(補間)シェルの環境変数 と .env
B:コンテナに環境変数を渡す世界コンテナの中の printenv に出るものenvironment: と env_file: と Dockerfile の ENV

.env はコンテナには届きません。 .env は「Compose ファイルの ${VAR} を埋めるための材料」であって、中身が自動でコンテナに入るわけではありません。 本線の記事で .env に書いたパスワードが効いていたのは、compose.yaml 側に ${MYSQL_ROOT_PASSWORD} と書いてあったからです。そこを書かなければ何も起きません。

実験の準備

4か所すべてに、違う値で APP_NAME を書きます。

bash
$ cd ~/complab
$ printf 'APP_NAME=from-dotenv\nMYSQL_ROOT_PASSWORD=labpass\n' > .env
$ printf 'APP_NAME=from-envfile\n' > app.env
$ export APP_NAME=from-shell

compose.yaml の app を、こうします。

  app:
    build: ./app
    env_file:
      - ./app.env
    environment:
      DB_HOST: db
      DB_PORT: 3306
      APP_NAME: from-environment
    depends_on:
      db:
        condition: service_healthy

測り方はこれ1つです。 コンテナを実際に立てて、中の値を読みます。

bash
$ docker compose run --rm --no-deps app printenv APP_NAME

--no-deps を付けないと db の healthcheck を待たされます。 変数を見たいだけなので外します。--rm は使い捨ての意味です。

1段目:全部書いてある

from-environment

environment: が勝ちました。 env_file: にも .env にもシェルにも書いてあるのに、です。

2段目:environment: から APP_NAME の行を消す

    environment:
      DB_HOST: db
      DB_PORT: 3306
bash
$ docker compose run --rm --no-deps app printenv APP_NAME
from-envfile

env_file: が出てきました。

3段目:env_file: の2行も消す

bash
$ docker compose run --rm --no-deps app printenv APP_NAME
$ echo "終了コード: $?"
終了コード: 1

何も出ません。 .env にもシェルにも APP_NAME=... があるのに、コンテナには何も渡っていません。

これが「.env に書いたのに効かない」の正体です。 .env とシェル変数は、世界Aの住人です。 compose.yaml に ${APP_NAME} と書いて呼び出さないかぎり、世界Bには入ってきません。

4段目:${APP_NAME} で呼び出す

    environment:
      DB_HOST: db
      DB_PORT: 3306
      APP_NAME: ${APP_NAME}
bash
$ docker compose run --rm --no-deps app printenv APP_NAME
from-shell

シェルの環境変数が勝ちました。

5段目:シェル変数を消す

bash
$ unset APP_NAME
$ docker compose run --rm --no-deps app printenv APP_NAME
from-dotenv

ここで初めて .env が出てきます。

結論の表

上ほど強い。

順位書き場所世界
1docker compose run -e APP_NAME=...(コマンドライン)B
2environment:B
3env_file:B
4Dockerfile の ENVB
—(ここから下は ${VAR} で呼ばないと届かない)
5シェルの環境変数A
6.envA

environment: APP_NAME: ${APP_NAME} と書いたときだけ、5と6が2の座席に座ります。 順位が入れ替わって見えるのはこのためです。

${VAR} が展開されるのはいつか

Compose ファイルを読んだ瞬間、VMの上でです。コンテナの中ではありません。

確かめます。app に1行足します。

      HOME_ON_HOST: ${HOME}
bash
$ docker compose run --rm --no-deps app printenv HOME HOME_ON_HOST
/root
/home/ubuntu

HOME はコンテナの中の値、HOME_ON_HOST はVMのログインユーザーの値です。同じ ${HOME} と書いたのに、片方はVM側で埋められています。

コンテナの中で $ を使いたいときは $$ と書きます。

    command: sh -c 'echo "container HOME is $$HOME"'

$ 1つだと Compose が先に食べます。 本線で sh -c '...' を使ったときの話と同じ問題が、Compose ファイル側でも起きるということです。確認したら、この command: と HOME_ON_HOST: の行は消しておいてください。

既定値とエラーの書き方

書き方意味
${VAR}未設定なら空文字。エラーにならない
${VAR:-nameless}未設定または空なら nameless
${VAR-nameless}未設定なら nameless(空文字はそのまま空文字)
${VAR:?メッセージ}未設定または空なら、そのメッセージを出して止まる
${VAR:+付いてる}設定されているときだけ 付いてる に置き換わる

空文字で静かに通るのが一番危ないので、消えては困るものには :? を付けます。

  db:
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?パスワードが .env にありません}

わざと外して試します。

bash
$ mv .env .env.bak
$ docker compose config > /dev/null
required variable MYSQL_ROOT_PASSWORD is missing a value: パスワードが .env にありません
bash
$ mv .env.bak .env

起動する前に、自分の言葉で止まりました。 ${MYSQL_ROOT_PASSWORD} のままだと空文字で起動しにいって、MySQL 側の分かりにくいエラーで落ちます。

.env は Git に入れない。.env.example を置く

bash
$ cd ~/complab
$ printf '.env\napp.env\n' > .gitignore
$ printf 'APP_NAME=my-app\nMYSQL_ROOT_PASSWORD=ここに自分のパスワードを書く\n' > .env.example
$ ls -a
.  ..  .env  .env.example  .gitignore  app  app.env  compose.yaml  web
ファイルGitに入れるか中身
compose.yaml入れる構成。秘密は入れない
.env入れない実際のパスワード
.env.example入れる変数名だけを並べた見本。値はダミー

.env.example があると、他の人(半年後の自分を含む)が「何を用意すればいいか」を1秒で分かります。 .env だけ無視されていると、必要な変数名すら分かりません。

暗号化してGitに置く方法もあります。 SOPSとageの回で扱っています。


④ docker compose config で「展開後」を見る

これが、この記事で一番使う型です。

bash
$ docker compose config
name: complab
services:
  app:
    build:
      context: /home/ubuntu/complab/app
    depends_on:
      db:
        condition: service_healthy
        required: true
    environment:
      APP_NAME: from-dotenv
      DB_HOST: db
      DB_PORT: "3306"

${...} は1つも残っていません。 これがCompose が実際に使う最終形です。

使い方何が分かるか
docker compose config変数を展開し、複数ファイルを重ねた最終形
docker compose config --no-interpolate展開する前の形。「どこで ${} を書いたか」を探すとき
docker compose config --servicesサービス名の一覧だけ
docker compose config --quiet出力せず、構文が正しいかだけを見る

変数が絡む不具合は、起動して調べる前にこれを見ます。

bash
$ docker compose config | grep -A3 'environment:'

config の出力にはパスワードがそのまま出ます。 画面共有やスクリーンショットのときに注意してください。 この記事のスクリーンショットも、ダミーのパスワードだからそのまま出しています。

[スクリーンショット: 03_config展開後.png] docker compose config の出力で、${...} が実際の値に置き換わっているところを撮ってください。本物のパスワードが写っていないことを確認してからアップロードしてください。


⑤ プロファイルで「開発のときだけ立てるもの」を分ける

データベースの中身を見る画面が欲しい。でも本番では絶対に立てたくない。 これがプロファイルの出番です。

compose.yaml にサービスを1つ足します。

  adminer:
    image: adminer
    profiles:
      - dev
    ports:
      - "127.0.0.1:8091:8080"
    depends_on:
      db:
        condition: service_healthy
bash
$ docker compose up -d
$ docker compose ps --services
app
db
web

adminer は起動していません。 プロファイルが付いたサービスは、名指ししない限り無視されます。

bash
$ docker compose --profile dev up -d
$ docker compose ps --services
adminer
app
db
web

今度は立ちました。

bash
$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8091/
200
やり方書き方
コマンドで指定docker compose --profile dev up -d
複数指定docker compose --profile dev --profile debug up -d
環境変数で指定COMPOSE_PROFILES=dev docker compose up -d(.env にも書ける)
全部立てるdocker compose --profile "*" up -d

落とすときも同じプロファイルを付けます。

bash
$ docker compose down
$ docker compose ps -a --services
adminer

adminer だけ残りました。 プロファイル無しの down は、プロファイル付きのサービスを知らないからです。

bash
$ docker compose --profile dev down

「片づけたのに1つ残っている」の典型です。 上げるときに付けたものは、下ろすときにも付けると覚えてください。


⑥ ファイルを重ねる — 開発と本番で差分だけ変える

同じ compose.yaml を本番にも使いたい。でもポートと変数は変えたい。 ファイルをコピーして2本持つと、片方だけ直して食い違います。

compose.override.yaml は自動で重なる

bash
$ nano ~/complab/compose.override.yaml
services:
  app:
    environment:
      APP_NAME: dev-override
bash
$ docker compose config | grep APP_NAME
      APP_NAME: dev-override

何も指定していないのに重なりました。 compose.yaml と compose.override.yaml は、既定で自動的に読まれます。

重なり方には規則がある

compose.override.yaml にポートを足してみます。

services:
  app:
    environment:
      APP_NAME: dev-override
  web:
    ports:
      - "127.0.0.1:8099:80"
bash
$ docker compose config | grep -A6 'web:'
  web:
    image: nginx:alpine
    ports:
    - 127.0.0.1:8090:80
    - 127.0.0.1:8099:80

8090 が消えていません。両方になりました。

種類重なり方
キーと値(image: APP_NAME:)後のファイルが上書きする
リスト(ports: volumes: command 以外の配列)後のファイルが後ろに足される(上書きではない)

「本番用のポートに変えたつもりが、開発用のポートも開いたまま」はここで起きます。置き換えたいときは !override を書きます。

本番用のファイルを別に置く

bash
$ nano ~/complab/compose.prod.yaml
services:
  web:
    ports: !override
      - "127.0.0.1:8100:80"
  app:
    environment:
      APP_NAME: prod
  adminer:
    profiles:
      - never
bash
$ docker compose --file compose.yaml --file compose.prod.yaml config | grep -E 'APP_NAME|8090|8099|8100'
      APP_NAME: prod
    - 127.0.0.1:8100:80

8090 も 8099 も消えました。

押さえること中身
--file(-f)は左から順に重なる右のファイルほど強い
-f を指定すると compose.override.yaml は自動では読まれないだから本番で開発用の設定が混ざらない
相対パスの基準は「最初の -f のファイルがある場所」./app の意味が変わらないのはこのため
!overrideそのリストを足さずに置き換える
プロジェクト名は -p で変える別名で同時に立てられる

docker compose -f a.yaml -f b.yaml up で立てたものは、docker compose down だけでは落ちません。 落とすときも同じ -f を並べます。 プロファイルと同じ話です。


⑦ up と up --build と up --force-recreate

「コードを直したのに反映されない」 の原因は、ほぼここです。

app のメッセージを変えます。

bash
$ sed -i 's/db=OK/db=OK v2/' ~/complab/app/app.js
$ docker compose up -d
$ curl -s http://127.0.0.1:8090/
APP_NAME=dev-override db=OK

v2 になっていません。

docker compose up は、イメージを作り直しません。 すでに作ってあるイメージをそのまま使います。 app.js はイメージの中に COPY されているので、作り直さない限り古いままです。

bash
$ docker compose up -d --build
$ curl -s http://127.0.0.1:8090/
APP_NAME=dev-override db=OK v2

反映されました。

コマンド何をやり直すか使う場面
up -d設定が変わったサービスだけコンテナを作り直すふだんはこれ
up -d --buildイメージをビルドし直してから作り直すbuild: のソースを直したとき
up -d --force-recreate設定が変わっていなくてもコンテナを作り直す中で手で直したものを捨てたいとき
up -d --no-deps <名前>依存を巻き込まずにそのサービスだけdb を落とさずに app だけ入れ替える
up -d --pull alwaysイメージを取り直してから起動image: 側が更新されたとき
build --no-cacheキャッシュを使わずにビルドレイヤーキャッシュが効きすぎて古いものを掴むとき

判断はこの順です。

  1. build: を書いたサービスのソースを直した → --build
  2. image: のタグは同じだが中身が新しくなった → --pull always
  3. compose.yaml を直した → up -d だけでよい(差分を見て作り直してくれる)
  4. 何も変えていないが状態を捨てたい → --force-recreate

--force-recreate はコンテナを作り直すだけで、ボリュームは消しません。 データを消したいわけではないなら、これで十分です。


⑧ ログを絞る

サービスが3つあると、全部混ざって読めません。

bash
$ docker compose logs --tail 5 db
complab-db-1  | [System] [MY-010931] [Server] /usr/sbin/mysqld: ready for connections.
書き方意味
docker compose logs <サービス名>そのサービスだけ。名前は空白区切りで複数書ける
--tail 20末尾20行だけ。付けないと最初から全部出る
-f追いかけ続ける(Ctrl + C で抜ける)
--since 5m直近5分だけ。--until もある
-t時刻を付ける
--no-log-prefix行頭の complab-db-1 | を消す。grep に流すとき

よく使うのはこの2つです。

bash
$ docker compose logs -f --tail 20 app
bash
$ docker compose logs --tail 50 app db

docker compose logs は、down で消したコンテナのログは出しません。 落ちた原因を追うときは、down する前に読んでください。 私はこれで2回、原因が分からないまま作り直しました。


⑨ down と stop と down -v

混同すると、データが消えます。

コマンドコンテナネットワーク名前付きボリュームイメージ
stop止まるが残る(start で再開)残る残る残る
down消える消える残る残る
down -v消える消える消える=データが消える残る
down --rmi local消える消える残る自分でビルドしたものが消える

確かめます。

bash
$ docker compose down
$ docker volume ls | grep complab
local     complab_db-data

down では残ります。

-v は取り返しがつきません。 「なんかおかしいから作り直そう」で down -v を打つと、データベースの中身が全部消えます。 消したいのはコンテナなのか、データなのかを口に出してから打ってください。コンテナだけ作り直したいなら --force-recreate です。

消してしまったときに戻せるかどうかは、事前にバックアップを取っていたかで決まります。 取り方はボリュームの回にまとめてあります。

stop との違いも見ておきます。

bash
$ docker compose up -d
$ docker compose stop
$ docker compose ps -a --format 'table {{.Name}}\t{{.State}}'
NAME              STATE
complab-app-1     exited
complab-db-1      exited
complab-web-1     exited
bash
$ docker compose start

コンテナはそのまま残っているので、start で戻ります。 down したあとは start できません(コンテナが無いので up からです)。


つまずいたところ

depends_on のつづりを疑った。 合っていました。エラーが ECONNREFUSED なら、設定ではなく「相手がまだ受け付けていない」を先に疑う。名前が引けていないなら別のエラーになります。切り分けの入口をエラーの種類にしたら、同じ問題で悩まなくなりました。

docker compose ps に app が出てこないので「起動していない」と思った。 落ちて Exited になっていただけでした。-a を付けないと止まったものは出ません。 「見えない=起動していない」ではありませんでした。

healthcheck を書いたのに、いつまでも starting のままだった。 test に curl を書いたのに、そのイメージに curl が入っていませんでした。test のコマンドは「そのコンテナの中」に無いと必ず失敗します。 docker compose exec db which mysqladmin で先に確かめる、を型にしました。

start_period を知らずに retries を50にした。 MySQL の初期化が終わるまで失敗し続けるのが怖かったからです。start_period の間の失敗は数えられません。 「初期化にかかる時間」は start_period、「壊れたと判断するまで」は interval × retries、と役割が分かれていました。

.env にパスワードを書いたのに、コンテナに渡っていなかった。 compose.yaml 側に ${...} を書き忘れていました。.env は Compose ファイルを組み立てる材料で、コンテナには直接届きません。 ここを分けて考えるまで、30分ごとに同じ勘違いをしていました。

シェルに残っていた export APP_NAME=... が、翌日まで効いていた。 別のターミナルでは再現せず、原因が分からず混乱しました。シェル変数は .env より強い。 実験のあとは unset する、を決めました。

本番用のファイルを重ねたのに、開発用のポートが開いたままだった。 リストは上書きではなく追加でした。!override を知るまで、ポートが2つ開いていることに気づきませんでした。docker compose config を見ていれば1秒で分かりました。

app.js を直したのに反映されず、ボリュームを疑った。 up はイメージを作り直しません。 COPY でイメージに焼き込んだものは --build が要ります。「バインドマウントなら即反映、COPY なら再ビルド」という区別が付いていませんでした。

docker compose down したのに adminer が残っていた。 プロファイル付きは、同じプロファイルを付けないと落ちません。 -f を並べたときも同じでした。上げたときのオプションを、下ろすときにも書くと覚えました。


後片づけ

bash
$ cd ~/complab
$ docker compose --profile dev down -v
$ docker compose ps -a
NAME   IMAGE   COMMAND   SERVICE   CREATED   STATUS   PORTS

見出しの行だけになれば片づいています。 ボリュームも消えたか見ます。

bash
$ docker volume ls | grep complab

何も出なければ消えています。

実験で export したシェル変数を戻します。

bash
$ unset APP_NAME
$ env | grep APP_NAME

何も出なければ戻っています。 ここを忘れると、別のプロジェクトで謎の値が入ります。

イメージとフォルダを消します。

bash
$ docker image rm complab-app nginx:alpine mysql:8.4 adminer node:22-alpine 2>/dev/null
$ cd ~ && rm -rf ~/complab
$ docker system df

~/stack(本線で作ったもの)は消していません。 この記事は ~/complab の中だけで完結しています。


まとめ — 理解できたこと

  • depends_on は「コンテナが開始したか」しか見ない。 中のサービスが受付を始めたかは見ていない
  • ECONNREFUSED は「届いたが誰も待っていない」。 名前が引けない・経路が無い場合とはエラーが変わる
  • healthcheck + condition: service_healthy で、準備完了まで待たせられる
  • healthcheck は test / interval / timeout / retries / start_period の5つ。 初期化が長いものには start_period
  • test のコマンドは、そのイメージの中に無いと必ず失敗する(curl が入っていない、が定番)
  • healthcheck が守るのは起動の瞬間だけ。 再起動・瞬断ではアプリ側のリトライしか助けにならない
  • 環境変数には2つの世界がある。.env はコンテナに届かない。${VAR} で呼び出して初めて渡る
  • 強さは -e > environment: > env_file: > Dockerfile の ENV。 シェル変数と .env は補間の材料
  • ${VAR} が展開されるのは Compose ファイルを読むとき、VMの上で。 コンテナの中では $$ と書く
  • 消えては困る変数には ${VAR:?メッセージ}。 ${VAR} は空文字で静かに通る
  • .env は Git に入れない。.env.example を置いて変数名だけ共有する
  • docker compose config が最終形。 変数まわりで迷ったら、起動する前にこれを読む
  • profiles: で、開発のときだけ立てるものを分けられる。 落とすときも同じ --profile が要る
  • compose.override.yaml は自動で重なる。-f を指定すると読まれない
  • 重ねたとき、キーは上書き・リストは追加。 置き換えたいなら !override
  • up はイメージを作り直さない。 ソースを直したら --build、状態を捨てたいなら --force-recreate
  • logs は --tail とサービス名で絞る。 down するとログも読めなくなる
  • stop は残る、down はデータが残る、down -v はデータが消える

参考リンク


次に読む

この記事は 【深掘り】Docker の 8 / 11 本目です。

記事
← 前の記事docker runのオプションを5つに分ける — 長い1行が読めない
→ 次の記事Dockerでの開発ワークフロー — bind mountでnode_modulesが消える

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

DevOps›Docker — Compose
  • depends_on と healthcheck / 環境変数の優先順位
  • プロファイル・複数ファイル・up の使い分け

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次