Django を WSL＋systemd＋Gunicorn で安定稼働させる手順とトラブル解決記録

Webアプリを開発中のあなた、聞いてください。この構成は「ちょっとローカルで試す」以上の価値があります。
私は WSL 上で Django を動かし、Gunicorn による本番っぽい起動を systemd で安定させる方法を取りました。
ところが、途中で systemd ファイルが読み込まれずに起動に失敗したり、Gunicorn ワーカーが勝手に落ちて再起動を繰り返したり……。
この記事では、そんなトラブルを **一つひとつ潰しながら構築した手順** を、初心者にも分かりやすく、WordPress ブログにまとめた形で紹介します。
再現性を重視して、「コピペOK」の systemd 設定例も掲載。あなたの Django 環境構築がぐっと堅牢になります。

1. 背景と構成設計：なぜ WSL＋systemd＋Gunicorn を選んだか
2. トラブル発生と解決の記録
3. 最終構成と運用ポイント
まとめ
〆最後に〆

1. 背景と構成設計：なぜ WSL＋systemd＋Gunicorn を選んだか

WSL (Windows Subsystem for Linux) 上で Django を動かす目的は、ローカル開発環境ながら実運用に近い挙動を確認したい からでした。単に manage.py runserver を使うだけでは、本番環境のプロセス管理や再起動が考慮されていません。一方で Gunicorn は Python の WSGI アプリケーション用 HTTP サーバーとして広く使われており、本番っぽさを出すには理想的です。さらに systemd を使えば、Linux 起動時に自動で Gunicorn を起動し、落ちたら再起動もできるため、安定性と自動化の両方が得られます。今回の構成は、WSL 上という開発用環境でありながら、本番運用のシミュレーションを兼ねた「準本番運用」体制を狙ったものです。

1.1 WSL を使うメリットと注意点

メリット

Windows 上で Linux 環境を自然に利用できる
ファイル共有が容易、開発効率が高い
Web サーバーや Python ライブラリが Linux と同等に動作

注意点

systemd を使うには WSL の設定変更や cgroup2 の確認が必要
WSL のメモリや CPU 制限が Gunicorn のワーカー数に影響

1.2 Gunicorn とは何か：WSGI サーバーの役割

Gunicorn（Green Unicorn）は、Python 用の WSGI サーバーです。Django を本番寄りに動作させる方法として最も一般的で、systemd 管理との相性が抜群です。

軽量で高速
ワーカー数の調整によって性能を変えられる
systemd のサービス化が容易

1.3 systemd によるプロセス管理の重要性

systemd は Linux のサービス管理の中心であり、Gunicorn のプロセスを安定して運用するには不可欠です。

自動起動、自動再起動を組み込める
ログ管理が journalctl 経由で統一される
復旧時間を短縮し、手動作業が減る

2. トラブル発生と解決の記録

構築の途中で、systemd サービスファイルの文法エラーや不可視文字の混入、Gunicorn ワーカーが落ちる問題など、複数のトラブルに直面しました。systemd によるサービス起動で「Bad message」「Invalid section header」といったエラーが出たのは、サービスファイル自体の記述ミスや改行／スペースの不正が原因でした。また Gunicorn ワーカーが再起動を繰り返す現象は、Django 側の ALLOWED_HOSTS の構文ミスが原因という意外な落とし穴でもありました。これらを丁寧に潰した結果、systemd による安定稼働が実現しました。

2.1 systemd ファイルの文法エラー (“Bad message”)

主な原因

[Unit] と Description を同じ行に書いていた
Windows 由来の BOM や不可視文字が紛れ込んでいた
全角スペース

対処

サービスファイルを作り直す
sudo systemctl daemon-reload
sudo systemctl reset-failed

2.2 Gunicorn ワーカーが落ちる (“SystemExit: 1”)

ワーカーが起動後すぐに停止し、systemd が再起動ループに突入
原因は ALLOWED_HOSTS の書き間違い（Python のリスト構文エラー）
修正後は正常稼働

2.3 systemd の再起動設定見直し

サービスが高頻度に再起動してしまう場合は、systemd 側の再起動間隔を調整します。

Restart=always
RestartSec=5

3. 最終構成と運用ポイント

最終的に作成した systemd サービスファイルと運用方針は、安定性とメンテナンス性の両立を意識した構成です。ユーザー指定、作業ディレクトリ、Gunicorn 実行ファイルのフルパス指定、再起動ポリシーを含めることで、WSL 再起動後も安定して Django が立ち上がる環境が整いました。今後は Nginx を追加し、静的ファイルの配信や SSL 化を組み込むことで、本番レベルの構成に近づけることができます。

3.1 最終 systemd サービスファイル例

[Unit]
Description=Django Gateway Service
After=network.target

[Service]
User=matumoto-1025
Group=matumoto-1025
WorkingDirectory=/mnt/c/users/matumoto-1025/project_rails3_251118/django_gateway
ExecStart=/mnt/c/users/matumoto-1025/project_rails3_251118/django_gateway/venv/bin/gunicorn --workers 2 --bind 0.0.0.0:8000 gateway.wsgi:application
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

3.2 systemd 操作コマンド一覧

操作	コマンド	説明
デーモン再読み込み	`sudo systemctl daemon-reload`	設定変更を systemd に反映
失敗状態リセット	`sudo systemctl reset-failed`	systemd の失敗カウンタをリセット
起動時自動化	`sudo systemctl enable django_gateway`	ブート時に自動起動
起動	`sudo systemctl start django_gateway`	サービス起動
状態確認	`sudo systemctl status django_gateway`	ログや状態を確認

3.3 運用の拡張ポイント

Nginx を加え、静的ファイル配信を最適化
Gunicorn の --max-requests でメモリ管理強化
HTTPS 化（Let’s Encrypt）

まとめ

以上が、私が WSL 上で Django を Gunicorn + systemd で運用するために経験したトラブルと、そこから得られた最終構成の記録です。
systemd ファイルの文法ミス、不可視文字、Gunicorn ワーカーのクラッシュ、ALLOWED_HOSTS の構文ミスなど、原因は多岐にわたりましたが、一つずつ修正することで、最終的には “Active (running)” の安定運用に到達しました。
この構成は学習目的にとどまらず、本番寄りの運用シミュレーションとして極めて有効です。
今後 Nginx や HTTPS を追加すれば、そのまま本番構成に近づきます。この記事があなたの Django 開発の助けになれば幸いです。