1コマンドで環境が丸ごと立つ — Dockerの到達作品

Dockerの到達作品。コンテナのブロックとアプリの画面、データベース。

※本記事はアフィリエイト広告(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行で立ち上げます。

bash
$ docker compose up -d

この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. 何を1コマンドにするかを決める(アプリ+DBの2コンテナ)
  2. アプリを Dockerfile にする(FROM / COPY / RUN / CMD と .dockerignore)
  3. compose で2コンテナを繋ぐ(サービス名で解決する)
  4. ボリュームでデータを永続化し、down と down -v の違いを実演する
  5. ヘルスチェックで起動順を待ち合わせる
  6. 設定を環境変数(.env)に追い出す
  7. 完成の判定(チェックリスト)を自分で通す

先に知る言葉

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

言葉意味
イメージコンテナの「型」。アプリと必要なものを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 を使わず手で並べると、これだけのコマンドになります。 (雰囲気を見るためのもので、いま打つ必要はありません。)

bash
$ # DBを立てる。パスワードも保存先もポートも、全部この1行に押し込む
$ docker run -d --name db \
    -e POSTGRES_USER=appuser \
    -e POSTGRES_PASSWORD=change-me-please \
    -e POSTGRES_DB=appdb \
    -v db-data:/var/lib/postgresql/data \
    postgres:16

$ # アプリのイメージをビルドする
$ docker build -t myapp ./app

$ # アプリを立てる。DBと同じネットワークに入れて、繋ぎ先も手で教える
$ docker network create appnet
$ docker network connect appnet db
$ docker run -d --name app \
    --network appnet \
    -e PGHOST=db \
    -e PGUSER=appuser \
    -e PGPASSWORD=change-me-please \
    -e PGDATABASE=appdb \
    -p 3000:3000 \
    myapp

問題は、これが「動いた瞬間」の記録が残らないことです。 どのオプションを付けたか、どの順で打ったか、ネットワークを作ったか——全部あなたの記憶頼みです。しかも、\ で改行したこの長い1行は、docker run の長いオプションそのもので、深掘りでも「読めない」と書いたやつです。

compose は、この全部を1つの docker-compose.yml に置き換えます。 対応はこうです。

手で打っていたものcompose ではどこに書くか
docker build -t myapp ./appapp の build: ./app
-p 3000:3000app の ports:
-e PGHOST=db などapp の environment:
-v db-data:/var/lib/...db の volumes: + トップの volumes:
docker network create / connectcompose が自動でやる(何も書かなくていい)
「DBの準備を待つ」depends_on: + healthcheck:

ネットワークだけは、手だと3コマンド要ったのに、compose では1行も書きません。 compose は、同じファイルのサービスを最初から同じネットワークに入れてくれます。だからサービス名だけで繋がります。「書かなくていいことが増える」のが、compose の効き目です。

この記事で作るもの

大きなアプリは要りません。基礎が全部通る、いちばん小さな組み合わせにします。

サービス中身役割
app小さな Node のWebサーバー開かれるたびにDBに1行足し、「何回開かれたか」を返す
dbPostgresその「回数」を覚えておく。アプリを消しても、ここが残っていれば数は消えない

「開いた回数を数える」だけのアプリにしたのは、わざとです。 これなら、データがDBに本当に残っているかが、画面の数字を見るだけで分かります。down して up して、数が続いていれば「残った」、1に戻っていれば「消えた」。永続化の成否が、目で見えるアプリにしました。

作るファイルの全体像

最終的に、こういう形になります。この地図を、頭の隅に置いておいてください。

myapp/
├── docker-compose.yml     ← 2つのコンテナと、繋ぎ方・保存先をここに書く
├── .env                   ← パスワードなどの秘密(⚠️ Gitに入れない)
├── .env.example           ← 「こういう変数が要る」の見本(こちらはGitに入れてよい)
├── .gitignore
└── app/
    ├── Dockerfile         ← アプリのイメージの作り方
    ├── .dockerignore
    ├── package.json
    └── server.js          ← アプリ本体(数十行)

まず、VMの中に作業フォルダを用意します。

bash
$ mkdir -p ~/myapp/app
$ cd ~/myapp

確認: 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)が揃います。

bash
$ ls -a ~/myapp/app

.dockerignore . から始まるファイルも見たいので ls -a です。4つ見えれば次へ。

アプリだけ、先にビルドして確かめる

