Gunicornマスタープロセスによるダウンタイムなしのコード反映

FastAPIコンテナを運用する際、ソースコードの更新に伴うサーバー再起動は運用効率に直結します。Gunicornベースのサーバープロセスでは、マスタープロセスに対してSIGHUPシグナルを送信することで、ダウンタイムなしでワーカープロセスを再ロードするGraceful Reloadが可能です。公式イメージでは設定ファイルの優先読み込みパスが定められていますが、プロジェクトルートにカスタム設定ファイルを配置して挙動を制御できます。

# custom_worker_conf.py
bind = "0.0.0.0:8080"
worker_pid_path = "/var/run/gunicorn_main.pid"
log_level = "info"
error_log_file = "/var/log/gunicorn_err.log"
access_log_file = "/var/log/gunicorn_access.log"

設定を適用しコンテナを起動した後、実行中のプロセスIDを参照してシグナルを送信します。

docker exec -it <container_name> /bin/sh -c "kill -HUP \$(cat /var/run/gunicorn_main.pid)"

なお、ホストマウント時にシンボリックリンクを経由している場合、ファイルシステムのイベント監視が正しく機能せず、シグナル送信後も新コードが反映されないケースがあります。この現象はコンテナのボリュームマウント構造に依存するため、シンボリックリンクを解消して実ファイルを直接配置するか、またはコンテナの完全再起動に切り替えるのが確実です。

依存関係を事前解決したカスタムベースイメージの構築

プロジェクトごとの環境構築負荷を削減するため、公式イメージをベースに頻繁に利用される外部ライブラリを事前にインストールしたカスタムベースイメージを用意すると効率的です。例えば、データベース接続、非同期処理、ログ出力、オブジェクトストレージ連携などの依存関係をDockerfile内で一元管理し、ビルドアーティファクトとして配布できます。

FROM tiangolo/uvicorn-gunicorn-fastapi:python3.10

COPY requirements.txt /workspace/deps.txt
RUN pip install --no-cache-dir -r /workspace/deps.txt \
    && rm /workspace/deps.txt

依存ファイルには、fastapi, pydantic, redis, sqlalchemy, loguru, requests, numpy などのモジュールをバージョン固定で記載します。これにより、各プロジェクトで重複するセットアップ作業を省き、CI/CDパイプラインの高速化と環境の標準化を図れます。

コンテナ起動時の抽象的なエラーログの解消方法

コンテナ起動時にGunicornがクラッシュし、ログに gunicorn.errors.HaltServer: <HaltServer 'Worker failed to boot.' 3> といった抽象的なメッセージしか出力されない場合があります。これは、アプリケーションコードのインポート段階で例外が発生し、マスタープロセスがワーカーの初期化を中断しているためです。デフォルト設定では詳細なスタックトレースが隠蔽されるため、設定ファイルに preload_app = True を追加することで、マスタープロセス起動時にアプリケーションの読み込みを強制し、エラーの詳細を可視化できます。

# custom_worker_conf.py への追記
preload_app = True

このパラメータを有効化して再起動すると、欠落モジュールや構文エラーが明確に表示されます。

Traceback (most recent call last):
  File "/app/main.py", line 15, in <module>
    from core.database import init_pool
ModuleNotFoundError: No module named 'core'

根本原因を特定し、該当の修正や依存関係の追加を行って正常にプロセスが起動する状態に戻したら、本番運用では preload_app を無効化して、メモリ使用量を抑えつつワーカーごとの独立した初期化プロセスに戻すのが標準的なプラクティスです。