VSCodeでDocker環境を構築する方法

VSCodeでDocker環境を構築すると、Node.jsやPython、PHP、データベースなどの開発環境をコンテナとして管理できるようになります。

PC本体へさまざまなソフトウェアを直接インストールする必要が少なくなり、プロジェクトごとに独立した環境を用意できるのが大きなメリットです。

また、Dockerfileやcompose.yamlなどをGitで共有すれば、チームメンバー間でもほぼ同じ開発環境を再現しやすくなります。

VSCodeでは、Dockerを管理する「Container Tools」や、Dockerコンテナそのものを開発環境として利用する「Dev Containers」といった拡張機能も利用できます。

ここでは、VSCodeでDocker環境を構築する基本的な方法から、Docker ComposeやDev Containersを利用する方法まで詳しく解説します。

VSCodeでDockerを利用する仕組み

VSCodeだけをインストールしても、Dockerコンテナを実行することはできません。

実際にDockerイメージを作成したり、コンテナを起動したりするのはDocker Engineです。

VSCodeは、Dockerを操作したり、コンテナ内部で開発したりするためのインターフェースとして利用します。

基本的な関係は次のようになります。

VSCode
  ↓
Container Tools / Dev Containers
  ↓
Docker CLI
  ↓
Docker Engine
  ↓
Dockerコンテナ

そのため、VSCodeでDockerを利用するときは、基本的に次のような順番で環境を準備します。

Dockerをインストール
↓
Dockerの動作確認
↓
VSCodeをインストール
↓
Container Toolsをインストール
↓
Dockerfileを作成
↓
Dockerイメージをビルド
↓
コンテナを起動
↓
必要に応じてDocker Composeを利用
↓
必要に応じてDev Containersを利用

Dockerをインストールする

Windowsの場合

Windowsでは、Docker Desktopを利用する方法が分かりやすいでしょう。

Docker Desktopには、Docker Engine、Docker CLI、Docker Composeなど、Dockerを利用するための主要機能が含まれています。

WindowsでLinuxコンテナを扱う場合は、WSL 2バックエンドを利用する構成が一般的です。

まず、PowerShellなどでWSLの状態を確認します。

wsl --version

WSLがインストールされていない場合は、管理者権限のPowerShellなどから次のコマンドを実行できます。

wsl --install

WSLを更新する場合は、次のコマンドを使用します。

wsl --update

その後、Docker Desktopをインストールして起動します。

なお、WindowsではWSL 2以外のバックエンドも利用できるため、必ずWSL 2でなければならないわけではありません。

一般的なWeb開発でLinuxコンテナを利用する場合は、WSL 2が有力な選択肢となります。

macOSの場合

macOSでもDocker Desktopを利用する方法が一般的です。

Docker Desktopをインストールすれば、Docker Engine、Docker CLI、Docker Composeなどをまとめて利用できます。

Intel MacとApple Silicon搭載Macでは配布されるDocker Desktopが異なる場合があるため、自分のMacに合ったものを選びます。

Linuxの場合

LinuxではDocker Engineを直接インストールする方法が一般的です。

Ubuntu、Debian、Fedoraなど、利用しているディストリビューションごとにインストール方法が異なります。

また、一般ユーザーからDockerを実行する場合は、ユーザー権限の設定が必要になることがあります。

Dockerが正常に動作するか確認する

Dockerをインストールしたら、VSCodeのターミナルなどから動作確認を行います。

まずDockerのバージョンを確認します。

docker --version

続いてDocker Composeを確認します。

docker compose version

現在は、基本的に次の形式を利用します。

docker compose

古い記事では、次のような形式が紹介されていることがあります。

docker-compose

現在はCompose V2のdocker composeを基本として覚えておくとよいでしょう。

さらに、Docker Engineまで正常に利用できるか確認します。

docker run hello-world

正常にメッセージが表示されれば、Docker環境の基本的な準備は完了です。

VSCodeにContainer Toolsをインストールする

VSCodeからDockerを扱いやすくするために、Microsoftの「Container Tools」をインストールします。

VSCodeの拡張機能画面を開きます。

WindowsやLinuxでは、次のショートカットを利用できます。

Ctrl + Shift + X

検索欄で、次の名前を検索します。

Container Tools

Microsoftが提供しているContainer Toolsをインストールします。

Container Toolsを利用すると、VSCode上からDockerのコンテナやイメージなどを確認・管理しやすくなります。

代表的には、次のようなDockerリソースを確認できます。

Containers
Images
Volumes
Networks
Registries

従来はMicrosoftの「Docker」拡張機能がよく使われていましたが、現在はContainer ToolsがDocker開発・管理機能の中心となっています。

Docker用のプロジェクトを作成する

ここからはNode.jsを例に、実際のDocker環境を作成します。

例えば、次のようなプロジェクト構成を作ります。

docker-sample/
├─ package.json
├─ package-lock.json
├─ server.js
├─ Dockerfile
└─ .dockerignore

VSCodeから、このフォルダを開きます。

Node.jsアプリケーションを作成する

package.jsonを作成する

まず、次のようなpackage.jsonを用意します。

{
  "name": "docker-sample",
  "version": "1.0.0",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^5.0.0"
  }
}

依存パッケージをインストールしてpackage-lock.jsonも作成しておくと、Dockerビルド時にnpm ciを利用できます。

server.jsを作成する

続いて、簡単なWebサーバーを作成します。

const express = require("express");

const app = express();

app.get("/", (req, res) => {
  res.send("Hello Docker!");
});

app.listen(3000, "0.0.0.0", () => {
  console.log("Server running on port 3000");
});

ここでは明示的に0.0.0.0へバインドしています。

コンテナ内のWebサーバーへホスト側からアクセスする場合、このように外部インターフェースから受け付けられる状態にしておくと分かりやすくなります。

Dockerfileを作成する

プロジェクト直下に、次の名前でファイルを作成します。

Dockerfile

拡張子は付けません。

例えば、次のように記述します。

FROM node:22-alpine

WORKDIR /app

COPY package.json package-lock.json ./

RUN npm ci

COPY . .

EXPOSE 3000

CMD ["npm", "start"]

FROMの意味

FROM node:22-alpine

Dockerイメージのベースとなる環境を指定します。

この例では、Node.js 22を利用できるAlpine Linuxベースのイメージを使用しています。

Alpine Linuxは軽量ですが、Dev Containers用の開発環境として利用する場合は、一部のVSCode拡張機能やネイティブライブラリとの互換性に注意が必要です。

WORKDIRの意味

WORKDIR /app

コンテナ内部で作業するディレクトリを指定します。

これ以降の命令は、基本的に/appを基準として実行されます。

COPYの意味

COPY package.json package-lock.json ./

ホスト側のファイルをDockerイメージ内へコピーします。

依存関係を記述したファイルを先にコピーすることで、Dockerのビルドキャッシュを効率的に利用しやすくなります。

RUNの意味

RUN npm ci

Dockerイメージをビルドするときにコマンドを実行します。

package-lock.jsonが存在するNode.jsプロジェクトでは、npm installよりnpm ciを利用すると、依存パッケージのバージョンを再現しやすくなります。

EXPOSEの意味

EXPOSE 3000

アプリケーションが3000番ポートを利用することを示します。

ただし、EXPOSE 3000を書くだけでは、ホストPCへ3000番ポートが公開されるわけではありません。

ホスト側へ公開するには、docker runの-pオプションやDocker Composeのportsを利用します。

CMDの意味

CMD ["npm", "start"]

コンテナを起動したときに実行するコマンドです。

この例では、npm startを実行します。

.dockerignoreを作成する

Dockerイメージへ不要なファイルを含めないため、.dockerignoreを作成します。

例えば、次のように記述します。

node_modules
npm-debug.log*
.git
.gitignore
.env
.env.*

特にnode_modulesを除外しておくことは重要です。

WindowsやmacOS上で作成されたnode_modulesをLinuxコンテナへコピーすると、OS依存のモジュールで問題が発生することがあります。

