Posted inDocker

PoetryでPythonをDocker化：依存関係管理とビルド速度の最適解

Docker tutorial - IT technology blog
Docker tutorial - IT technology blog

従来の手法における「依存関係地獄（Dependency Hell）」の悪夢

ローカルでは完璧に動作するのに、Dockerにデプロイした途端にライブラリ不足やバージョン違いでエラー growth 多発する……そんな光景に心当たりはありませんか？ 多くの開発者は依然として pip freeze > requirements.txt を使っていますが、これはあくまで「応急処置」に過ぎません。それは、どの部品がどこに対応するのか分からないまま、大量のパーツを箱に詰め込むようなものです。

requirements.txt の最大の欠点は、メインライブラリとサブ依存関係（sub-dependencies）の境界が曖昧なことです。ある日突然、サブライブラリがアップデートされてシステム全体が壊れることもあります。その「裏切り者」がどこにいるのかを特定するだけで、午後の時間を丸ごと潰してしまうこともあるでしょう。そこで登場するのが Poetry です。

依存関係管理手法の比較

1. Requirements.txt：「古き良き」が、リスクも多い

使いやすい反面、一貫性に欠けます。バージョンの競合をスマートに解決できません。実際、Dockerfileを最適化していないと、コードを1行修正するたびにDockerが数GBものライブラリを再ダウンロードすることになり、リソースと時間の大きな無駄遣いになります。

2. Conda または Pipenv：決定打に欠ける

Condaはシンプルなマイクロサービスには肥大化しすぎていることが多いです。Pipenvに関しては、依存関係の解決（resolve）やロックファイルの生成が非常に遅く、ストレスを感じる場面が多々あります。

3. Poetry：プロの開発者が選ぶ最適解

Poetryは poetry.lock ファイルを通じてバージョンを厳密に固定します。これにより、ローカル、ステージング、本番環境まで、100%同一の環境を保証します。依存関係をグループ化（テスト用と本番用を分離するなど）できるため、イメージを大幅に軽量化することが可能です。

導入のメリットと注意点

なぜ使うべきなのか？

  • ビルドの確実性：ロックファイルにより、バージョンの不一致が完全に解消されます。
  • クリーン：最終イメージから重いビルドツールを排除し、セキュリティを向上させます。
  • スピード：Docker Layer Cachingのパワーを最大限に引き出します。

注意点：

  • 初期ビルド時にPoetryをインストールするため、30〜45秒ほど追加の時間がかかります。
  • キャッシュを最適化するために、Dockerfileを少し工夫して書く必要があります。

実プロジェクトからの教訓

あるECサイトのマイクロサービス群をデプロイした時のことを今でも覚えています。当初のイメージは gcc や python-dev などの「ゴミ」が詰まっており、サイズは900MB近くありました。その結果、サーバーでメモリリークが頻発しました。Poetryとマルチステージビルドに移行したところ、イメージサイズは120MBまで縮小。デプロイ速度は4倍になり、何よりライブラリ関連のエラーが完全に消失しました。

Poetryによる完璧なDocker化の実装

ここでは、マルチステージビルド（Multi-stage build）という手法を使います。簡単に言うと、「調理（インストール）」のためのステージと、「配膳（実行）」のみを行うステージを分ける方法です。

ステップ1：pyproject.toml の設定

基本的な FastAPI プロジェクトの例：

[tool.poetry]
name = "itfromzero-app"
version = "0.1.0"

[tool.poetry.dependencies]
python = "^3.10"
fastapi = "^0.100.0"
uvicorn = "^0.22.0"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

ステップ2：Layer Cachingを最適化したDockerfile

ポイントは順序にあります。まず設定ファイルをコピーし、その後にコードをコピーします。これにより、Dockerはライブラリのインストールレイヤーをキャッシュします。pyproject.toml を変更した時だけ再インストールが行われ、コードのロジックを修正しただけであれば、このステップは完全にスキップされます。ビルド速度は驚くほど速くなります。

# ステージ1: ビルダー（インストールフェーズ）
FROM python:3.10-slim as builder

ENV POETRY_NO_INTERACTION=1 \
    POETRY_VIRTUALENVS_IN_PROJECT=true \
    POETRY_HOME="/opt/poetry"

ENV PATH="$POETRY_HOME/bin:$PATH"

RUN apt-get update && apt-get install -y curl && \
    curl -sSL https://install.python-poetry.org | python3 - 

WORKDIR /app
# キャッシュを活用するために、先にロックファイルをコピーする
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root --only main

# ステージ2: ランタイム（実行フェーズ - 非常に軽量）
FROM python:3.10-slim as runtime

WORKDIR /app
# 仮想環境フォルダのみをコピーする
COPY --from=builder /app/.venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

重要なパラメータの解説：

  • POETRY_VIRTUALENVS_IN_PROJECT=true：次のステージへ簡単に持ち出せるよう、プロジェクトディレクトリ内にライブラリをインストールさせます。
  • --no-root：この段階ではソースコードがまだコピーされていないため、メインコードの仮想環境へのインストールを避けます。
  • --only main：PytestやBlackなどの本番環境には不要なライブラリを除外します。

最終的な成果

ビルドコマンドを実行して、その成果を確認しましょう：

docker build -t itfromzero-app .

2回目のビルドでは、インストールステップに CACHED という文字が表示されるはずです。5分間待つ代わりに、すべてが20秒足らずで完了します。あなたのイメージはコンパクトになるだけでなく、同僚の目にも非常にプロフェッショナルに映るでしょう。

PoetryとDockerの組み合わせは、ワークフローをアップグレードするための賢明な一歩です。システムの安定稼働と爆速デプロイを実現したいなら、ぜひこの方法を試してみてください！

Share:
Tags: