はじめて「Web + アプリ + データベース」の3つを Compose で書いたとき、こう書きました。
これは【深掘り】の記事です。本線の順路ではありません。 読まなくても先へ進めます。 本線の 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はデータを消す
この記事でやること
~/complabに Web・アプリ・データベースの3つを書いて、アプリがECONNREFUSEDで落ちるところを再現するhealthcheckとcondition: service_healthyを書いて直す- db を再起動して、healthcheck では防げないことを確かめ、アプリ側にリトライを入れる
- 同じ変数名を4か所すべてに書いて、どれが勝つかを1つずつ潰す
docker compose configで展開後を読む- プロファイルと複数ファイルの重ね方で、開発と本番の差分を分ける
up --build/--force-recreate/logs --tail/down -vの違いを確かめて、片づける
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| ECONNREFUSED | 「その番号で待っている人がいない」というエラー。宛先までは届いている。届いていないなら別のエラーになる |
| healthcheck | コンテナの中で定期的にコマンドを実行して、成功したら「健康」と判定する設定 |
| 補間(interpolation) | Compose ファイルの中の ${VAR} を、読み込むときに文字列へ置き換えること |
| env_file | 変数をまとめて書いたファイルを、コンテナの環境変数として読み込ませる設定 |
| プロファイル | サービスに付けるラベル。指定したときだけそのサービスを起動する |
| マージ(merge) | 複数の Compose ファイルを重ねて1つの設定にすること |
| リトライ | 失敗したら間を置いて何度かやり直すこと。アプリ側で書く |
① 3つのサービスを立てる
練習用のフォルダを作ります。本線の ~/stack とは別物です。
アプリを書く
データベースに繋ぎに行って、繋がったらHTTPで応答するだけのアプリです。ライブラリは使いません(npm install が要らないので、この記事の中で完結します)。
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回だけ繋ぎに行き、失敗したら終了します。 これはわざとです。世の中のアプリの多くが最初はこう書かれています。
FROM node:22-alpine
WORKDIR /app
COPY app.js .
CMD ["node", "app.js"]
Webサーバーの設定を書く
nginx が受けて、後ろの app へ渡すだけです。リバースプロキシの回で 127.0.0.1:3000 と書いたところが、Compose では app:3000 になります。
server {
listen 80;
location / {
proxy_pass http://app:3000;
proxy_set_header Host $host;
}
}
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で行います。
書いたら、起動する前に検査します。
OK が出れば YAML として読めています。
② depends_on は「起動順」であって「準備完了」ではない
app にはまだ depends_on を書いていません。まず、書かない状態で落とします。
[+] 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」と出ています。 状態を見ます。
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 を付けてください。
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
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:
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 の起動が後ろにずれました。 確認します。
APP_NAME=(未設定)
nginx → app → db が通りました。
[スクリーンショット: 02_healthy待ち.png] docker compose ps で db に (healthy) が付き、app が Up になっている画面を撮ってください。
healthcheck の各項目
この5つで全部です。
| 項目 | 意味 | 決め方 |
|---|---|---|
test | 判定に使うコマンド。終了コード0なら健康、1なら不健康 | そのコンテナの中に入っているコマンドを選ぶ。無ければ必ず失敗する |
interval | 何秒おきに実行するか | 短すぎると負荷になる。5〜30秒 |
timeout | 1回の試行の待ち時間の上限。超えたら失敗扱い | interval より短くする |
retries | 何回続けて失敗したら unhealthy にするか | interval × retries が「諦めるまでの時間」 |
start_period | 起動直後の猶予時間。この間の失敗は retries に数えない | 初期化に時間がかかるもの(データベース)には必ず付ける |
test の書き方は2種類あります。
| 書き方 | 実行のされ方 |
|---|---|
["CMD", "mysqladmin", "ping"] | シェルを通さずそのまま実行。パイプもリダイレクトも使えない |
["CMD-SHELL", "mysqladmin ping ... || exit 1"] | シェルを通す。パイプ・&&・|| が使える |
素の文字列で書くと CMD-SHELL 扱いです。 上の例で CMD-SHELL にしたのは、--silent で出力を消しつつシェルの終了コードを使いたかったからです。
判定の履歴は残っています。
{"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_healthy | healthcheck が通った |
service_completed_successfully | そのサービスが終了コード0で終わった(初期化専用のサービスに使う) |
それでも、アプリ側のリトライは要る
ここが一番の落とし穴です。 healthcheck は「up するときの順番」しか面倒を見ません。
db を再起動してみます。
APP_NAME=(未設定)
NAME IMAGE STATUS
complab-app-1 complab-app Up 3 minutes
アプリは生きたままです。 起動時に1回繋いだきりで、その後は何も確かめていないからです。この状態で db にクエリを投げれば、当然エラーになります。
healthcheck が守るのは「起動の瞬間」だけです。 運用中の再起動・ネットワークの瞬断・データベースのフェイルオーバーでは、誰も app を待たせてくれません。 繋ぎ直すのはアプリの仕事であって、Compose の仕事ではありません。
アプリにリトライを入れます。
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秒おきにやり直すのと、リクエストのたびに繋ぎ直すようにしたところです。
APP_NAME=(未設定) db=OK
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 を書きます。
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つです。 コンテナを実際に立てて、中の値を読みます。
--no-deps を付けないと db の healthcheck を待たされます。 変数を見たいだけなので外します。--rm は使い捨ての意味です。
1段目:全部書いてある
from-environment
environment: が勝ちました。 env_file: にも .env にもシェルにも書いてあるのに、です。
2段目:environment: から APP_NAME の行を消す
environment:
DB_HOST: db
DB_PORT: 3306
from-envfile
env_file: が出てきました。
3段目:env_file: の2行も消す
終了コード: 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}
from-shell
シェルの環境変数が勝ちました。
5段目:シェル変数を消す
from-dotenv
ここで初めて .env が出てきます。
結論の表
上ほど強い。
| 順位 | 書き場所 | 世界 |
|---|---|---|
| 1 | docker compose run -e APP_NAME=...(コマンドライン) | B |
| 2 | environment: | B |
| 3 | env_file: | B |
| 4 | Dockerfile の ENV | B |
| — | (ここから下は ${VAR} で呼ばないと届かない) | |
| 5 | シェルの環境変数 | A |
| 6 | .env | A |
environment: APP_NAME: ${APP_NAME} と書いたときだけ、5と6が2の座席に座ります。 順位が入れ替わって見えるのはこのためです。
${VAR} が展開されるのはいつか
Compose ファイルを読んだ瞬間、VMの上でです。コンテナの中ではありません。
確かめます。app に1行足します。
HOME_ON_HOST: ${HOME}
/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 にありません}
わざと外して試します。
required variable MYSQL_ROOT_PASSWORD is missing a value: パスワードが .env にありません
起動する前に、自分の言葉で止まりました。 ${MYSQL_ROOT_PASSWORD} のままだと空文字で起動しにいって、MySQL 側の分かりにくいエラーで落ちます。
.env は Git に入れない。.env.example を置く
. .. .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 で「展開後」を見る
これが、この記事で一番使う型です。
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 | 出力せず、構文が正しいかだけを見る |
変数が絡む不具合は、起動して調べる前にこれを見ます。
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
app
db
web
adminer は起動していません。 プロファイルが付いたサービスは、名指ししない限り無視されます。
adminer
app
db
web
今度は立ちました。
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 |
落とすときも同じプロファイルを付けます。
adminer
adminer だけ残りました。 プロファイル無しの down は、プロファイル付きのサービスを知らないからです。
「片づけたのに1つ残っている」の典型です。 上げるときに付けたものは、下ろすときにも付けると覚えてください。
⑥ ファイルを重ねる — 開発と本番で差分だけ変える
同じ compose.yaml を本番にも使いたい。でもポートと変数は変えたい。 ファイルをコピーして2本持つと、片方だけ直して食い違います。
compose.override.yaml は自動で重なる
services:
app:
environment:
APP_NAME: dev-override
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"
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 を書きます。
本番用のファイルを別に置く
services:
web:
ports: !override
- "127.0.0.1:8100:80"
app:
environment:
APP_NAME: prod
adminer:
profiles:
- never
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 のメッセージを変えます。
APP_NAME=dev-override db=OK
v2 になっていません。
docker compose upは、イメージを作り直しません。 すでに作ってあるイメージをそのまま使います。app.jsはイメージの中にCOPYされているので、作り直さない限り古いままです。
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 | キャッシュを使わずにビルド | レイヤーキャッシュが効きすぎて古いものを掴むとき |
判断はこの順です。
build:を書いたサービスのソースを直した →--buildimage:のタグは同じだが中身が新しくなった →--pull alwayscompose.yamlを直した →up -dだけでよい(差分を見て作り直してくれる)- 何も変えていないが状態を捨てたい →
--force-recreate
--force-recreate はコンテナを作り直すだけで、ボリュームは消しません。 データを消したいわけではないなら、これで十分です。
⑧ ログを絞る
サービスが3つあると、全部混ざって読めません。
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つです。
docker compose logs は、down で消したコンテナのログは出しません。 落ちた原因を追うときは、down する前に読んでください。 私はこれで2回、原因が分からないまま作り直しました。
⑨ down と stop と down -v
混同すると、データが消えます。
| コマンド | コンテナ | ネットワーク | 名前付きボリューム | イメージ |
|---|---|---|---|---|
stop | 止まるが残る(start で再開) | 残る | 残る | 残る |
down | 消える | 消える | 残る | 残る |
down -v | 消える | 消える | 消える=データが消える | 残る |
down --rmi local | 消える | 消える | 残る | 自分でビルドしたものが消える |
確かめます。
local complab_db-data
down では残ります。
-vは取り返しがつきません。 「なんかおかしいから作り直そう」でdown -vを打つと、データベースの中身が全部消えます。 消したいのはコンテナなのか、データなのかを口に出してから打ってください。コンテナだけ作り直したいなら--force-recreateです。
消してしまったときに戻せるかどうかは、事前にバックアップを取っていたかで決まります。 取り方はボリュームの回にまとめてあります。
stop との違いも見ておきます。
NAME STATE
complab-app-1 exited
complab-db-1 exited
complab-web-1 exited
コンテナはそのまま残っているので、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 を並べたときも同じでした。上げたときのオプションを、下ろすときにも書くと覚えました。
後片づけ
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
見出しの行だけになれば片づいています。 ボリュームも消えたか見ます。
何も出なければ消えています。
実験で export したシェル変数を戻します。
何も出なければ戻っています。 ここを忘れると、別のプロジェクトで謎の値が入ります。
イメージとフォルダを消します。
~/stack(本線で作ったもの)は消していません。 この記事は~/complabの中だけで完結しています。
まとめ — 理解できたこと
depends_onは「コンテナが開始したか」しか見ない。 中のサービスが受付を始めたかは見ていないECONNREFUSEDは「届いたが誰も待っていない」。 名前が引けない・経路が無い場合とはエラーが変わるhealthcheck+condition: service_healthyで、準備完了まで待たせられるhealthcheckはtest/interval/timeout/retries/start_periodの5つ。 初期化が長いものにはstart_periodtestのコマンドは、そのイメージの中に無いと必ず失敗する(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-recreatelogsは--tailとサービス名で絞る。downするとログも読めなくなるstopは残る、downはデータが残る、down -vはデータが消える
参考リンク
- roadmap.sh — Docker
- Docker 公式 — Compose file: services
- Docker 公式 — Startup order と depends_on
- Docker 公式 — 環境変数の優先順位
- Docker 公式 — 変数の補間
- Docker 公式 — Compose のプロファイル
- Docker 公式 — 複数の Compose ファイルをマージする
- Docker 公式 — docker compose up
- Docker 公式 — docker compose config
- Docker 公式 — HEALTHCHECK
次に読む
この記事は 【深掘り】Docker の 8 / 11 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- depends_on と healthcheck / 環境変数の優先順位
- プロファイル・複数ファイル・up の使い分け
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント