はじめに

Pythonのプロジェクトで運用コンテナーをビルドする場合の基本形は、大体こんな感じ。

# ステージ: ビルドコンテナー上でビルド
FROM python:3.13 AS build

... ビルド処理など ...

# ステージ: 運用コンテナーのビルド
FROM python:3.13-slim AS production

... 運用環境の設定など ...

# ビルド環境から生成物をコピーする
COPY --from=build /usr/local/lib/python3.13/site-packages /usr/local/lib/python3.13/site-packages

... アプリケーションコードのコピー

COPY –from=buildの行は、他にもルートのキャッシュをコピーするなど、色々やり方があるので、この形である必要はない。
ググれば出てくる。

また、マルチステージビルドがなぜ必要かについては言及しない。
とりあえず動かしたいだけなら、slimのような最適化したコンテナーではなく、全部入りを使っていればよい。

ビルド環境と運用環境のコンテナーの違いを考える

重要なのは、3.13と3.13-slimのタグが付いたベースコンテナーの中身の違い。
3.13にはgccなどのコンパイラー、ビルドに必要なヘッダ類、その他パッケージが含まれているため、ビルドができる。一方、slimには含まれないため、ビルドできない。
※タグの付け方はリポジトリによって異なる。上記はpythonの場合。

大半のコンテナーは、こんな感じで分かれている。

Pythonはスクリプト単体で成り立っている訳ではなく、利用する依存パッケージ次第でC/C++などの言語で作られたライブラリも利用する。
また、pipなどでパッケージをインストールするタイミングで、C/C++のコードをコンパイルすることもある。

よって、運用コンテナーには、コンパイル済みオブジェクトも含めてコピーする必要がある。

運用コンテナーに含む必要があるもの

psycopg2

Pythonパッケージのpsycopg2は、libpq.so.5を必要とするが、Pythonのパッケージではないため、site-packagesには含まれない。
よって、実行時にlibpq.so.5が見つからないことが原因で落ちる。

Debian/Ubuntu環境でlibpq.so.5が見つからない問題を解決するには、libpq5をaptでインストールすれば良い。
libpqが何者かは、PostgreSQLの公式サイトを参照。

第34章 libpq — C ライブラリ

備考

soは（UNIXまたはLinux）でshared libraryのこと。
WindowsならDLLがこれにあたる。
動的ライブラリなので、起動または利用するタイミングでロードされると考えておけばよい。