また、.envにはAPIキーやパスワードなどが含まれることがあるため、必要がなければDockerビルドコンテキストへ送らない方が安全です。

Dockerイメージをビルドする

Dockerfileを作成したら、VSCodeのターミナルで次のコマンドを実行します。

docker build -t docker-sample .

docker buildはDockerイメージを作成するコマンドです。

-t docker-sample

では、作成するDockerイメージへdocker-sampleという名前を付けています。

最後の、

.

は、現在のディレクトリをビルドコンテキストとして利用するという意味です。

ビルドしたイメージは、次のコマンドで確認できます。

docker image ls

または、次のコマンドも利用できます。

docker images

Dockerコンテナを起動する

作成したDockerイメージからコンテナを起動します。

docker run -d -p 3000:3000 --name docker-sample-container docker-sample

-dオプション

-d

コンテナをバックグラウンドで実行します。

-pオプション

-p 3000:3000

ホストPCの3000番ポートと、コンテナの3000番ポートを接続します。

基本的には、

ホスト側:コンテナ側

という順番です。

–nameオプション

--name docker-sample-container

コンテナへ分かりやすい名前を付けています。

起動後、ブラウザから次のURLへアクセスします。

http://localhost:3000

「Hello Docker!」と表示されれば、Docker環境でNode.jsアプリケーションが正常に動作しています。

Dockerコンテナの状態を確認する

起動中のコンテナを確認する

次のコマンドを使用します。

docker ps

停止済みコンテナも確認する

すべてのコンテナを確認したい場合は、次のようにします。

docker ps -a

Dockerコンテナのログを確認する

Docker環境でエラーが発生した場合は、ログの確認が重要です。

docker logs docker-sample-container

ログをリアルタイムで追跡する場合は、次のようにします。

docker logs -f docker-sample-container

-fを指定すると、新しいログが継続的に表示されます。

Dockerコンテナ内部へ入る

実行中のコンテナ内部でコマンドを実行したい場合は、docker execを使用します。

Alpine Linux系のコンテナであれば、次のようにします。

docker exec -it docker-sample-container sh

Ubuntuなど、bashがインストールされているコンテナでは、次のコマンドを利用できる場合があります。

docker exec -it docker-sample-container bash

コンテナ内へ入った後、例えば次のコマンドを実行できます。

node --version

ホストPCではなく、コンテナ内部にインストールされているNode.jsのバージョンが表示されます。

Dockerコンテナを停止・削除する

コンテナを停止する

docker stop docker-sample-container

コンテナを再起動する

docker start docker-sample-container

コンテナを削除する

停止済みコンテナを削除する場合は、次のようにします。

docker rm docker-sample-container

Dockerイメージを削除する

コンテナを削除した後、Dockerイメージも削除したい場合は、次のコマンドを利用します。

docker image rm docker-sample

そのイメージを使用しているコンテナが残っていると、イメージを削除できない場合があります。

そのため、基本的には、

コンテナ停止
↓
コンテナ削除
↓
イメージ削除

という順番で操作すると分かりやすいでしょう。

VSCodeからDockerfileを作成する

Container Toolsを利用すると、Docker関連ファイルをVSCodeから生成することもできます。

まずコマンドパレットを開きます。

Ctrl + Shift + P

続いて、次のようなコマンドを実行します。

Containers: Add Docker Files to Workspace

プロジェクトの言語や構成を選択すると、Dockerfileや.dockerignoreなどを自動生成できます。

Dockerfileの書き方に慣れていない場合は、この機能を利用してひな形を作成すると便利です。

Docker Composeを利用する

Web開発では、アプリケーションだけでなく、データベースやキャッシュなど複数のサービスを利用することがあります。

例えば、次のような構成です。

Node.js
+
PostgreSQL
+
Redis

このような複数のコンテナをまとめて管理するときに便利なのがDocker Composeです。

ただし、Docker Composeは複数コンテナ専用というわけではありません。

単一コンテナでも、ポート、環境変数、ボリュームなどの実行設定をファイルとして管理したい場合に利用できます。

compose.yamlを作成する

Node.jsアプリケーションだけであれば、次のようなcompose.yamlを作成できます。

services:
  app:
    build: .
    ports:
      - "3000:3000"

起動するときは、次のコマンドを実行します。

docker compose up

バックグラウンドで起動する場合は、次のようにします。

docker compose up -d

Dockerイメージを再ビルドしてから起動したい場合は、次のコマンドが便利です。

docker compose up -d --build

Docker ComposeでPostgreSQLを利用する

Node.jsとPostgreSQLを組み合わせる場合は、例えば次のように記述できます。

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: app
      DB_PASSWORD: ${DB_PASSWORD}
      DB_NAME: appdb
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: appdb
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
      interval: 5s
      timeout: 5s
      retries: 5
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

コンテナ間ではサービス名で通信する

この例では、Node.js側からPostgreSQLへ接続するときのホスト名は、

localhost

ではありません。

次のように、Composeのサービス名を利用します。

db

つまり、アプリケーションからPostgreSQLへ接続するときは、

db:5432

という考え方になります。

同じComposeプロジェクト内のサービスは、通常はサービス名を利用して通信できます。

depends_onだけではDBの準備完了まで待たない

Docker Composeでは、次のような単純な指定も可能です。

depends_on:
  - db

ただし、この書き方では「dbコンテナが起動したこと」は確認できますが、PostgreSQLが実際に接続可能な状態になるまで待つとは限りません。

そのため、アプリケーション起動時に確実にデータベースへ接続したい場合は、healthcheckとcondition: service_healthyを組み合わせる方法があります。

Docker Composeを停止する

Compose環境を停止・削除する場合は、次のコマンドを利用します。

docker compose down

単純に停止だけしたい場合は、次のコマンドです。

docker compose stop

再び開始する場合は、次のようにします。

docker compose start

名前付きボリュームは通常削除されない

docker compose down

を実行しても、通常は名前付きボリュームまでは削除されません。

例えばPostgreSQLのデータを、

volumes:
  - postgres-data:/var/lib/postgresql/data

として保存している場合、通常のdocker compose downでデータが保持されます。

ボリュームも削除したい場合は、次のようにします。

docker compose down -v

ただし、このコマンドを実行するとデータベースの保存データまで削除される可能性があります。

実行前に、本当に削除して問題ないか確認しましょう。

Docker Composeのログを確認する

Compose環境全体のログを見る場合は、次のコマンドを利用します。

docker compose logs

リアルタイムでログを確認する場合は、次のようにします。

docker compose logs -f

特定サービスだけ確認したい場合は、例えば次のように指定できます。

docker compose logs -f app

Dev Containersを利用する

VSCodeでDockerを利用するときに便利なのが「Dev Containers」です。

Container ToolsとDev Containersは似ていますが、役割が異なります。

Container Tools
→ Dockerコンテナやイメージを管理する

Dev Containers
→ DockerコンテナそのものをVSCodeの開発環境として利用する

Dev Containersを利用すると、Node.jsやPythonなどの実行環境だけでなく、開発ツールやVSCode拡張機能までプロジェクト単位でそろえやすくなります。

Dev Containers拡張機能をインストールする

VSCodeの拡張機能画面を開いて、

Dev Containers

と検索します。

MicrosoftのDev Containers拡張機能をインストールします。

devcontainer.jsonを作成する

Dev Containersでは、主に次のファイルを利用します。

.devcontainer/devcontainer.json

例えば、次のような構成にできます。

docker-sample/
├─ .devcontainer/
│  └─ devcontainer.json
├─ Dockerfile
├─ package.json
└─ server.js

devcontainer.jsonは、例えば次のように記述できます。

{
  "name": "Node Docker Development",
  "build": {
    "dockerfile": "../Dockerfile"
  },
  "forwardPorts": [3000]
}

VSCode拡張機能も自動的にインストールしたい場合は、次のような設定が可能です。

{
  "name": "Node Docker Development",
  "build": {
    "dockerfile": "../Dockerfile"
  },
  "forwardPorts": [3000],
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint"
      ]
    }
  }
}

