riceshop のローカル開発環境を Docker で構築するための、開発者向け手順書です。空のクローン直後から、開発サーバーが http://localhost:8000 で動くまでをカバーします。
このドキュメントは旧
specs/10_開発環境構築手順書.mdを、現行のDockerfile/docker-compose.dev.yml/env.development/config/settings.pyと照合して再構成したものです。旧手順書との差異は本文中に「実装メモ」として注記しています。
docker compose サブコマンドが使える v2 系を前提）。docker compose で動きます。コマンドは PowerShell / bash 共通です。xhtml2pdf）で日本語を出力するためのフォントはイメージ内に同梱・設定されます。事前ダウンロードは不要です。開発環境はリポジトリ直下の以下のファイルで定義されています。クローンした時点で揃っているため、通常は編集不要です（環境変数ファイルのみ後述の調整が必要）。
| ファイル | 役割 |
|---|---|
Dockerfile |
アプリイメージのビルド定義（python:3.12-slim ベース） |
requirements.txt |
Python 依存パッケージ |
docker-compose.dev.yml |
開発用 Compose 定義（app + db） |
docker-compose.yml |
本番用 Compose 定義（→ operations/本番デプロイ） |
entrypoint.sh |
本番コンテナ起動スクリプト（migrate → collectstatic → gunicorn） |
env.development |
開発用の環境変数ファイル |
env.production.template |
本番用環境変数のテンプレート（コピーして env.production を作る） |
.dockerignore |
ビルドコンテキストから除外するファイル（詳細な整理は 補足資料 で扱う） |
python:3.12-slim をベースに、mysqlclient（default-libmysqlclient-dev / pkg-config / gcc）と PDF 描画（libfreetype6-dev）に必要な OS パッケージを導入し、requirements.txt をインストールします。ENTRYPOINT に entrypoint.sh を設定しているため、本番用 Compose ではそのまま起動するとマイグレーション → 静的ファイル収集 → Gunicorn 起動が走ります。
実装メモ（
default-mysql-client、Issue #20）:mysqldumpコマンドを含む DB クライアント（Debian 系のdefault-mysql-client、実体は MariaDB クライアント）も導入済みです。年度締め画面からアプリコンテナ内で直接mysqldumpを実行してその場でバックアップをダウンロードする機能（features/管理者向け補助機能 §2.1.1）で使用します。dbへの接続は Docker 内部ネットワークに閉じているため、SSL は--skip-sslで無効化しています（MySQL クライアントの--ssl-mode=DISABLEDではなく、MariaDB クライアントの--skip-sslを使う点に注意）。
Django==4.2.13
gunicorn==22.0.0
mysqlclient==2.2.4
python-dotenv==1.0.1
django-bootstrap-v5
icecream
django-debug-toolbar
django-extensions
xhtml2pdf==0.2.11
Markdown==3.6
whitenoise==6.7.0
実装メモ: 旧手順書では
icecream==2.1.3とバージョン固定でしたが、現行のrequirements.txtではicecreamはバージョン非固定です。django-bootstrap-v5/django-debug-toolbar/django-extensionsも非固定です。
主要パッケージの用途:
django-debug-toolbar — 開発補助。DEBUG=True のときだけ INSTALLED_APPS / MIDDLEWARE に追加されます（config/settings.py）。django-extensions — 開発補助コマンド群。config/settings.py で 常時 INSTALLED_APPS に登録されています（DEBUG に依存しません）。whitenoise — 静的ファイル配信。whitenoise.runserver_nostatic を常時、ミドルウェアを常時利用。xhtml2pdf — 請求書 PDF 生成で利用。icecream — デバッグ出力（→ features/管理者向け補助機能）。実装メモ（
Markdownパッケージ）:requirements.txtに Python のMarkdownが含まれますが、現行コードに Python 側の利用箇所（import markdown等）は見当たりません。オンラインマニュアルの本文描画はブラウザ側で行われ、static/js/manual.jsが Markdown ファイルを fetch しmarked.parse(...)でレンダリングします（→ features/管理者向け補助機能）。
開発環境では -f docker-compose.dev.yml を明示して使います。本番用 docker-compose.yml とは別物です。
app サービス
env_file: env.development で環境変数を注入。volumes: .:/app でリポジトリ全体をマウント（ソース編集が即反映される）。ports: "8000:8000" をホストへ公開。entrypoint: python manage.py runserver 0.0.0.0:8000 --skip-checks で Dockerfile の ENTRYPOINT を上書きし、開発サーバーを起動。
entrypoint.sh（自動 migrate / collectstatic）は走りません。マイグレーションは手動で実行する必要があります（→ §3）。--skip-checks で manage.py check を省略して起動を高速化しています。db サービス
mysql:8.0。env_file: env.development。volumes: ./db_data:/var/lib/mysql に永続化（db_data/ は Git 管理外）。ports: "13306:3306" — ホスト側 13306 に公開（コンテナ内は 3306）。ローカルの MySQL クライアントから繋ぐ場合は 13306 を使います。healthcheck で起動完了を待ってから app が起動（depends_on: condition: service_healthy）。env.development は雛形値が入っているため、ローカル用に値を設定します。
DJANGO_SECRET_KEY='your_very_secret_random_string_here'
DJANGO_DEBUG=True
MYSQL_DATABASE=riceshop_db
MYSQL_USER=riceshop_user
MYSQL_PASSWORD='your_strong_password_here'
MYSQL_ROOT_PASSWORD='your_strong_root_password_here'
MYSQL_HOST=db
DJANGO_ALLOWED_HOSTS=
DJANGO_CSRF_TRUSTED_ORIGINS=http://localhost:8000,http://127.0.0.1:8000
DJANGO_SECRET_KEY / MYSQL_* の各パスワードは任意の値に置き換えてください（開発用途なので雛形のままでも起動はします）。DJANGO_DEBUG=True のとき、config/settings.py が ALLOWED_HOSTS に localhost / 127.0.0.1 / 0.0.0.0 を自動追加し、debug_toolbar も有効になります。実装メモ（環境変数の読み込み経路）:
config/settings.pyは冒頭でload_dotenv()を呼び、カレントディレクトリの.envを読みます。挙動を正確に整理すると次のとおりです。
- Docker 開発（本手順）:
docker-compose.dev.ymlのenv_file: env.developmentによりDJANGO_*/MYSQL_*がプロセス環境に注入されます。python-dotenvの既定（override=False）では既存の環境変数を上書きしないため、同名キーはenv.developmentの値が優先されます。.envの見え方:.dockerignoreで.envはビルド時イメージには含まれませんが、docker-compose.dev.ymlが.:/appをマウントするため、ホスト直下に.envがあれば実行中コンテナでは/app/.envとして見えます。ただし上記のとおりDJANGO_*/MYSQL_*はenv_fileが優先するため、Django の DB 接続等はenv.developmentが供給元になります。- 非 Docker（
python manage.pyを直接実行）:env_fileは効かないため、load_dotenv()が読む.envが設定の供給源になり得ます。なお、本リポジトリ直下の
.envは Butler / Git / Wiki.js などのツール用の認証情報で、DJANGO_*/MYSQL_*のような Django 設定キーは含みません（Git 管理外）。そのため現状の Docker 開発で Django 設定に影響することはありません。
実装メモ（README は未整備）: 旧棚卸し表は「README と照合」とありますが、現状リポジトリに README はありません。本ドキュメントが実質的な開発環境構築の入口です。
docker compose -f docker-compose.dev.yml up -d --build
db の healthcheck が通ると app が runserver を起動します。
開発用 Compose は entrypoint.sh を使わないため、初回および以後のマイグレーションは手動で実行します。
docker compose -f docker-compose.dev.yml exec app python manage.py migrate
管理画面・管理者ダッシュボードにログインするためのスーパーユーザーを作成します。
docker compose -f docker-compose.dev.yml exec app python manage.py createsuperuser
補足: riceshop には購入者向けの新規登録機能はありません。一般顧客アカウントは管理者が顧客管理画面から発行します（→ features/アカウント認証 §4）。
ブラウザで http://localhost:8000 にアクセスし、ログイン画面が表示されれば成功です。ログイン後は、スタッフユーザーなら管理者ダッシュボード、一般顧客なら商品一覧へリダイレクトされます（→ features/アカウント認証）。
補足（新規プロジェクトとしての初期化について）: 旧手順書には
django-admin startproject/startappでゼロから骨格を作る手順が含まれていますが、本リポジトリには既にconfigプロジェクトと各アプリ（accounts/products/orders/cart/system_settings/dashboard/mg_orders/mg_customers/mg_masters/mg_workflow/common）が存在します。クローンして開発する場合これらの手順は不要です。アプリ構成は design/アーキテクチャ を参照してください。
| 操作 | コマンド |
|---|---|
| 起動 | docker compose -f docker-compose.dev.yml up -d |
| 停止 | docker compose -f docker-compose.dev.yml down |
| ログ確認 | docker compose -f docker-compose.dev.yml logs -f app |
| 管理コマンド実行 | docker compose -f docker-compose.dev.yml exec app python manage.py <コマンド> |
| マイグレーション作成 | ... exec app python manage.py makemigrations |
| マイグレーション適用 | ... exec app python manage.py migrate |
ソースはコンテナにマウントされているため、Python ファイルの編集は runserver の自動リロードで反映されます。
⚠️ 重要（DB データの実体は bind mount）: 開発用
dbサービスはdocker-compose.dev.ymlで./db_data:/var/lib/mysqlの bind mount によりデータを永続化しています（Compose ファイル末尾にdb_dataという named volume 宣言がありますが、DB サービスでは使われていません）。docker compose down -vが削除するのは Compose 管理の named volume であり、bind mount のホストディレクトリ./db_data/は削除されません。
コンテナとネットワークを作り直すだけなら、以下で十分です。
# コンテナ・ネットワーク・(未使用の)named volume を削除
docker compose -f docker-compose.dev.yml down -v
# 再ビルドして起動
docker compose -f docker-compose.dev.yml up -d --build
# 起動ログを確認（Ctrl+C で終了）
docker compose -f docker-compose.dev.yml logs -f app
データベースを完全に初期化したい場合は、コンテナ停止後にホストの ./db_data/ を手動削除する必要があります。
docker compose -f docker-compose.dev.yml down
rm -rf ./db_data # ⚠️ DB の全データが消えます。本番では絶対に実行しない
docker compose -f docker-compose.dev.yml up -d --build
DB を初期化した後は、§3.3 のマイグレーション以降（マイグレーション → スーパーユーザー作成）を再実行してください。
| 症状 | 原因 | 対処 |
|---|---|---|
ALLOWED_HOSTS エラー |
DJANGO_DEBUG が True でない／DJANGO_ALLOWED_HOSTS 不足 |
env.development の DJANGO_DEBUG=True を確認（localhost 等が自動追加される） |
| データベース接続エラー | db コンテナ未起動・起動途中 |
docker compose -f docker-compose.dev.yml up -d db で再起動し、healthcheck 完了を待つ |
| ポート 8000 使用中 | 別プロセスが占有 | 占有プロセスを停止するか、docker-compose.dev.yml の ports を変更 |
| ポート 13306 使用中 | ローカル MySQL 等と衝突 | db の ports を別ポートへ変更 |
| マイグレーションエラー | マイグレーション不整合 | §5.1 のクリーンアップを実行 |
元資料: specs/10_開発環境構築手順書.md (Ver.4.0) を現行コード（Dockerfile, requirements.txt, docker-compose.dev.yml, entrypoint.sh, env.development, env.production.template, .dockerignore, config/settings.py）と照合して再構成
関連: README, specs棚卸し表, Issue #1