※本記事はアフィリエイト広告(PR)を含みます。
ここまで Docker コースで、コンテナを1つ動かし、Compose で複数コンテナをまとめ、深掘りでボリュームやネットワークの中身まで見てきました。でも、「じゃあ自分のアプリを、DB付きで丸ごと立ててみて」と言われると、まだ手が止まります。
前回: Composeなら1コマンド — 複数コンテナをまとめる
これは Docker コースの「到達作品」の回です。 新しい知識はほとんど出てきません。これまでの Dockerの導入 / Compose、そして深掘りで見たボリューム・ネットワーク・レイヤーキャッシュ・ヘルスチェックを、1つの動くものに束ねる回です。
この記事のコマンドは、VMの中(Ubuntu Server)で打ちます。 Windows本体の PowerShell ではありません。前回までに Docker を入れた、あの Ubuntu Server に SSH で入って作業します。どのプロンプトで打っているかを常に意識してください。
理由は、はっきりしています。一つ一つのコマンドは打てても、それを「1つの成果」に束ねた経験が無いからです。アプリとDBを繋ぐ、データを残す、起動順を待つ——個々の知識は、束ねて初めて「作れる」に変わります。 そして束ねた結果が1ファイルに残るからこそ、それは「自分の環境でだけ動くもの」から「どこでも同じ形で立つもの」に変わります。
この記事は、新しい知識を足す回ではありません。これまで学んだことを1つの動く成果にまとめ、最後に「1コマンドで、アプリ+DBが丸ごと立ち上がる」を自分のVMで動かして、Docker コースを締める回です。
対象レベル: 中級 / 区分: 必修
めがける作品
このコースを終えたら、これができるようになっている。 ——そう言い切れる1本を、ここで作ります。
作るのは大げさなものではありません。「開くたびに回数を数えて返す、小さな Web アプリ」と、その数を覚えておくデータベース(Postgres)の、2つのコンテナです。地味に見えますが、Docker コースの基礎が全部入っています。
そして、それを次の1行で立ち上げます。
この1行だけで、こうなることを目指します。
- アプリのコンテナと、DBのコンテナが、同時に立ち上がる
- アプリからDBに、
dbという名前だけで繋がる(IPアドレスを書かない) - DBの「準備完了」を待ってからアプリが動き出す(起動順の待ち合わせ)
- 開いた回数がDBに残り、
docker compose downで止めても消えない(ボリュームで永続化) docker compose down -vで初めて、データごと消える- DBのパスワードは、イメージの中ではなく
.envに分かれている
完成すると、こういう関係になります。
docker compose up -d
│
┌───────────────┴────────────────┐
▼ ▼
┌───────────┐ db という名前で ┌──────────────┐
│ app │ ───────────────▶ │ db │
│ (Node) │ ポート5432 │ (Postgres) │
│ :3000 │ │ │
└─────┬──────┘ └──────┬────────┘
│ 3000番を公開 │ データは
▼ ▼
あなたのブラウザ 名前付きボリューム db-data
(VMのIP:3000) (コンテナを消しても残る)
この図の全部——2つのコンテナ、名前での繋がり、公開ポート、消えないボリューム——を、docker-compose.yml というたった1枚のファイルに書きます。そして docker compose up -d の1行で、この図が丸ごと立ち上がる。図とファイルと1コマンドが、きれいに一対一で対応する——これが、この記事で体感してほしいことです。
そして最後に、「自分のVMでは動く」を1ファイルにできた——これが再現性の第一歩だった、というところまで持っていきます。
この記事でわかること
- 「Docker のコマンドを覚えた」と「アプリを1コマンドで立てられる」は別であること。埋めるのは、手を動かす1本だけであること
- 手で「アプリ起動 → DB起動 → 繋ぐ」をやると、環境が人によってずれ、手順を必ず忘れること。それを compose 1ファイルに畳むと、誰の環境でも同じ形で立つこと
- コンテナ同士は
localhostでは繋がらないこと。繋ぐのはサービス名(db)であること - コンテナを消すとDBのデータも消えること。それを防ぐのが名前付きボリュームで、
downでは残りdown -vで消えること depends_onだけでは「DBの準備完了」を待たないこと。待たせるにはヘルスチェックが要ること- DBのパスワードをイメージに焼いてはいけないこと。設定は環境変数で外から渡し、
.envは Git に入れないこと
この記事でやること
- 何を1コマンドにするかを決める(アプリ+DBの2コンテナ)
- アプリを Dockerfile にする(
FROM/COPY/RUN/CMDと.dockerignore) - compose で2コンテナを繋ぐ(サービス名で解決する)
- ボリュームでデータを永続化し、
downとdown -vの違いを実演する - ヘルスチェックで起動順を待ち合わせる
- 設定を環境変数(
.env)に追い出す - 完成の判定(チェックリスト)を自分で通す
先に知る言葉
この記事で軸になる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| イメージ | コンテナの「型」。アプリと必要なものを1つに固めた読み取り専用のかたまり |
| コンテナ | イメージから起動した、実際に動いているプロセス。消しても、また作れる |
| サービス | compose の中の、コンテナ1種類ぶんの定義。ここでは app と db の2つ |
| Dockerfile | イメージの作り方を書いた手順書。FROM から始まる |
| ボリューム | コンテナの外にある、消えないデータ置き場。コンテナを消しても残る |
| サービス名解決 | app から db という名前でDBに繋がる仕組み。IPを書かなくてよい |
| ヘルスチェック | コンテナが「起動した」だけでなく「準備できた」かを確かめる仕組み |
| 環境変数 | コンテナの外から渡す設定。パスワードなど、イメージに焼きたくない値を入れる |
.env | 環境変数をまとめて書くファイル。秘密が入るので Git に入れない |
① 何を1コマンドにするか — まず、手でやると何が起きるか
いきなりファイルを書く前に、「なぜ1コマンドにしたいのか」をはっきりさせます。 ここが分かっていないと、compose はただの写経になります。
もし compose を使わずに、手でこれをやるとどうなるか。だいたい、こういう順番になります。
1. DBのコンテナを docker run で立てる(ポート・パスワード・保存先を指定)
2. DBが起動しきるのを、なんとなく待つ
3. アプリのイメージをビルドする
4. アプリのコンテナを docker run で立てる(DBのアドレスを教える)
5. 繋がらない → アドレスが違う、パスワードが違う、DBがまだ準備中……を1つずつ潰す
これの何がつらいか。 動いたとして、その手順はあなたの頭の中と、打ち終わったターミナルの履歴にしかありません。
- 1週間後の自分が、同じ順番・同じオプションを再現できない
- 他の人に「これ動かして」と渡せない(口で説明するしかない)
- VMを作り直したら、また最初から手で並べ直す
「自分の環境では動く」の正体は、たいていこの「手順が記録されていない」ことです。 compose がやってくれるのは、この手順の全部を1つのファイルに畳むことです。ファイルがあれば、docker compose up -d の1行で、誰の・いつの環境でも同じ形が立ちます。
手でやると、こう並ぶ
具体的に、compose を使わず手で並べると、これだけのコマンドになります。 (雰囲気を見るためのもので、いま打つ必要はありません。)
問題は、これが「動いた瞬間」の記録が残らないことです。 どのオプションを付けたか、どの順で打ったか、ネットワークを作ったか——全部あなたの記憶頼みです。しかも、\ で改行したこの長い1行は、docker run の長いオプションそのもので、深掘りでも「読めない」と書いたやつです。
compose は、この全部を1つの docker-compose.yml に置き換えます。 対応はこうです。
| 手で打っていたもの | compose ではどこに書くか |
|---|---|
docker build -t myapp ./app | app の build: ./app |
-p 3000:3000 | app の ports: |
-e PGHOST=db など | app の environment: |
-v db-data:/var/lib/... | db の volumes: + トップの volumes: |
docker network create / connect | compose が自動でやる(何も書かなくていい) |
| 「DBの準備を待つ」 | depends_on: + healthcheck: |
ネットワークだけは、手だと3コマンド要ったのに、compose では1行も書きません。 compose は、同じファイルのサービスを最初から同じネットワークに入れてくれます。だからサービス名だけで繋がります。「書かなくていいことが増える」のが、compose の効き目です。
この記事で作るもの
大きなアプリは要りません。基礎が全部通る、いちばん小さな組み合わせにします。
| サービス | 中身 | 役割 |
|---|---|---|
app | 小さな Node のWebサーバー | 開かれるたびにDBに1行足し、「何回開かれたか」を返す |
db | Postgres | その「回数」を覚えておく。アプリを消しても、ここが残っていれば数は消えない |
「開いた回数を数える」だけのアプリにしたのは、わざとです。 これなら、データがDBに本当に残っているかが、画面の数字を見るだけで分かります。down して up して、数が続いていれば「残った」、1に戻っていれば「消えた」。永続化の成否が、目で見えるアプリにしました。
作るファイルの全体像
最終的に、こういう形になります。この地図を、頭の隅に置いておいてください。
myapp/
├── docker-compose.yml ← 2つのコンテナと、繋ぎ方・保存先をここに書く
├── .env ← パスワードなどの秘密(⚠️ Gitに入れない)
├── .env.example ← 「こういう変数が要る」の見本(こちらはGitに入れてよい)
├── .gitignore
└── app/
├── Dockerfile ← アプリのイメージの作り方
├── .dockerignore
├── package.json
└── server.js ← アプリ本体(数十行)
まず、VMの中に作業フォルダを用意します。
確認: pwd で /home/あなたのユーザー名/myapp が出て、ls でまだ何も無ければ、ここが出発点です。
この記事のコマンドは、ここから最後まで、すべて VM の中の ~/myapp で打ちます。 Windows の PowerShell ではありません。
② アプリを Dockerfile にする — キャッシュが効く順番で書く
まず、アプリ本体を書きます。 Node の標準機能と、Postgres に繋ぐ pg という部品だけを使います。凝ったことはしません。
~/myapp/app/server.js を作ります。
const http = require("http");
const { Pool } = require("pg");
// 接続情報は「環境変数」から読む。ここに直書きしないのが大事(⑥で回収する)。
// PGHOST / PGUSER / PGPASSWORD / PGDATABASE を pg が自動で読む。
const pool = new Pool();
// 起動時に一度だけ、テーブルが無ければ作る。
async function init() {
await pool.query(`
CREATE TABLE IF NOT EXISTS visits (
id serial PRIMARY KEY,
seen_at timestamptz NOT NULL DEFAULT now()
)
`);
}
const server = http.createServer(async (req, res) => {
// ヘルスチェック用。DBに触らず、生きてることだけ返す。
if (req.url === "/health") {
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("ok");
return;
}
try {
// 開かれるたびに1行足して、総数を数え直す。
await pool.query("INSERT INTO visits DEFAULT VALUES");
const result = await pool.query("SELECT count(*)::int AS n FROM visits");
const n = result.rows[0].n;
res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
res.end(`このページは ${n} 回開かれました\n`);
} catch (err) {
// DBにまだ繋がらないときは、ここに落ちる。500を返す。
res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
res.end("DBに繋がりませんでした\n");
}
});
// テーブルを用意してから、ポートを開く。
init()
.then(() => {
server.listen(3000, () => console.log("listening on 3000"));
})
.catch((err) => {
console.error("init failed:", err.message);
process.exit(1);
});
接続情報を new Pool() に直接書いていないのがポイントです。pg は PGHOST PGUSER PGPASSWORD PGDATABASE という環境変数を自動で読みます。「どのDBに、どのパスワードで繋ぐか」は、コードの外から渡す——これが⑥に繋がります。いまは「そう書いてある」とだけ覚えてください。
~/myapp/app/package.json を作ります。使う部品は pg 1つだけです。
{
"name": "compose-capstone",
"version": "1.0.0",
"private": true,
"main": "server.js",
"dependencies": {
"pg": "^8.11.0"
}
}
Dockerfile — 4つの命令の意味
このアプリを「イメージ」にする手順書が Dockerfile です。 ~/myapp/app/Dockerfile を作ります。
# ① 土台にする既製イメージ。Node が入った軽いやつ。
FROM node:24-alpine
# ② コンテナの中の作業場所。以降のコマンドはここで動く。
WORKDIR /app
# ③ まず package.json だけコピーして、部品を入れる。
COPY package*.json ./
RUN npm install --omit=dev
# ④ そのあとで、残りのソースをコピーする。
COPY . .
# ⑤ このイメージは3000番で待つ、という「宣言」。
EXPOSE 3000
# ⑥ コンテナが起動したら実行するコマンド。
CMD ["node", "server.js"]
それぞれの命令が何をしているか。
| 命令 | やること |
|---|---|
FROM | 土台のイメージを選ぶ。ここでは Node 入りの軽い(alpine)イメージ |
COPY | ホスト(app/ の中)のファイルを、イメージの中へ持ち込む |
RUN | イメージを作る途中で実行するコマンド。ここでは部品のインストール |
CMD | できあがったコンテナを起動したときに走るコマンド。RUN との違いに注意 |
RUN と CMD は別物です。 RUN はイメージを作るときに一度走り、その結果がイメージに焼き込まれます。CMD はコンテナを起動するたびに走ります。ここを混同すると「ビルドは通るのに起動で何もしない」になります。
なぜ node:24-alpine なのか
FROM で選ぶ土台イメージには、いくつも種類があります。 node:24、node:24-slim、node:24-alpine……。末尾の違いは、土台に入っている「OSの部分」の大きさです。数字の 24 は Node.js の版で、サポート期間中(LTS)の版を選びます(Node.js 20 は 2026年4月30日でサポートが終了しています)。
node:24(無印)は、Debian という中身の詰まったOSの上に Node が載っています。何でも入っているぶん、大きいnode:24-alpineは、Alpine Linux という極端に小さいOSの上に Node が載っています。数百MB小さくなります
小さいイメージは、ビルドも配布も速く、攻撃されうる面も小さいので、まずは alpine を選ぶのが定石です。ただし alpine は一部のツールが最初から入っていないので、RUN apt install(Debian系のコマンド)が効きません(alpine は apk)。この記事のアプリは追加インストールが要らないので、alpine で問題ありません。イメージのサイズをどこまで削れるかは、深掘りの1.2GBのイメージが80MBになるの考え方に繋がります。
npm install と npm ci の違い
この記事では RUN npm install --omit=dev にしました。 --omit=dev は「開発用の部品(テスト道具など)は入れない」の意味で、本番用イメージを軽くします。
チームや本番では、npm install より npm ci が向いています。 npm ci は package-lock.json(部品の正確なバージョンを固定したファイル)どおりに入れるので、「手元と本番で部品のバージョンがずれる」を防ぎます。 ただし npm ci は lock ファイルが必須です。この記事は lock を作らない最小構成なので npm install にしていますが、本番に近づけるなら lock をコミットして npm ci に替える、と覚えておいてください。
なぜ package.json を先にコピーするのか — レイヤーキャッシュ
③と④で、コピーを2回に分けているのが不自然に見えるかもしれません。COPY . . で一気に全部入れればいいのでは、と。分けているのには理由があります。
Dockerfile は、上から1命令ずつ「レイヤー」を積みます。そして、変わっていないレイヤーはキャッシュが再利用されます。
- ソースを1行直しただけなら、変わるのは
COPY . .(④)から下だけ package.jsonを触っていなければ、③のnpm installはキャッシュが効いて、再実行されない- もし
COPY . .を先に1回で書いていたら、ソースを1行直すたびにnpm installが毎回走ります(部品は何も変わっていないのに)
「変わりにくいもの(依存関係)を上に、変わりやすいもの(自分のコード)を下に」——この順番が、ビルドを速くします。ここは深掘りの回で詳しくやりました。レイヤーキャッシュは行の順番で決まる — Docker深掘りに、実際に測った記録があります。
.dockerignore — 要らないものを持ち込まない
~/myapp/app/.dockerignore を作ります。
node_modules
npm-debug.log
.env
.git
これが無いと、COPY . . でホスト側の node_modules や .env まで丸ごとイメージに入ります。 node_modules はイメージの中で npm install して作り直すので、持ち込むと無駄に重くなるうえ、OSが違うと壊れます。そして .env(秘密)をイメージに焼き込む事故も、これで防ぎます。 .gitignore の Docker 版だと思ってください。
確認: ここまでで app/ の中に4ファイル(Dockerfile / .dockerignore / package.json / server.js)が揃います。
.dockerignore . から始まるファイルも見たいので ls -a です。4つ見えれば次へ。
アプリだけ、先にビルドして確かめる
compose に進む前に、「アプリのイメージが、単体でちゃんとビルドできるか」だけを確かめておきます。 全部を一度に組んでから動かすと、失敗したときに「どこが悪いのか」が分かりません。 部品ごとに動作を確かめてから束ねると、切り分けが楽になります。
docker build は、Dockerfile どおりにイメージを作るコマンドです。-t myapp-test は「できたイメージに myapp-test という名前を付ける」の意味、末尾の ./app は「app/ フォルダの Dockerfile を使う」の意味です。
途中で、レイヤーが1つずつ積まれていくのが表示されます。
=> [1/5] FROM docker.io/library/node:24-alpine
=> [2/5] WORKDIR /app
=> [3/5] COPY package*.json ./
=> [4/5] RUN npm install --omit=dev
=> [5/5] COPY . .
=> exporting to image
=> => naming to docker.io/library/myapp-test
[4/5] RUN npm install のところでエラーが出たら、package.json の書き間違いです。ここが通れば、アプリのイメージは正しく作れています。この確認用イメージは、もう要らないので消しておきます。
単体でビルドが通ることを見ておくと、このあと compose で失敗したとき「ビルドは問題ない → 繋ぎ方の問題だ」と、すぐ切り分けられます。 一度に全部を疑わなくて済みます。
③ compose で2コンテナを繋ぐ — 名前で繋がる
ここが束ねる作業の中心です。 アプリとDB、2つのコンテナと、その繋ぎ方を、1ファイルに書きます。
~/myapp/docker-compose.yml を作ります。まずは骨組みだけ(ボリュームとヘルスチェックは④⑤で足します)。
services:
app:
build: ./app
ports:
- "3000:3000"
environment:
PGHOST: db
PGUSER: ${POSTGRES_USER}
PGPASSWORD: ${POSTGRES_PASSWORD}
PGDATABASE: ${POSTGRES_DB}
depends_on:
- db
db:
image: postgres:16
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
読み方を、上から。
services:の下に、コンテナ1種類ぶんを1つずつ書きます。ここではappとdbappのbuild: ./appは、「app/フォルダの Dockerfile からイメージをビルドして使う」という意味。②で書いたものですdbのimage: postgres:16は、「Postgres の既製イメージをそのまま使う」。DBは自分で作らず、公式のを借ります
build: と image: の使い分けが、ここで出てきます。 自分で中身を書くもの(アプリ)は build: で Dockerfile から作り、すでに世の中にある完成品(Postgres)は image: で借りる。 DBを自分で Dockerfile から作る必要はありません。「作るのは自分のアプリだけ。ミドルウェアは公式イメージを借りる」——これが実務でも基本の形です。借りる Postgres の詳しい使い方は公式イメージのページに、環境変数の一覧まで載っています。
ports: "3000:3000"は、「VMの3000番を、アプリコンテナの3000番に繋ぐ」。左がVM側、右がコンテナ側ですenvironment:は、そのコンテナに渡す環境変数。${...}は⑥で作る.envから埋まります
その1: なぜ PGHOST が db なのか
アプリの PGHOST に db と書いてあります。 これは、⑤で見るサービス名です。
compose は、同じファイルのサービスを、サービス名だけで繋げてくれます。 app の中から db という名前を呼ぶと、compose がDBコンテナのIPに解決してくれる。IPアドレスを一切書かなくていい——これが「サービス名解決」です。
そして、初心者が必ず一度はやる間違いがこれです。
PGHOST に localhost と書いても、DBには繋がりません。
- コンテナの中の
localhostは、そのコンテナ自身を指します appコンテナの中でlocalhostと言うと、それは「app 自身」であって、DBではない- コンテナは1台ずつ別の小さな箱です。箱の中の
localhostは、その箱の中だけ
繋ぎたい相手は、相手のサービス名(db)で呼ぶ。 ここは深掘りで実際に切り分けました。localhostで繋がらないのは当然 — Docker深掘りを読むと、なぜそうなるかが腑に落ちます。
いったん動かしてみる(まだ失敗してよい)
⑥の .env がまだ無いので、このままでは変数が埋まりません。 先に⑥の .env を作ってから動かします。ここでは「2サービスが書けた」ことだけ確認します。
docker compose config は、実際には起動せず、「compose がこのファイルをどう解釈したか」を展開して見せるコマンドです。書式ミスや変数の埋まり方を、起動前に確かめられます。この時点では変数が空という警告が出ますが、それで正常です。
.env を作ったあとで打つと、${POSTGRES_USER} などが埋まった、こういう展開が返ります(一部)。
name: myapp
services:
app:
build:
context: /home/あなた/myapp/app
depends_on:
db:
condition: service_healthy
environment:
PGDATABASE: appdb
PGHOST: db
PGUSER: appuser
...
ここで注目してほしいのは、PGPASSWORD の値が展開後には見えてしまうことです。config は「compose が最終的にどう読んだか」を全部見せるので、画面共有や貼り付けのときに、うっかりパスワードを出さないよう気をつけてください。 秘密が .env に分かれていても、config は展開してしまいます。
書式(YAML)を間違えていると、この config がエラーで止まります。 「up して初めて気づく」より、config で先に弾いておくほうが、原因が分かりやすい。新しく書いたら config、が習慣になると事故が減ります。
「db という名前で繋がる」を、目で確かめる(任意)
サービス名で繋がる、という話を、実際に見てみます。(⑥まで終えて up -d したあとに試せます。任意です。)
app コンテナの中に入って、db という名前が本当に引けるかを見ます。
docker compose exec app sh は、「動いている app コンテナの中で、シェルを開く」コマンドです。プロンプトがコンテナの中のものに変わります。そこで、db という名前を引いてみます。
db に対してIPアドレスが1行返れば、名前解決ができています。 172で始まる、compose が割り当てた内部IPのはずです。これが、PGHOST=db だけで繋がっていた正体です。一方 getent hosts localhost を引くと、返るのは 127.0.0.1——つまり app 自身で、DBではありません。「localhost では繋がらない」が、ここで実物として見えます。確認したら exit でコンテナから出ます。
④ データを消さない(ボリューム)
ここがこの記事のいちばん大事なところです。 いま作った db には、致命的な問題があります。
コンテナを消すと、DBのデータも一緒に消えます。
コンテナは「使い捨て」が前提です。中に書き込んだファイルは、そのコンテナを消した瞬間、一緒に消えます。 DBのデータもコンテナの中にあるので、docker compose down でコンテナを片づけると、溜めたデータが丸ごと吹き飛びます。
これはバグではなく、コンテナの仕様です。 だからこそ、消えては困るデータは、コンテナの外に置く。 それが「名前付きボリューム」です。
ボリュームを足す
docker-compose.yml を、こう書き換えます(db に volumes: を足し、ファイルの末尾に volumes: の宣言を足す)。
services:
app:
build: ./app
ports:
- "3000:3000"
environment:
PGHOST: db
PGUSER: ${POSTGRES_USER}
PGPASSWORD: ${POSTGRES_PASSWORD}
PGDATABASE: ${POSTGRES_DB}
depends_on:
- db
db:
image: postgres:16
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
volumes:
- db-data:/var/lib/postgresql/data
volumes:
db-data:
2か所、足しました。
dbの下のvolumes:— 「db-dataという名前のボリュームを、コンテナの中の/var/lib/postgresql/dataに繋ぐ」。この場所は、Postgres がデータを書き込む場所です。そこを、コンテナの外のボリュームに逃がしています- ファイル末尾の
volumes:— 「db-dataという名前付きボリュームを使う」という宣言。services:と同じ高さ(インデント0)に書きます
db-data:/var/lib/postgresql/data の左右の意味は、ports と同じ発想です。左がボリュームの名前、右がコンテナの中のパス。 Postgres がデータを書き込む場所(右)を、消えない場所(左)に繋いでいます。
末尾の volumes: 宣言を忘れると、compose が refers to undefined volume db-data というエラーで止まります。 「db の中の volumes」と「トップレベルの volumes」の2つが要る、と覚えてください。ここは深掘りで詳しくやりました。コンテナを消すとデータも消える — Docker深掘りを参照。
down では残り、down -v で消える — 目で確かめる
⑥の .env を作ったら(次の節)、この永続化を必ず自分の目で確かめます。ここを実演しないと、「たぶん残る」で終わってしまいます。
やることは、こういう流れです(⑥まで終えてから実行してください)。
3回開けば「3回開かれました」と返るはずです。ここで、コンテナを止めて片づけます。
ここで「4回開かれました」と続けば、成功です。 コンテナは一度消えたのに、数が3から続いた——データはコンテナの外(ボリューム)に残っていた証拠です。
そして、消えることも確かめます。
今度は「1回開かれました」に戻ります。 -v(--volumes)を付けると、名前付きボリュームまで消えます。down と down -v の違いが、この数字の差です。
ボリュームが「そこにある/消えた」は、コマンドでも見えます。
down(-vなし)のあとは、こういう行が残っています。
DRIVER VOLUME NAME
local myapp_db-data
コンテナは消えても、myapp_db-data というボリュームは残っているのが見えます。名前の頭に myapp_(プロジェクト名)が付くのは、compose が付ける目印です。そして down -v のあとに同じ docker volume ls を打つと、この行が消えています。 数字が1に戻ったのと、この行が消えたのは、同じことを別の角度から見ているだけです。
| コマンド | コンテナ | ボリューム(データ) |
|---|---|---|
docker compose stop | 止めるだけ(残る) | 残る |
docker compose down | 消す | 残る |
docker compose down -v | 消す | 消える |
down -v は「初期状態に戻したいとき」だけに使う、と覚えてください。 何気なく打つと、溜めたデータが消えます。
スクリーンショットを撮ってください:
01_downしても数が続く.pngcurlを数回打って数を増やし →docker compose down→up -d→ もう一度curlで数が続いている、という一連を撮ってください。数字が「消えずに続いている」ことが見えるように。
⑤ 起動順と待ち合わせ — depends_on だけでは待たない
③で depends_on: - db を書きました。 これで「DBが先、アプリが後」の順番になります。……なりますが、これだけでは足りません。
depends_on は「DBコンテナを先に起動する」までしか面倒を見ません。「DBが接続を受け付けられる状態になった」までは待ちません。
Postgres は、コンテナが起動してから、実際に接続を受け付けるまでに数秒かかります。その間にアプリが繋ぎに行くと、「DBに繋がりませんでした」で落ちます。 ②の server.js で init() が失敗すると process.exit(1) するように書いたのは、まさにこれが起きるからです。
「アプリが先に立ち上がって、DBがまだ準備中で、繋がらずに落ちる」——これは深掘りでも実演しました。depends_onを書いても落ちる — Docker深掘りに、そのときのログが残っています。
ヘルスチェックを付ける前に up すると、アプリのログにこういう行が出ます。
app-1 | init failed: connect ECONNREFUSED 172.18.0.2:5432
app-1 exited with code 1
ECONNREFUSED(接続を拒否された)は、「相手(DB)は居るが、まだ接続の窓口を開けていない」という意味です。「DBが無い」のではなく「DBがまだ準備中」——だから、繋ぎ先が間違っているわけではありません。ここを取り違えて PGHOST をいじり始めると、迷子になります。直すのは繋ぎ先ではなく、待ち方です。
ヘルスチェックで「準備完了」を待つ
解決は2段階です。「DBが準備できたか確かめる方法(ヘルスチェック)」を db に付け、「アプリはその準備完了を待つ」を app に書きます。
docker-compose.yml の完成形です。今度は全文を載せます。
services:
app:
build: ./app
ports:
- "3000:3000"
environment:
PGHOST: db
PGUSER: ${POSTGRES_USER}
PGPASSWORD: ${POSTGRES_PASSWORD}
PGDATABASE: ${POSTGRES_DB}
depends_on:
db:
condition: service_healthy
restart: unless-stopped
db:
image: postgres:16
environment:
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: ${POSTGRES_DB}
volumes:
- db-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 5s
timeout: 3s
retries: 5
volumes:
db-data:
変わったのは3か所です。
dbのhealthcheck:— 5秒ごとにpg_isready(Postgres が接続を受け付けられるか確かめるコマンド)を実行します。成功すれば、そのコンテナは「healthy(準備完了)」と印が付きますappのdepends_on— 書き方が- dbから、db: condition: service_healthyに変わりました。これで「DBが healthy になるまで、app を起動しない」になりますappのrestart: unless-stopped— 何かの拍子にアプリが落ちても、自動で立て直します。人が明示的に止めたときだけは、立て直しません
healthcheck と condition: service_healthy は、必ずセットです。 DB側に「準備できたか確かめる方法」を書き、アプリ側に「その準備完了を待つ」と書く。片方だけでは効きません。
pg_isready は Postgres のイメージに最初から入っているコマンドなので、追加インストールは要りません。ただし test の ["CMD-SHELL", ...] の書式は崩さないでください。角括弧とダブルクォートを消すと、compose が読めなくなります。
確認: ⑥の .env を作ったら、docker compose up -d して、次で状態を見ます。
db の STATUS 欄に (healthy) と出ていれば、ヘルスチェックが効いています。 そして app は、その (healthy) になるまで起動を待ってから立ち上がっています。
スクリーンショットを撮ってください:
02_ps_healthy.pngdocker compose psの出力で、dbに(healthy)が付き、appがUpになっている状態を撮ってください。「待ってから立った」ことが分かるように。
⑥ 設定は環境変数で — パスワードをイメージに焼かない
ここまで ${POSTGRES_USER} のような書き方を、埋めずに残してきました。 その正体がこれです。
DBのユーザー名やパスワードを、Dockerfile や compose ファイルに直書きしてはいけません。
- ファイルに直書きすると、Git に上げた瞬間、パスワードが世界に公開されます
- イメージに焼き込むと、そのイメージを持っている人は、誰でもパスワードを取り出せます
- 環境(開発用・本番用)でパスワードを変えたいのに、ファイルを書き換えることになります
だから、秘密は「コードの外」に置く。 それが .env ファイルです。
.env を作る
~/myapp/.env を作ります(app/ の中ではなく、docker-compose.yml と同じ場所)。
POSTGRES_USER=appuser
POSTGRES_PASSWORD=change-me-please
POSTGRES_DB=appdb
POSTGRES_PASSWORD の値は、ここでは説明用のダミーです。 change-me-please のような「本物ではない、明らかに仮の値」にしてあります。自分で動かすときは、自分だけが知る値に変えてください。 そして、この記事にも、Git にも、本物のパスワードは絶対に書きません。
compose は、同じフォルダの .env を自動で読み込み、ファイル中の ${POSTGRES_USER} などを、ここの値で埋めます。だから③④⑤で書いた ${...} が、ここで初めて意味を持ちます。
.env は Git に入れない — .gitignore と .env.example
.env は秘密なので、Git に入れません。 そのために ~/myapp/.gitignore を作ります。
.env
node_modules
そして、「どんな変数が要るか」だけは、チームや将来の自分に伝えたい。 そこで、値を空にした見本を ~/myapp/.env.example として作り、こちらはGitに入れます。
# これは見本です。コピーして .env を作り、値を埋めてください。
# cp .env.example .env
POSTGRES_USER=
POSTGRES_PASSWORD=
POSTGRES_DB=
「.env は入れない、.env.example は入れる」——これがひとつの型です。秘密の値は渡さず、「秘密の形(どんなキーが要るか)」だけを渡します。秘密の扱いをもっと踏み込むと、暗号化して Git に置く方法まであります(今は要りません。ずっと先の話です)。
いよいよ、1コマンドで立てる
ファイルが全部揃いました。 出発点の1コマンドを、今度こそ打ちます。
-d(detached)は「バックグラウンドで動かす」の意味です。付けないと、ログが画面に流れ続けて、ターミナルが戻ってきません。初回はアプリのイメージをビルドするので、少し時間がかかります。
繋がるか確かめます。
「このページは 1 回開かれました」と返れば、全部が繋がっています。 アプリが立ち、DBの準備完了を待ち、db という名前でDBに繋がり、テーブルを作り、1行足して数えた——ここまでが、この1回の curl で通っています。
VMの外(Windows本体のブラウザ)から見たいときは、localhost ではなく VMのIPアドレス(例: http://192.168.x.x:3000/)です。localhost はあくまで「VM自身」を指します。VMのIPは、VMの中で ip a を打つと確認できます。
スクリーンショットを撮ってください:
03_ブラウザで確認.pngWindows本体のブラウザからhttp://VMのIP:3000/を開き、「このページは N 回開かれました」が表示された画面を撮ってください。1コマンドで立てたアプリが、外から見えていることが分かるように。
うまくいかないときは、ログを見る
一発で繋がらないことのほうが、むしろ普通です。 そのとき、あてずっぽうで直さないための道具が3つあります。
まず、いま何が立っているかを見ます。
app が Exited (1) になっていたら、アプリが起動に失敗して落ちています。 db が (health: starting) のままなら、まだ準備中です。「立っているか」「落ちているか」「準備中か」を、まずここで見分けます。
落ちているアプリの理由は、ログに出ています。
エラーは、たいてい下(新しいほう)にあります。 ECONNREFUSED ならDBの待ち合わせ(⑤)、password authentication failed ならパスワードの不一致(⑥の .env)、getaddrinfo ENOTFOUND なら繋ぎ先の名前が違う(③の PGHOST)——エラーの言葉が、どの節に戻ればいいかを教えてくれます。
動いている様子を、流れるまま見たいときは -f を付けます。
-f(follow)は、ログが出続けるのを見張るモードです。別のターミナルで curl を打つと、アプリのログに処理が流れるのが見えます。止めるときは Ctrl+C(ログを止めるだけで、コンテナは止まりません)。
設定を変えたのに反映されないときは、作り直します。
--build を付けると、イメージをビルドし直してから立ち上げます。 Dockerfile やソースを変えたのに反映されないときは、たいていこれで直ります。compose ファイルだけを変えたときは --build は要らず、docker compose up -d だけで差分が反映されます。
⑦ 完成の判定 — 自分で「できた」と言えるように
「なんとなく動いた」で終わらせません。 この6つを自分で通したら、この作品は完成です。1つずつ、実際にコマンドで確かめます。
□ docker compose up -d の1行で、app と db が両方立つ
□ curl http://localhost:3000 で「N 回開かれました」が返る(アプリからDBに繋がっている)
□ docker compose ps で db に (healthy) が付き、app がそれを待って立っている
□ 数を増やしてから down → up で、数が続く(ボリュームで残っている)
□ down -v → up で、数が 1 に戻る(-v で初めて消える)
□ パスワードが .env に分かれていて、compose ファイルにもイメージにも直書きされていない
最後の1つは、こう確かめられます。
何も出てこなければ正解です。 パスワードの値は .env にしか無く、ファイルには ${POSTGRES_PASSWORD} という「入れ物」しか書かれていない、という状態です。
1つでも通らなかったら、それがこのコースの「まだ手が届いていない場所」です。 そこだけ、対応する節(③〜⑥)や、リンクした深掘りの回に戻ればいい。この判定リストが、「Dockerを触った」を「1コマンドで環境を立てられる」に変えます。
いちばん効く確認 — 別のVM(または別フォルダ)で再現する
この作品の本当の完成条件は、「別の場所でも、同じ1コマンドで立つ」ことです。 「自分のこのVMでだけ動く」なら、compose を使う意味の半分を捨てています。
いちばん手軽な確認は、フォルダごとコピーして、別の場所で立て直すことです。
.env も一緒にコピーされるので、これはそのまま立ちます。 もし別のVMやGitHub経由で渡すなら、⑥で分けた .env は付いてきません(Gitに入れていないので)。そのときは、相手の環境で .env.example をコピーして .env を作り、値を埋めるところから始めます。
この「フォルダ+.envさえあれば、どこでも同じ形が立つ」——これが、①で「手でやると再現できない」と言ったことの答えです。 手順が docker-compose.yml という1枚の紙になったから、こうして配れるようになりました。
確認が終わったら、コピーは片づけます。
myapp と myapp-copy は、compose にとっては別プロジェクトなので、ボリュームも別々に作られます(myapp_db-data と myapp-copy_db-data)。片方を消しても、もう片方のデータには影響しません。
つまずいたところ
app が「DBに繋がりませんでした」を返して、すぐ落ちた。 depends_on を - db(起動順だけ)のまま、ヘルスチェックを付けていませんでした。DBがまだ準備中なのにアプリが繋ぎに行っていた。⑤の healthcheck + condition: service_healthy を足したら、待ってから立つようになりました。
PGHOST を localhost にしていて、ずっと繋がらなかった。 コンテナの中の localhost は「そのコンテナ自身」で、DBではありません。db(サービス名)に直したら一発で繋がりました。「相手はサービス名で呼ぶ」を忘れていました。
docker compose down したら、数が1に戻ってしまった(最初の版)。 ボリュームを付ける前でした。DBのデータがコンテナの中にしか無く、コンテナと一緒に消えていた。④の名前付きボリュームを足したら、down しても残るようになりました。
逆に、down -v したのに「消えない」と勘違いした。 別のターミナルで先に up し直していて、新しいデータで1から数え始めていただけでした。落ち着いて docker compose ps で状態を見るのが先でした。
ソースを1行直すたびに、ビルドがやたら遅かった。 Dockerfile で COPY . . を先に1回で書いていたので、毎回 npm install が走っていました。②のように package*.json を先にコピーする順に直したら、2回目以降のビルドが一気に速くなりました(レイヤーキャッシュが効いた)。
.env を Git に上げそうになった。 .gitignore に .env を入れる前に git add . していました。⑥の .gitignore と .env.example を用意して、秘密は入れない・見本だけ入れるに直しました。
healthcheck の test を書き換えたら、compose がエラーで読めなくなった。 ["CMD-SHELL", "..."] の角括弧やダブルクォートを崩していました。YAML は書式に厳しいので、docker compose config で展開して確かめてから up するようにしました。
ポートを変えたのに反映されなかった。 compose ファイルの設定を変えたなら、docker compose up -d で変わったサービスのコンテナが作り直されます。ですが、ソースや Dockerfile の側で変えたものはイメージに焼き込まれているので、up -d だけでは反映されません。そのときは docker compose up -d --build(イメージも作り直す)で作り直します。
後片づけ
この作品は、VMの中で動き続けます。 バックグラウンド(-d)で立てたので、放っておくとコンテナは動いたままです。確かめ終わったら、止めておきましょう。
down(-v なし)なら、溜めた数はボリュームに残ります。 次に up -d すれば、その続きから動きます。
この作品ごと、きれいさっぱり消したいときだけ、-v を付けます。
アプリのイメージも消したいときは、続けて確認できます。
フォルダ(~/myapp)自体は、残しておくことを勧めます。 docker-compose.yml があれば、いつでも docker compose up -d の1行で、また同じ環境が立ちます。 それが、この記事で作った本当の成果物です。
ディスクが減ってきたら
Docker を触っていると、使われなくなったイメージやボリュームが少しずつ溜まります。 いま何がどれだけ使っているかは、次で分かります。
Images Containers Local Volumes ごとに、使用量と「再利用できる(reclaimable)量」が出ます。 VMのディスクが減ってきたと感じたら、まずこれで現状を見ます。
どこからも使われていないものだけを、まとめて片づけたいときは、次を使います。
docker system prune は、止まっているコンテナや、どのコンテナも使っていないネットワーク、タグの無い(dangling)イメージを消します。 どのコンテナも使っていないイメージまで消すには -a が要ります。 ボリューム(データ)は既定では消しません。--volumes を付けても消えるのは名前の無い(匿名)ボリュームだけで、この記事の db-data のような名前付きボリュームは残ります。 これは「うっかりデータを消さない」ための、うれしい既定です。データごと消したいときだけ、意識して docker compose down -v(または docker volume rm)を打つ——down と down -v の関係と、同じ考え方です。
まとめ — 理解できたこと
- 「Docker のコマンドを覚えた」と「アプリを1コマンドで立てられる」は別物だった。埋めたのは、手を動かす1本
- 手で「アプリ起動 → DB起動 → 繋ぐ」をやると、手順が記録に残らず、再現できない。 compose 1ファイルに畳むと、
docker compose up -dの1行で誰の環境でも同じ形が立つ - コンテナ同士は
localhostでは繋がらない。 相手はサービス名(db)で呼ぶ。IPは書かない - コンテナを消すとDBのデータも消える。 消えては困るデータは名前付きボリュームでコンテナの外に逃がす
downは残り、down -vで初めて消える。 その違いを、画面の数字で目で確かめたdepends_onは起動順しか見ない。 「準備完了」を待つにはヘルスチェック+condition: service_healthyが要る。片方だけでは効かない- Dockerfile は上から積む。 変わりにくいもの(依存)を上、変わりやすいもの(自分のコード)を下に書くと、キャッシュが効いてビルドが速い
.dockerignoreでnode_modulesや.envを持ち込まない。 イメージが軽くなり、秘密の焼き込み事故も防げる- DBのパスワードをイメージや compose に直書きしない。
.envに追い出し、.envは Git に入れず、.env.example(見本)だけ入れる - 自分のアプリは
build:、ミドルウェア(Postgres)はimage:で借りる。 DBを自分で作る必要はない - 書式は
docker compose configで先に確かめる。 「upして初めてエラー」より、原因が分かりやすい - 繋がらないときは、あてずっぽうで直さず
docker compose psとlogsを見る。 エラーの言葉が、戻るべき節を教えてくれる - 完成の判定を自分で6つ持った。 「なんとなく動く」で終わらない
- フォルダ+
.envさえあれば、別のVMでも同じ1コマンドで立つ。 これが再現できる、ということ docker compose up -dの1行で、アプリ+DBが丸ごと立ち、データはボリュームで残せた。 これが Docker コースの到達点
そして、その先にあるもの
この作品で手にしたのは、「自分のVMでは、1ファイルで丸ごと再現できる」という状態です。これが再現性の第一歩です。 頭の中とターミナルの履歴にしか無かった手順が、docker-compose.yml という1枚の紙になった。
でも、この作品は「1台のVMで動く」までです。
- VMが1台落ちたら、アプリも止まります。 24時間動かし続けたいなら、それでは足りません
- アクセスが増えて、アプリを何台にも増やしたくなったら、compose だけでは手に負えなくなります
「複数台で、落ちても動かし続ける」を扱う道具が Kubernetesです。compose で束ねる考え方(サービス・ボリューム・ヘルスチェック)は、そのまま次の土台になります。Kubernetesは「状態を宣言する」 — minikube入門へ、この作品を持って進んでください。
そして、本番で動かすには、この記事では触れていない注意がまだあります。 イメージのサイズ、権限、再起動の方針、ログの出し方——それらは本番で決めることは8つある — Docker深掘りにまとめてあります。この作品を「本番で動かす」前に、必ず一度読んでください。
この作品はVMの中で完結しますが、VPSを1台借りて同じ compose を流すと、「どこでも1コマンドで立つ」ことを別の環境で確かめられます。たとえばシンVPS
は 50種類以上のOS・アプリイメージを無料で使え、大容量メモリプランの 2GB(2コア・50GB)が1ヶ月 1,040円〜36ヶ月 950円(税込・月額換算、2026-11 時点)です。無料のお試し期間は無く最低利用期間は3ヶ月なので、「試して壊す」用途なら契約期間と月額の差を見てから決めてください。
参考リンク
- roadmap.sh — DevOps
- Docker Docs — Docker Compose overview
- Docker Docs — Compose file: services
- Docker Docs — Compose file: volumes
- Docker Docs — Control startup and shutdown order
- Docker Docs — Dockerfile reference
- Docker Hub — postgres 公式イメージ
次に読む
この記事は 【第6段階】インフラとコンテナ の 5 / 25 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
Docker コースの到達作品です。 アプリとDBを compose 1コマンドで丸ごと立ち上げます。

コメント