⑥docker_beginner-pitfalls_concepts

うさうさ研修工房 初心者がつまずくポイント 全力サポート＆概念理解編 「なぜエラーが起きるか」を、概念から腹落ちさせる回 2026年7月時点の公式ドキュメントにもとづく解説 うさうさ先生

Chapter 1 なぜ「概念」から理解すると 躓かなくなるのか エラーメッセージを丸暗記で乗り切ろうとすると、少し違う場面でまた同じとこ ろで詰まります。「イメージとコンテナの関係」「レイヤー」「ライフサイクル」とい う3つの概念さえ押さえておけば、エラーの意味が自分で読めるようになりま す。 この章の進め方 前半＝概念の再確認、後半＝つまずきポイントを1つずつ「原因→対処」の形で解 消します。 うさうさ研修工房 | 初心者サポート＆概念理解編 2

概念 1 / 3 イメージは「設計図」 コンテナは「実体」 イメージは変更できない読み取り専用の設計図です。docker runするたびに、そ の設計図の上に「書き込み可能な層」を1枚重ねたものがコンテナになります。だ からこそ、同じイメージから何個でもコンテナを作れます。 つまずきの正体 「コンテナの中でファイルを直接編集したのに、次に docker runしたら消えていた」 → コンテナを削除すると書き込み層ごと消えるのが正常な挙動です。 うさうさ研修工房 | 初心者サポート＆概念理解編 3

概念 2 / 3 イメージは薄い層の 積み重ね（レイヤー） Dockerfileの1行1行が、それぞれ1枚のレイヤーになります。ビルド時、変更のな い行から順にキャッシュが再利用されるため、変更が少ない命令ほど上（前）に書 くとビルドが速くなります。 COPY package.json . RUN npm install COPY . . # ソースだけ後にコピー うさうさ研修工房 | 初心者サポート＆概念理解編 4

概念 3 / 3 コンテナには 「今どの状態か」がある コンテナは作成・実行中・停止・削除という状態を行き来します。「動いていない」と 思っても、実は停止中で残っている場合があり、それがポート競合や名前重複エ ラーの原因になります。 作成 (create) → 実行中 (running) → 停止 (stopped) → 削除 (removed) docker ps -a で「停止中も含めた全コンテナ」を確認できます。docker rmで削除、docker startで再 開できます。 うさうさ研修工房 | 初心者サポート＆概念理解編 5

あるある つまずき 1 ブラウザで開けない： ポート番号の向きを逆にしがち 原因 -p の書式は「ホスト側 :コンテナ側」です。左右を逆にすると、意図しないポートで 待ち受けてしまいます。 対処 コンテナ内でアプリが実際に待ち受けているポート（コンテナ側）を確認し、 -p ホス ト:コンテナ の順で指定します。 docker run -p 8080:80 nginx うさうさ研修工房 | 初心者サポート＆概念理解編 # ホスト8080 → コンテナ 80 6

あるある つまずき 2 せっかく入れたデータが 消えた！ 原因 コンテナ内のデータは、コンテナを削除すると一緒に消えます（概念①の書き込み 層の話です）。 対処 残したいデータは volumesやbind mountでコンテナの外に置きます。 DBなどの永 続データはnamed volumeが基本です。 docker run -v db_data:/var/lib/mysql mysql うさうさ研修工房 | 初心者サポート＆概念理解編 7

あるある つまずき 3 localhostを指定しても DBに繋がらない 原因 コンテナから見た localhostは「自分自身」を指します。別コンテナの DBはそこには いません。 対処 Composeで起動したサービス同士は、サービス名がそのままホスト名として使えま す。接続先は localhostではなくサービス名にします。 DATABASE_URL=postgresql://user:pass@db:5432/app 名 うさうさ研修工房 | 初心者サポート＆概念理解編 # 「db」はサービス 8

あるある つまずき 4 コードを直したのに ビルドに反映されない 原因 概念②のレイヤーキャッシュが働き、古い COPY結果が再利用されている場合があ ります。 対処 まずは通常の再ビルドで直るか確認し、直らない場合のみキャッシュを使わない 再ビルドを試します。 docker build --no-cache -t myapp . うさうさ研修工房 | 初心者サポート＆概念理解編 9

あるある つまずき 5 Permission deniedが 出る 原因 多くのベースイメージは root権限で動作するため、コンテナが作成したファイルの 所有者がホスト側のユーザーと一致しないことがあります。 対処 Dockerfileの USER 命令で実行ユーザーを指定するか、公式ドキュメントのセキュリ ティ関連ページで案内される権限設定を確認します。 うさうさ研修工房 | 初心者サポート＆概念理解編 10

あるある つまずき 6 気づいたらディスク容量が カツカツ 原因 止めただけのコンテナや、使わなくなったイメージ・ボリュームは自動では消えま せん。 対処 不要なリソースの掃除を定期的な習慣にします。掃除前に何が消えるか確認した い場合は各コマンドの --dry-runオプションが使えます。 docker system prune うさうさ研修工房 | 初心者サポート＆概念理解編 11

Chapter 2 困ったときの型： ログ→exec→再現 何が起きているか分からないときほど、闇雲に触らず手順を決めておくと落ち着 いて対処できます。 1 docker logs <コンテナ名> まずログでエラーメッセージそのものを確認する 2 docker exec -it <コンテナ名> sh コンテナの中に入り、実際のファイルや環境変数を確認する 3 docker ps -a / docker inspect 状態や設定（ポート・マウント等）を客観的に確認する うさうさ研修工房 | 初心者サポート＆概念理解編 12

Closing まとめ：エラーは 「概念のどこ」を指しているか イメージ＝設計図／コンテナ＝実体、削除すれば書き込み層は消える レイヤーとキャッシュを意識するとビルドも反映も予測できる ポート・接続先・権限のエラーは「向き」と「範囲」の勘違いが多い 困ったら logs → exec → inspect の順で事実を集める うさうさ研修工房 / うさうさ先生