参考サイト

Dev Containersとは？Dockerを使った開発環境構築の決定版【図解で完全理解】

コンテナ内部でVSCodeを開く

devcontainer.jsonを作成したら、VSCodeのコマンドパレットを開きます。

Ctrl + Shift + P

続いて、次のコマンドを実行します。

Dev Containers: Reopen in Container

VSCodeが再読み込みされ、Dockerコンテナを開発環境として利用できるようになります。

例えばターミナルで、

node --version

を実行すると、ホストPCではなく、コンテナ内部のNode.jsが利用されます。

本番用DockerfileとDev Containers用Dockerfileを分ける方法

本番環境と開発環境では、必要なツールが異なることがあります。

本番環境では不要でも、開発環境では次のようなツールが必要になる場合があります。

Git
curl
デバッガー
リンター
シェル
VSCode拡張機能用ライブラリ

そのため、プロジェクトによっては次のようにDockerfileを分ける方法もあります。

project/
├─ .devcontainer/
│  ├─ devcontainer.json
│  └─ Dockerfile
├─ Dockerfile
└─ ...

例えば、

ルートのDockerfile
→ 本番環境・アプリ実行用

.devcontainer/Dockerfile
→ VSCode開発環境用

という役割分担です。

本番用イメージを軽量に保ちながら、開発環境では必要なツールを充実させることができます。

Dockerfile・Docker Compose・Dev Containersの違い

Docker関連のファイルは役割が似て見えるため、最初は混乱しやすい部分です。

整理すると次のようになります。

ファイル	主な役割
Dockerfile	Dockerイメージの作り方を定義する
compose.yaml	コンテナの起動設定や複数サービスを管理する
devcontainer.json	VSCodeの開発環境としてコンテナを利用する設定
.dockerignore	Dockerビルドへ不要なファイルを除外する

例えば、次のように組み合わせて利用できます。

VSCode
↓
Dev Containers
↓
devcontainer.json
↓
Docker Compose
↓
appコンテナ + dbコンテナ
↓
Dockerfile

すべてを必ず利用する必要はありません。

小規模なプロジェクトならDockerfileだけでも構築できますし、複数サービスが必要になればDocker Composeを追加します。

開発環境そのものをコンテナ化したければ、さらにDev Containersを追加するとよいでしょう。

VSCodeでDockerを使うときによく利用するコマンド

Dockerのバージョンを確認する

docker --version

起動中のコンテナを確認する

docker ps

すべてのコンテナを確認する

docker ps -a

Dockerイメージを確認する

docker image ls

Dockerイメージをビルドする

docker build -t my-app .

Dockerコンテナを起動する

docker run -d -p 3000:3000 my-app

Dockerコンテナのログを確認する

docker logs -f コンテナ名

Dockerコンテナ内部でシェルを開く

docker exec -it コンテナ名 sh

Dockerコンテナを停止する

docker stop コンテナ名

Dockerコンテナを削除する

docker rm コンテナ名

Docker Composeを起動する

docker compose up -d

Docker Composeを再ビルドして起動する

docker compose up -d --build

Docker Composeを終了する

docker compose down

Dockerが動かない場合の確認ポイント

Docker Desktopが起動しているか確認する

次のようなエラーが表示される場合があります。

Cannot connect to the Docker daemon

この場合は、Docker Engineが起動していない可能性があります。

WindowsやmacOSでは、まずDocker Desktopが正常に起動しているか確認しましょう。

WindowsではWSLの状態を確認する

WindowsでWSL 2バックエンドを利用している場合は、次のコマンドで状態を確認できます。

wsl --version

または、

wsl --status

WSL自体に問題があると、Docker Desktopが正常に起動しないことがあります。

ポートの競合を確認する

例えば、

docker run -p 3000:3000 ...

を実行したときにエラーが出る場合、ホストPCの3000番ポートを別のアプリケーションが使用している可能性があります。

その場合は、ホスト側のポート番号を変更します。

docker run -p 3001:3000 ...

これは、

ホストPC:3001
↓
コンテナ:3000

という意味です。

