PythonアプリのDocker構成入門：Dockerfile、Compose、requirements.txtの役割

PythonアプリケーションをDockerで動かすとき、最初につまずきやすいのは、どのファイルに何を書くかという役割分担です。

requirements.txt、Dockerfile、docker-compose.ymlの関係を理解すれば、構成を上から順に読み解けます。

Dockerイメージはアプリケーションの実行環境を組み立てるひな型であり、コンテナはそのイメージから起動する実行単位です。

Pythonパッケージだけを分離したい場合は、venvとDockerの違いを先に確認すると、使い分けが明確になります。

3つの設定ファイルの関係

三つのファイルは同じ設定を重ねて書くものではなく、それぞれ異なる範囲を担当します。

一つのコンテナだけで足りる構成では、まずDockerfileだけで試し、複数サービスが必要になった段階でComposeを加えると理解しやすくなります。

基本のディレクトリ構成

小規模なFlaskアプリケーションを例にすると、プロジェクトの入口は次のように整理できます。

my-python-app/
├── app/
│   ├── __init__.py
│   └── main.py
├── tests/
│   ├── __init__.py
│   └── test_main.py
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── README.md

この構成は出発点であり、アプリケーションの規模や採用するフレームワークに合わせて分割方法を変えます。

requirements.txtでPythonの依存関係を管理する

requirements.txtには、アプリケーションが利用するPythonパッケージを一行ずつ記述します。

FlaskアプリケーションがHTTP通信にRequestsも使う場合、最小例は次のとおりです。

Flask
requests

バージョンを固定する場合は、パッケージ名の後ろに==とプロジェクトで検証したバージョンを書きます。

特定の古いバージョンを例として固定すると、そのままコピーした読者が古い環境を作るおそれがあるため、採用バージョンは公式情報とアプリケーションの互換性を確認して決めます。

ローカル環境では、次のコマンドで一覧に記載したパッケージをインストールできます。

python -m pip install -r requirements.txt

requirements.txtが担当するのはPythonパッケージであり、Python本体やOS側の環境は次のDockerfileで定義します。

Dockerfileでイメージの構築手順を定義する

Dockerfileは、ベースとなるイメージ、作業場所、依存関係のインストール、ソースコードの配置、起動コマンドを上から順に記述するファイルです。

次の例は、app/main.pyを起動できることを前提にした最小構成です。

FROM python:3-slim

WORKDIR /app

COPY requirements.txt .
RUN python -m pip install --no-cache-dir -r requirements.txt

COPY app ./app

CMD ["python", "app/main.py"]

python:3-slimは構成を説明するための例なので、実際のプロジェクトでは動作確認を済ませたベースイメージのタグを選びます。

Flask以外の選択肢も含めて構成を考える場合は、Pythonフレームワークの比較も参考になります。

docker-compose.ymlで複数のサービスをまとめる

Composeは、WebアプリケーションとRedisのように、複数のコンテナを一つの構成として起動したい場合に使います。

元の例を現在のCompose仕様に合わせて簡潔にすると、次のように書けます。

services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - .:/app
    depends_on:
      - redis

  redis:
    image: redis:alpine

depends_onの短い書き方は起動順を示しますが、Redisが接続を受け付けられる状態まで待つ設定ではありません。

準備完了を確認してからWebアプリケーションを動かす必要がある場合は、ヘルスチェックと条件付きの依存関係を別に設計します。

このComposeファイルはコンテナ同士の構成を定義するだけなので、Flask側にもRedisへ接続する処理と設定が必要です。

Webアプリケーションがコンテナ内のポート5000で待ち受ける構成であれば、次のコマンドで構築と起動をまとめて実行できます。

docker compose up --build

確認後は、次のコマンドでComposeが管理するコンテナを停止して削除します。

docker compose down

構築を進める順序

1. app/にアプリケーションを書き、ローカルで起動できることを確認します。
2. 必要なPythonパッケージをrequirements.txtに記録します。
3. Dockerfileに依存関係のインストールと起動方法を書きます。
4. Redisなど別のサービスが必要な場合にdocker-compose.ymlを追加します。
5. 構築、起動、接続、停止の手順をREADME.mdへ残します。

この順序なら、問題が起きたときにアプリケーション、イメージ構築、複数サービス連携のどこで失敗したかを切り分けやすくなります。

初心者が迷いやすい点

設定ファイルを一度に増やすより、単体で動くアプリケーションから順に確認したほうが、原因を追いやすくなります。

まとめ

requirements.txtはPythonの依存関係、Dockerfileはイメージの構築、docker-compose.ymlは複数サービスの連携を担当します。

まず小さな構成で各ファイルの境界を理解し、データベースやキャッシュなどが必要になった時点でComposeへサービスを追加すると、構成の意図を保ちやすくなります。