Docker+uvでAPIサーバー開発用コンテナを構築する
本記事を作成した背景
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は依存関係インストールのレイヤーを再実行せずに済むため、イメージのビルドを大幅に高速化できる。
参考文献
- 小笠原 種高. 『仕組みと使い方がわかる Docker&Kubernetesのきほんのきほん』 マイナビ出版, 2021.
https://www.amazon.co.jp/dp/4839972745
Discussion