🤷

Docker+uvでAPIサーバー開発用コンテナを構築する

に公開
2025/12/08

本記事を作成した背景

FastAPI + Uvicorn でAPIサーバを構築し、Cloud RunやAWS ECS等にデプロイするためのDockerfileを作成する方法を整理したいと思い、本記事を作成しました。

本記事で取り組んだこと

  • FastAPI + Uvicorn でAPIサーバを構築するためのDockerfileを作成しました。
  • パッケージ管理にはuvを使用して、ライブラリの依存関係のチェック・競合解決・インストールを高速化しました。

手順

前提

  • 環境: Windows 11 + WSL2 (Ubuntu 24.04)
  • 前提知識: イメージやコンテナなど、Dockerの概念について聞いたことがある
  • 前提状態: uvでvenv構築してAPI用コードの実装がひと段落した状態。pyproject.tomlとuv.lockがある

※ DockerはWSL2上にDocker Engineのみインストール済(Windows PC に Docker Desktop はインストールしていない)

手順1: FastAPIプロジェクトの構成は以下の通り

app配下にAPIのソースコードを集約済とする。

また、開発時のパッケージ管理・仮想環境にはuvを使用し、pyproject.tomlとuv.lockは既に作成・生成済とする。

/home/ユーザー名/projects/
└──  backend-study_fastapi-test/
    ├── .venv
    ├── app
    │   └── main.py                # ソースコード
    ├── .dockerignore
    ├── Dockerfile
    ├── docker-compose.dev.yml
    ├── docker-compose.yml
    ├── pyproject.toml             # 開発段階で作成済
    └── uv.lock                    # 開発段階で生成済

手順2: Dockerfile の作成

Dockerfileでは、本番環境用の動作(固定的・リアルタイム反映無し)を指定する。

  • コードはVOLUMEではなくCOPYでビルド時のものを固定化してコンテナに入れる
  • APIサーバー起動コマンドには--reloadを入れないことで、ビルド後コードが変更されても再起動が起こらない

🛠️ 具体例

# 1. Python & uv がセットになっている公式イメージ
FROM ghcr.io/astral-sh/uv:python3.12-bookworm

# 2. コンテナ上の作業ディレクトリ
WORKDIR /code

# 3. まずは依存情報だけコピー(キャッシュを効かせるため)
COPY pyproject.toml uv.lock ./

# 4. ロックファイルに基づいて依存インストール
#   --frozen : uv.lock をそのまま信じる(更新しない)
#   --no-dev: dev依存を除いて本番用のみにする(開発なら付けなくてもOK)
RUN uv sync --frozen --no-dev

# 5. アプリ本体をコピー
COPY . .

# 6. FastAPI 起動コマンド
CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

📝 補足

ライブラリインストールはuv syncで行う(pipは使わない。uvネイティブ)

手順3: .dockerignore ファイルを作成する

.dockerignore ファイルを作成してDockerfileと同じ階層に置くことで、ホストの.venvや.gitがコンテナに送られなくなるため、ビルド(イメージ生成)を高速化できる。

※余計なファイルがコンテナに乗らないのでスッキリする

🛠️ 具体例

.git
.venv
__pycache__
.env
*.log

手順4: docker-compose.dev.yml ファイルを作成する

開発用に、以下2点を追加する。

  • ホストPCとコンテナでの共有フォルダ設定(volumes: - .:/code)= コード変更のリアルタイム反映(to コンテナ)
  • コード変更を自動検出してサーバを再起動する設定(--reload)= コード変更のサーバへのリアルタイム反映
version: "3.9"

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    # ホスト側のコードをコンテナにマウント
    volumes:
      - .:/code
    working_dir: /code
    ports:
      - "8000:8000"
    # 開発用:--reload 付きで起動
    command: >
      uv run uvicorn app.main:app
      --host 0.0.0.0
      --port 8000
      --reload
    environment:
      # 必要なら FastAPI 側で読む用
      - ENV=development

手順5: docker-compose.yml ファイルを作成する

手順6: DockerfileからDockerイメージを作成する

docker compose buildで、DockerfileからDockerイメージを作成する。

※docker compose up --buildで、イメージ生成後コンテナ立ち上げまで一気通貫にできる。

🛠️ 手順詳細

-f (ファイル名)オプションでcompose.ymlファイルを指定して起動できる。

docker compose -f docker-compose.dev.yml build
  • 出来上がったイメージ名は、自動でディレクトリ名_サービス名:latestとなる。今回の場合、ディレクトリ名はbackend-study_fastapi-test、サービス名はapi(Dockerfile に記載されている)なので、backend-study_fastapi-test_apiとなる

  • イメージ名はdocker image lsで確認できる(上記確認してみたらbackend-study_fastapi-test-apiと出た。区切り文字が「_」ではなく「-」となっている。なぜかは分からない)

手順7: Dockerイメージからコンテナを作成し、起動する

docker compose upで、DockerfileからDockerイメージを作成する。

docker compose -f docker-compose.dev.yml up
  • docker compose up --buildでビルドからコンテナ起動までやれてはしまうが、ビルドエラーにならないかチェックするためにも事前にdocker compose buildでビルドできるかチェックだけしておいている。
  • docker compose upで、Dockerイメージが無い場合はイメージの作成からしてくれるが、Dockerイメージがある場合はそのままそれを使ってコンテナを起動してくれる。Dockerイメージがあっても再度生成したい場合は--buildオプションを付ける。

手順8: FastAPI サーバにアクセスする

ブラウザでhttp://localhost:8000/docsにアクセスする。

Swagger UIで自動生成したAPIドキュメントが表示される。

APIの動作確認を画面上で行うことができる。

手順9: コンテナを停止する

docker compose upをフォアグラウンドで動かしているので、Ctrl + Cを押すことで、SIGINT を送りコンテナを停止させることができる。

Ctrl + Cの操作はdocker compose stopに相当する。この操作・コマンドでは、コンテナを停止させるだけで、削除はしない。

コンテナを削除したい場合は、停止後docker compose downコマンドを実行する。

また、docker compose down --volumesとすることで、DBデータ等のボリュームも含めて完全削除できる。

手順10: 停止したコンテナを再度動かす

Dockerfileやライブラリ(pyproject.toml,uv.lock)に変更がある場合:
Dockerfile があるディレクトリに移動してから、docker compose up --buildを実行する。

Dockerfileやライブラリの変更が無い場合(アプリコードの変更のみの場合):
Dockerfile があるディレクトリに移動してから、docker compose upを実行する。

まとめ

コマンド 説明
docker compose build Dockerイメージを生成
docker compose up --build Dockerイメージを生成し、コンテナ立上
docker compose up Dockerイメージからコンテナを立上
docker compose stop(Ctrl+C) コンテナを停止
docker compose down コンテナを削除

学び・次に活かせる知見

  • Dockerfileが1ファイルだとしても、コード更新・サーバ再起動等の動的な挙動はcompose.dev.ymlに分けて書いた方が良い(本番時の予期せぬ挙動を防ぐため)

  • .gitや.venvは.dockerignoreに記載することで、コンテナに不要なファイルを送らなくなるため、ビルドを高速化できる。

  • パッケージ管理ファイル(pyproject.tomlとuv.lock)をアプリコードより先にコンテナへコピーしておくことで、これらのファイルに変更がない場合、依存パッケージのインストール処理を前回ビルド時のキャッシュから再利用できる。

    → その結果、Dockerは依存関係インストールのレイヤーを再実行せずに済むため、イメージのビルドを大幅に高速化できる。

参考文献

Discussion