ブラウザからは次のURLへアクセスします。

http://localhost:3001

Dockerfileを変更したのに反映されない場合

Dockerfileを変更しても、以前のDockerイメージをそのまま利用している場合があります。

Docker Composeなら、次のコマンドで再ビルドできます。

docker compose up -d --build

Dockerのビルドキャッシュを利用せず、完全に最初からビルドしたい場合は、次の方法もあります。

docker build --no-cache -t docker-sample .

ただし、通常は毎回--no-cacheを使用する必要はありません。

キャッシュが原因と思われる問題を切り分ける場合などに利用します。

Docker環境でパスワードを扱うときの注意点

Docker Composeのサンプルでは、分かりやすさを優先してパスワードを直接書くことがあります。

しかし、実際のプロジェクトでは、次のようにパスワードを直接記述するのは避けた方がよいでしょう。

DB_PASSWORD: password

例えば、

DB_PASSWORD: ${DB_PASSWORD}

として、環境変数から値を渡す方法があります。

ただし、.envファイルにパスワードを書けば無条件に安全になるわけではありません。

.envをGitへコミットしないようにし、必要に応じてクラウドサービスのシークレット管理機能やDocker Secretsなどを利用することも検討します。

VSCodeでDocker環境を構築するメリット

Dockerを利用する最大のメリットの一つは、開発環境をコードとして管理しやすくなることです。

Dockerを使わない場合、開発者ごとに次のような違いが生じることがあります。

Aさん
Node.js 20

Bさん
Node.js 22

Cさん
Node.js 24

Dockerfileで、

FROM node:22-alpine

のように指定しておけば、プロジェクトで利用するNode.js環境を統一しやすくなります。

さらに、Dockerfile、compose.yaml、devcontainer.jsonなどをGitで管理すれば、新しいメンバーも同じ開発環境を構築しやすくなります。

初心者がDockerを学ぶおすすめの順番

Docker初心者の場合、最初からDocker ComposeやDev Containersまで一度に導入すると、それぞれの役割が分かりにくくなることがあります。

そのため、次のような順番で覚えると理解しやすいでしょう。

Docker Desktop
↓
docker run
↓
Dockerfile
↓
docker build
↓
docker run -p
↓
Docker Compose
↓
Container Tools
↓
Dev Containers

最初はDocker CLIで基本操作を理解し、その後VSCodeのGUI機能やDev Containersを利用すると、

Docker自体の機能
VSCodeの機能

を区別しやすくなります。

VSCodeでDocker環境を構築するときのおすすめ構成

Web開発でDockerを本格的に利用する場合は、例えば次のような構成にできます。

project/
├─ .devcontainer/
│  ├─ devcontainer.json
│  └─ Dockerfile
├─ src/
├─ Dockerfile
├─ compose.yaml
├─ .dockerignore
├─ package.json
├─ package-lock.json
└─ README.md

それぞれの役割は次の通りです。

Dockerfile
→ アプリケーション用Dockerイメージを作成

compose.yaml
→ アプリやDBなどのコンテナを管理

.devcontainer/devcontainer.json
→ VSCodeの開発環境を設定

.devcontainer/Dockerfile
→ Dev Containers専用の開発環境を構築

.dockerignore
→ Dockerビルドへ不要なファイルを除外

小規模なプロジェクトでは、最初からすべてを用意する必要はありません。

まずは、

Docker Desktop
+
Dockerfile
+
Container Tools

程度から始めても十分です。

データベースなど複数のサービスを利用するようになったらDocker Composeを導入し、チーム全体で開発環境まで完全に統一したくなった場合にDev Containersを加えるとよいでしょう。

VSCodeとDockerを組み合わせれば、開発環境を再現しやすくなり、プロジェクトごとの依存関係やバージョン違いによるトラブルも減らしやすくなります。

まずはDockerfileを使った単一コンテナの起動方法を理解し、その後Docker Compose、Dev Containersへ段階的に進むのがおすすめです。

以上、VSCodeでDocker環境を構築する方法についてでした。

最後までお読みいただき、ありがとうございました。