compose に進む前に、「アプリのイメージが、単体でちゃんとビルドできるか」だけを確かめておきます。 全部を一度に組んでから動かすと、失敗したときに「どこが悪いのか」が分かりません。 部品ごとに動作を確かめてから束ねると、切り分けが楽になります。

bash
$ docker build -t myapp-test ./app

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 の書き間違いです。ここが通れば、アプリのイメージは正しく作れています。この確認用イメージは、もう要らないので消しておきます。

bash
$ docker rmi myapp-test

単体でビルドが通ることを見ておくと、このあと 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 と db
  • app の 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サービスが書けた」ことだけ確認します。

bash
$ docker compose config

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 という名前が本当に引けるかを見ます。

bash
$ docker compose exec app sh

docker compose exec app sh は、「動いている app コンテナの中で、シェルを開く」コマンドです。プロンプトがコンテナの中のものに変わります。そこで、db という名前を引いてみます。

bash
$ getent hosts db

db に対してIPアドレスが1行返れば、名前解決ができています。 172で始まる、compose が割り当てた内部IPのはずです。これが、PGHOST=db だけで繋がっていた正体です。一方 getent hosts localhost を引くと、返るのは 127.0.0.1——つまり app 自身で、DBではありません。「localhost では繋がらない」が、ここで実物として見えます。確認したら exit でコンテナから出ます。

bash
$ 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 を作ったら(次の節)、この永続化を必ず自分の目で確かめます。ここを実演しないと、「たぶん残る」で終わってしまいます。

やることは、こういう流れです(⑥まで終えてから実行してください)。

bash
$ # 1. 立ち上げる
$ docker compose up -d

$ # 2. ブラウザ(またはcurl)で何回か開いて、数を増やす
$ curl http://localhost:3000
$ curl http://localhost:3000
$ curl http://localhost:3000

3回開けば「3回開かれました」と返るはずです。ここで、コンテナを止めて片づけます。

bash
$ # 3. コンテナを止めて消す(ボリュームは残す)
$ docker compose down

$ # 4. もう一度立ち上げる
$ docker compose up -d

$ # 5. また開く
$ curl http://localhost:3000

ここで「4回開かれました」と続けば、成功です。 コンテナは一度消えたのに、数が3から続いた——データはコンテナの外(ボリューム)に残っていた証拠です。

そして、消えることも確かめます。

bash
$ # 6. 今度はボリュームごと消す
$ docker compose down -v

$ # 7. 立ち上げて開く
$ docker compose up -d
$ curl http://localhost:3000

今度は「1回開かれました」に戻ります。 -v(--volumes)を付けると、名前付きボリュームまで消えます。down と down -v の違いが、この数字の差です。

ボリュームが「そこにある/消えた」は、コマンドでも見えます。

bash
$ docker volume ls

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しても数が続く.png curl を数回打って数を増やし → 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 して、次で状態を見ます。

bash
$ docker compose ps

db の STATUS 欄に (healthy) と出ていれば、ヘルスチェックが効いています。 そして app は、その (healthy) になるまで起動を待ってから立ち上がっています。

スクリーンショットを撮ってください: 02_ps_healthy.png docker 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コマンドを、今度こそ打ちます。

bash
$ cd ~/myapp
$ docker compose up -d

-d(detached)は「バックグラウンドで動かす」の意味です。付けないと、ログが画面に流れ続けて、ターミナルが戻ってきません。初回はアプリのイメージをビルドするので、少し時間がかかります。

繋がるか確かめます。

bash
$ curl http://localhost:3000

「このページは 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_ブラウザで確認.png Windows本体のブラウザから http://VMのIP:3000/ を開き、「このページは N 回開かれました」が表示された画面を撮ってください。1コマンドで立てたアプリが、外から見えていることが分かるように。

うまくいかないときは、ログを見る

一発で繋がらないことのほうが、むしろ普通です。 そのとき、あてずっぽうで直さないための道具が3つあります。

まず、いま何が立っているかを見ます。

bash
$ docker compose ps

app が Exited (1) になっていたら、アプリが起動に失敗して落ちています。 db が (health: starting) のままなら、まだ準備中です。「立っているか」「落ちているか」「準備中か」を、まずここで見分けます。

落ちているアプリの理由は、ログに出ています。

bash
$ docker compose logs app

エラーは、たいてい下(新しいほう)にあります。 ECONNREFUSED ならDBの待ち合わせ(⑤)、password authentication failed ならパスワードの不一致(⑥の .env)、getaddrinfo ENOTFOUND なら繋ぎ先の名前が違う(③の PGHOST)——エラーの言葉が、どの節に戻ればいいかを教えてくれます。

動いている様子を、流れるまま見たいときは -f を付けます。

bash
$ docker compose logs -f

-f(follow)は、ログが出続けるのを見張るモードです。別のターミナルで curl を打つと、アプリのログに処理が流れるのが見えます。止めるときは Ctrl+C(ログを止めるだけで、コンテナは止まりません)。

設定を変えたのに反映されないときは、作り直します。

bash
$ docker compose up -d --build

--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つは、こう確かめられます。

bash
$ # compose ファイルとDockerfileに、パスワードの値が直書きされていないか
$ grep -R "change-me" docker-compose.yml app/Dockerfile

何も出てこなければ正解です。 パスワードの値は .env にしか無く、ファイルには ${POSTGRES_PASSWORD} という「入れ物」しか書かれていない、という状態です。

1つでも通らなかったら、それがこのコースの「まだ手が届いていない場所」です。 そこだけ、対応する節(③〜⑥)や、リンクした深掘りの回に戻ればいい。この判定リストが、「Dockerを触った」を「1コマンドで環境を立てられる」に変えます。

いちばん効く確認 — 別のVM(または別フォルダ)で再現する

この作品の本当の完成条件は、「別の場所でも、同じ1コマンドで立つ」ことです。 「自分のこのVMでだけ動く」なら、compose を使う意味の半分を捨てています。

いちばん手軽な確認は、フォルダごとコピーして、別の場所で立て直すことです。

bash
$ # いま作った myapp を、まるごと別名でコピーする
$ cp -r ~/myapp ~/myapp-copy
$ cd ~/myapp-copy
$ docker compose up -d
$ curl http://localhost:3000

.env も一緒にコピーされるので、これはそのまま立ちます。 もし別のVMやGitHub経由で渡すなら、⑥で分けた .env は付いてきません(Gitに入れていないので)。そのときは、相手の環境で .env.example をコピーして .env を作り、値を埋めるところから始めます。

bash
$ # 渡された側がやること
$ cp .env.example .env
$ # .env をエディタで開き、パスワードなどを埋める
$ docker compose up -d

この「フォルダ+.envさえあれば、どこでも同じ形が立つ」——これが、①で「手でやると再現できない」と言ったことの答えです。 手順が docker-compose.yml という1枚の紙になったから、こうして配れるようになりました。

確認が終わったら、コピーは片づけます。

bash
$ cd ~/myapp-copy
$ docker compose down -v
$ cd ~
$ rm -rf ~/myapp-copy

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)で立てたので、放っておくとコンテナは動いたままです。確かめ終わったら、止めておきましょう。

bash
$ # コンテナを止めて消す(データは残したい場合)
$ docker compose down

down(-v なし)なら、溜めた数はボリュームに残ります。 次に up -d すれば、その続きから動きます。

この作品ごと、きれいさっぱり消したいときだけ、-v を付けます。

bash
$ # データ(ボリューム)ごと消す。初期状態に戻す
$ docker compose down -v

アプリのイメージも消したいときは、続けて確認できます。

bash
$ docker images        # myapp-app のようなイメージが残っている
$ docker rmi <イメージID>

フォルダ(~/myapp)自体は、残しておくことを勧めます。 docker-compose.yml があれば、いつでも docker compose up -d の1行で、また同じ環境が立ちます。 それが、この記事で作った本当の成果物です。

ディスクが減ってきたら

Docker を触っていると、使われなくなったイメージやボリュームが少しずつ溜まります。 いま何がどれだけ使っているかは、次で分かります。

bash
$ docker system df

Images Containers Local Volumes ごとに、使用量と「再利用できる(reclaimable)量」が出ます。 VMのディスクが減ってきたと感じたら、まずこれで現状を見ます。

どこからも使われていないものだけを、まとめて片づけたいときは、次を使います。

bash
$ docker system prune

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ヶ月なので、「試して壊す」用途なら契約期間と月額の差を見てから決めてください。

参考リンク


次に読む

この記事は 【第6段階】インフラとコンテナ の 5 / 25 本目です。

記事
← 前の記事Composeなら1コマンド — 複数コンテナをまとめる
→ 次の記事Kubernetesは「状態を宣言する」 — minikube入門

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

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

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

Docker コースの到達作品です。 アプリとDBを compose 1コマンドで丸ごと立ち上げます。

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

コメント

コメントする

目次