モデル比較

#Docker+DockerComposeによるローカル開発環境構築手順書この手順書では、以下の4サービスからなるローカル開発環境をDockerとDockerComposeで構築します。|サービス|技術|ホスト側ポート|説明||---|---|---:|---||フロントエンド|Next.js|3000|ブラウザから操作するWebUI||バックエンドAPI|FastAPI|8000|RESTAPIを提供||データベース|PostgreSQL|5432|永続化ストレージ||キャッシュ|Redis|6379|一時データ・キャッシュ|PostgreSQLとRedisは公式イメージを使うためDockerfileは不要です。Dockerfileを用意するのはNext.jsとFastAPIです。---##1.前提条件-DockerDesktop/DockerEngine-DockerComposev2以降確認コマンド:```bashdockercomposeversion```-以下のポートが空きポートであること-3000-8000-5432-6379ホスト側にNode.jsやPythonをインストールする必要はありません。すべてコンテナ内で実行します。---##2.全体構成```textブラウザ│▼Next.jsフロントエンド:3000│▼FastAPIバックエンド:8000├──PostgreSQL:5432└──Redis:6379```ローカル開発では、ブラウザからFastAPIを直接呼び出す構成にします。そのためフロントエンドの`NEXT_PUBLIC_API_BASE_URL`は`http://localhost:8000`にします。---##3.プロジェクト構造以下のようにディレクトリを作成してください。```text.├──.env.example├──.env├──.gitignore├──docker-compose.yml├──frontend/│├──Dockerfile│├──.dockerignore│├──package.json│├──next.config.mjs│├──tsconfig.json│├──next-env.d.ts│└──app/│├──layout.tsx│└──page.tsx└──backend/├──Dockerfile├──.dockerignore├──requirements.txt└──app/├──__init__.py├──main.py├──core/│├──__init__.py│└──config.py├──db/│├──__init__.py│└──session.py└──api/├──__init__.py└──health.py```---#4.環境変数ファイル##4-1.`.env.example`プロジェクトルートの`.env.example`を作成します。```dotenv#=========================================================#開発環境共通設定#=========================================================APP_ENV=developmentAPP_DEBUG=trueLOG_LEVEL=INFO#=========================================================#PostgreSQL設定#DockerCompose内でサービス名としてdbを使用します。#ホスト側からpsql等で直接アクセスする場合も利用できます。#=========================================================POSTGRES_USER=appPOSTGRES_PASSWORD=appPOSTGRES_DB=app#必要に応じてコメントを外して利用#POSTGRES_HOST=localhost#POSTGRES_PORT=5432#=========================================================#Redis設定#DockerCompose内でサービス名としてredisを使用します。#=========================================================#REDIS_HOST=localhost#REDIS_PORT=6379#=========================================================#Next.jsフロントエンド設定#ブラウザからFastAPIを呼び出す際のベースURLです。#NEXT_PUBLIC_付きの環境変数はブラウザ側に公開されます。#秘密情報を入れないでください。#=========================================================NEXT_PUBLIC_API_BASE_URL=http://localhost:8000#=========================================================#FastAPIバックエンド設定#CORSで許可するオリジンをカンマ区切りで指定できます。#=========================================================CORS_ORIGINS=http://localhost:3000```##4-2.`.env`を作成```bashcp.env.example.env````.env`はコミットしないようにしてください。---##5.`.gitignore`ルートに`.gitignore`を作成します。```gitignore#環境変数.env#Next.jsfrontend/node_modules/frontend/.next/#Pythonbackend/__pycache__/backend/.venv/backend/.envbackend/.env.*#OS.DS_Store```---#6.`docker-compose.yml`プロジェクトルートに`docker-compose.yml`を作成します。```yaml#=========================================================#DockerCompose設定#DockerComposev2以降を想定しています。#versionキーは非推奨のため省略しています。#=========================================================services:#-------------------------------------------------------#Next.jsフロントエンド#-------------------------------------------------------frontend:build:#Dockerfileの場所context:./frontenddockerfile:Dockerfile#任意：固定のコンテナ名。#複数の開発プロジェクトを並行で動かす場合は削除してください。container_name:next-fastapi-frontend#ホスト側ポート:コンテナ内ポートports:-"3000:3000"volumes:#ソースコードをコンテナにbindmountしてホットリロードを有効化-./frontend:/app#ホスト側やイメージ側のnode_modulesで上書きされないように#コンテナ用のnamedvolumeを使用します。-frontend_node_modules:/app/node_modules#Next.jsのビルドキャッシュ。#ホスト側の./frontend/.nextを生成したくない場合に使います。#スタールキャッシュの問題が出た場合はこのvolumeを削除してください。-frontend_next_cache:/app/.nextenvironment:#開発モードとして明示NODE_ENV:development#ホットリロード時にNext.jsが0.0.0.0でlistenするための設定HOSTNAME:0.0.0.0#ブラウザからFastAPIを呼び出すベースURL。#ブラウザが動くのはホスト側なのでlocalhostを使用します。#.envのNEXT_PUBLIC_API_BASE_URLを使用します。NEXT_PUBLIC_API_BASE_URL:${NEXT_PUBLIC_API_BASE_URL:-http://localhost:8000}#依存サービスの起動待ち#condition:service_healthyにより、ヘルスチェック成功まで待つdepends_on:backend:condition:service_healthydb:condition:service_healthyredis:condition:service_healthy#-------------------------------------------------------#FastAPIバックエンド#-------------------------------------------------------backend:build:context:./backenddockerfile:Dockerfilecontainer_name:next-fastapi-backendports:-"8000:8000"volumes:#ソースコードをbindmountしてuvicornのホットリロードを有効化-./backend:/appenvironment:#アプリ基本設定APP_ENV:developmentAPP_DEBUG:${APP_DEBUG:-true}LOG_LEVEL:${LOG_LEVEL:-INFO}#PostgreSQL接続文字列。#DockerCompose内でホスト名はservice名、つまりdbを使用します。DATABASE_URL:postgresql+psycopg2://${POSTGRES_USER:-app}:${POSTGRES_PASSWORD:-app}@db:5432/${POSTGRES_DB:-app}#Redis接続文字列。#DockerCompose内でホスト名はservice名、つまりredisを使用します。REDIS_URL:redis://redis:6379/0#CORSで許可するオリジン。#カンマ区切りで複数指定できます。CORS_ORIGINS:${CORS_ORIGINS:-http://localhost:3000}depends_on:db:condition:service_healthyredis:condition:service_healthyhealthcheck:#pythonスタンダードライブラリでHTTPチェックを行います。#curlが入っている必要はありません。#/healthが200を返すまでunhealthyとします。test:["CMD","python","-c","importurllib.request;urllib.request.urlopen('http://127.0.0.1:8000/health')"]interval:10stimeout:5sretries:5start_period:30s#-------------------------------------------------------#PostgreSQL#-------------------------------------------------------db:image:postgres:16-alpinecontainer_name:next-fastapi-postgresenvironment:#初期ユーザーPOSTGRES_USER:${POSTGRES_USER:-app}#初期パスワード#本番環境や公開環境では強いパスワードを使用してください。POSTGRES_PASSWORD:${POSTGRES_PASSWORD:-app}#初期データベース名POSTGRES_DB:${POSTGRES_DB:-app}ports:#ホスト側からpsqlやGUIツールでアクセスできるように公開します。#コンテナ間通信だけならportsは不要です。-"5432:5432"volumes:#PostgreSQLのデータ永続化-postgres_data:/var/lib/postgresql/datahealthcheck:#PostgreSQLが接続可能になったらhealthyとします。test:["CMD-SHELL","pg_isready-U${POSTGRES_USER:-app}-d${POSTGRES_DB:-app}"]interval:5stimeout:5sretries:10#-------------------------------------------------------#Redis#-------------------------------------------------------redis:image:redis:7-alpinecontainer_name:next-fastapi-redis#AOF永続化を有効化します。#ローカル開発なのでパスワード認証なしで保護モードを無効にしています。#公開環境では認証とネットワーク制限を必ず設定してください。command:["redis-server","--appendonly","yes","--protected-mode","no"]ports:#ホスト側からredis-cli等でアクセスできるように公開します。#コンテナ間通信だけならportsは不要です。-"6379:6379"volumes:#Redisのデータ永続化-redis_data:/datahealthcheck:#PINGに応答したらhealthyとします。test:["CMD","redis-cli","ping"]interval:5stimeout:3sretries:10#---------------------------------------------------------#永続化用namedvolumes#---------------------------------------------------------volumes:postgres_data:redis_data:frontend_node_modules:frontend_next_cache:```---#7.フロントエンドNext.js設定##7-1.`frontend/Dockerfile````dockerfile#syntax=docker/dockerfile:1#Node.js20LTSベースFROMnode:20-alpine#作業ディレクトリWORKDIR/app#依存関係を先にコピーしてビルドキャッシュを活かす#package-lock.jsonが存在する場合はnpmciを使用します。COPYpackage.jsonpackage-lock.json*./RUNif[-fpackage-lock.json];thennpmci;elsenpminstall;fi#アプリコードをコピーCOPY..#Next.jsがlistenするポートEXPOSE3000#開発サーバーを起動#nextdevはホットリロード有効です。CMD["npm","run","dev"]```##7-2.`frontend/.dockerignore````gitignorenode_modules.nextoutnpm-debug.log*yarn-debug.log*yarn-error.log*.env.env.*.git.gitignore.DS_Store```##7-3.`frontend/package.json````json{"name":"frontend","version":"0.1.0","private":true,"scripts":{"dev":"nextdev-p3000-H0.0.0.0","build":"nextbuild","start":"nextstart-p3000","lint":"nextlint"},"dependencies":{"next":"14.2.15","react":"^18.3.1","react-dom":"^18.3.1"},"devDependencies":{"@types/node":"^20.14.0","@types/react":"^18.3.3","@types/react-dom":"^18.3.0","typescript":"^5.5.3"}}```##7-4.`frontend/next.config.mjs````js/**@type{import('next').NextConfig}*/constnextConfig={//StrictModeを有効化reactStrictMode:true,};exportdefaultnextConfig;```##7-5.`frontend/tsconfig.json````json{"compilerOptions":{"lib":["dom","dom.iterable","esnext"],"allowJs":true,"skipLibCheck":true,"strict":true,"noEmit":true,"esModuleInterop":true,"module":"esnext","moduleResolution":"bundler","resolveJsonModule":true,"isolatedModules":true,"jsx":"preserve","incremental":true,"plugins":[{"name":"next"}],"paths":{"@/*":["./*"]}},"include":["next-env.d.ts","**/*.ts","**/*.tsx",".next/types/**/*.ts"],"exclude":["node_modules"]}```##7-6.`frontend/next-env.d.ts````ts///<referencetypes="next"/>///<referencetypes="next/image-types/global"/>//NOTE:Thisfileshouldnotbeedited//seehttps://nextjs.org/docs/app/building-your-application/configuring/typescriptformoreinformation.```##7-7.`frontend/app/layout.tsx````tsximporttype{Metadata}from"next";importtype{ReactNode}from"react";exportconstmetadata:Metadata={title:"Next.js+FastAPIDev",description:"DockerComposelocaldevelopmentenvironment",};exportdefaultfunctionRootLayout({children,}:{children:ReactNode;}){return(<htmllang="ja"><body>{children}</body></html>);}```##7-8.`frontend/app/page.tsx````tsx"useclient";import{useEffect,useState}from"react";typeHealthData={status?:string;database?:string;redis?:string;app?:string;env?:string;};exportdefaultfunctionHomePage(){const[status,setStatus]=useState<"loading"|"ok"|"error">("loading");const[data,setData]=useState<HealthData|null>(null);const[error,setError]=useState<string>("");useEffect(()=>{//NEXT_PUBLIC_付きの環境変数はブラウザ側からも利用可能constbaseUrl=process.env.NEXT_PUBLIC_API_BASE_URL??"http://localhost:8000";fetch(`${baseUrl}/health`).then((res)=>{if(!res.ok)thrownewError(`HTTP${res.status}`);returnres.json();}).then((json:HealthData)=>{setData(json);setStatus("ok");}).catch((err:Error)=>{setError(err.message);setStatus("error");});},[]);return(<mainstyle={{padding:24,fontFamily:"sans-serif"}}><h1>Next.js+FastAPI+PostgreSQL+Redis</h1><p>ローカル開発環境です。</p><section><h2>FastAPI/health</h2>{status==="loading"&&<p>読み込み中...</p>}{status==="error"&&(<pstyle={{color:"red"}}>API接続失敗:{error}</p>)}{status==="ok"&&data&&(<prestyle={{background:"#f5f5f5",padding:16}}>{JSON.stringify(data,null,2)}</pre>)}</section></main>);}```---#8.バックエンドFastAPI設定##8-1.`backend/Dockerfile````dockerfile#syntax=docker/dockerfile:1#Python3.12slimベースFROMpython:3.12-slim#Pythonのログがバッファリングされずリアルタイムに見えるように#また、bytecodeを書き出さないようにENVPYTHONDONTWRITEBYTECODE=1\PYTHONUNBUFFERED=1#作業ディレクトリWORKDIR/app#依存関係を先にコピーしてビルドキャッシュを活かすCOPYrequirements.txt.RUNpipinstall--no-cache-dir--upgradepip\&&pipinstall--no-cache-dir-rrequirements.txt#アプリコードをコピーCOPY..#FastAPIがlistenするポートEXPOSE8000#開発サーバーを起動#uvicorn[standard]にはwatchfilesが含まれており、ファイル変更を検知できます。#--reloadでホットリロードを有効化します。#--reload-dirappで変更監視をappディレクトリに限定します。CMD["uvicorn","app.main:app","--host","0.0.0.0","--port","8000","--reload","--reload-dir","app"]```##8-2.`backend/.dockerignore````gitignore__pycache__/*.pyc*.pyo.venv/venv/.env.env.*.pytest_cache/.mypy_cache/.ruff_cache/.git/.gitignore.DS_Store```##8-3.`backend/requirements.txt````textfastapi>=0.111,<1.0uvicorn[standard]>=0.30,<1.0sqlalchemy>=2.0,<2.1psycopg2-binary>=2.9,<3.0pydantic>=2.7,<3.0pydantic-settings>=2.3,<3.0redis>=5.0,<6.0python-dotenv>=1.0,<2.0```##8-4.`backend/app/__init__.py````python```##8-5.`backend/app/core/__init__.py````python```##8-6.`backend/app/core/config.py````pythonfromfunctoolsimportlru_cachefrompydantic_settingsimportBaseSettings,SettingsConfigDictclassSettings(BaseSettings):"""アプリケーション設定。読み込み優先順位:1.コンテナ環境変数DockerComposeのenvironmentで渡された変数が優先されます。2.backend/.envローカルでuvicornを直接実行する場合に使えます。Docker環境ではComposeのenvironmentが優先されます。"""model_config=SettingsConfigDict(env_file=".env",env_file_encoding="utf-8",extra="ignore",)#アプリ基本設定app_name:str="FastAPIBackend"app_env:str="development"app_debug:bool=Trueapi_v1_prefix:str="/api/v1"log_level:str="INFO"#PostgreSQL#Docker環境ではdocker-compose.ymlで#postgresql+psycopg2://user:pass@db:5432/dbdbのように設定されます。database_url:str="postgresql+psycopg2://app:app@localhost:5432/app"#Redis#Docker環境ではdocker-compose.ymlでredis://redis:6379/0に設定されます。redis_url:str="redis://localhost:6379/0"#CORS許可オリジン#カンマ区切りで複数指定します。#例:http://localhost:3000,http://localhost:3001cors_origins:str="http://localhost:3000"@propertydefcors_origin_list(self)->list[str]:"""CORS用オリジンリストを返します。"""return[origin.strip().rstrip("/")fororigininself.cors_origins.split(",")iforigin.strip()]@lru_cachedefget_settings()->Settings:"""設定インスタンスをキャッシュして返します。環境変数が変更された場合はコンテナを再起動してください。"""returnSettings()```##8-7.`backend/app/db/__init__.py````python```##8-8.`backend/app/db/session.py````pythonfromsqlalchemyimportcreate_enginefromsqlalchemy.ormimportsessionmakerfromapp.core.configimportget_settingssettings=get_settings()#PostgreSQLへの接続#pool_pre_ping=Trueにより接続が切れた後に再利用されるのを防ぎます。#pool_recycle=1800により接続プールの再利用周期を1時間にします。engine=create_engine(settings.database_url,pool_pre_ping=True,pool_recycle=1800,)SessionLocal=sessionmaker(bind=engine,autocommit=False,autoflush=False,)defget_db():"""FastAPIの依存性として使用するDBセッションジェネレータ。"""db=SessionLocal()try:yielddbfinally:db.close()```##8-9.`backend/app/api/__init__.py````python```##8-10.`backend/app/api/health.py````pythonimportredisfromfastapiimportAPIRouterfromfastapi.responsesimportJSONResponsefromsqlalchemyimporttextfromapp.core.configimportget_settingsfromapp.db.sessionimportSessionLocalrouter=APIRouter(tags=["health"])settings=get_settings()#Redis接続クライアントredis_client=redis.Redis.from_url(settings.redis_url,decode_responses=True,)defrun_health_check()->tuple[dict,bool]:"""PostgreSQLとRedisの疎通を確認します。返り値:payload:healthチェック結果healthy:全体としてhealthyかどうかならTrue"""payload:dict={"status":"ok","app":settings.app_name,"env":settings.app_env,"database":"ok","redis":"ok",}healthy=True#PostgreSQLチェックdb=SessionLocal()try:db.execute(text("SELECT1"))exceptException:payload["status"]="degraded"payload["database"]="error"healthy=Falsefinally:db.close()#Redisチェックtry:redis_client.ping()exceptException:payload["status"]="degraded"payload["redis"]="error"healthy=Falsereturnpayload,healthy@router.get("/health")defhealth():"""/api/v1/healthAPIドキュメント用ヘルスチェック。"""payload,healthy=run_health_check()ifnothealthy:returnJSONResponse(status_code=503,content=payload)returnpayload```##8-11.`backend/app/main.py````pythonimportloggingfromfastapiimportFastAPIfromfastapi.middleware.corsimportCORSMiddlewarefromfastapi.responsesimportJSONResponsefromapp.api.healthimportrouterashealth_router,run_health_checkfromapp.core.configimportget_settingssettings=get_settings()#ログレベルを設定logging.basicConfig(level=settings.log_level.upper())app=FastAPI(title=settings.app_name,description="Next.js+FastAPI+PostgreSQL+Redis開発環境API",version="0.1.0",debug=settings.app_debug,openapi_url=f"{settings.api_v1_prefix}/openapi.json",docs_url="/docs",redoc_url="/redoc",)#CORS設定#フロントエンドhttp://localhost:3000からFastAPIhttp://localhost:8000を呼ぶため必要app.add_middleware(CORSMiddleware,allow_origins=settings.cors_origin_list,allow_credentials=True,allow_methods=["*"],allow_headers=["*"],)#/api/v1/healthを登録app.include_router(health_router,prefix=settings.api_v1_prefix)@app.get("/health",include_in_schema=False)defhealth():"""DockerComposeのhealthcheck用エンドポイント。PostgreSQLまたはRedisが接続できない場合は503を返します。"""payload,healthy=run_health_check()returnJSONResponse(status_code=200ifhealthyelse503,content=payload,)@app.get("/",include_in_schema=False)defroot():"""ルートエンドポイント。"""return{"message":f"{settings.app_name}isrunning","docs":"/docs","health":"/health",}```---#9.ホットリロードの設定##9-1.Next.jsのホットリロード`docker-compose.yml`のfrontendに以下の設定があります。```yamlvolumes:-./frontend:/app-frontend_node_modules:/app/node_modules-frontend_next_cache:/app/.next```###仕組み1.`./frontend:/app`ホスト側で`frontend/app/page.tsx`などを編集すると、コンテナ内の`/app`に反映されます。2.`frontend_node_modules:/app/node_modules``node_modules`はコンテナ内で`npmci`/`npminstall`済みなので、ホスト側の`node_modules`で上書きされないようにnamedvolumeで隔離します。3.`frontend_next_cache:/app/.next`Next.jsのキャッシュをコンテナ用volumeに置き、ホスト側に`.next`を生成しないようにします。4.`CMD["npm","run","dev"]``nextdev`が起動することでホットリロードが有効になります。###確認方法`frontend/app/page.tsx`を編集し、ブラウザを更新せずに反映されるか確認します。---##9-2.FastAPIのホットリロード`docker-compose.yml`のbackendに以下の設定があります。```yamlvolumes:-./backend:/app````backend/Dockerfile`には以下があります。```dockerfileCMD["uvicorn","app.main:app","--host","0.0.0.0","--port","8000","--reload","--reload-dir","app"]```###仕組み1.`./backend:/app`ホスト側で`backend/app/main.py`などを編集すると、コンテナ内の`/app`に反映されます。2.`uvicorn--reload`Pythonファイルの変更を検知してFastAPIアプリケーションを再読み込みします。3.`--reload-dirapp`変更監視を`app`ディレクトリに限定し、不要なファイル変更によるリロードを防ぎます。4.`uvicorn[standard]``watchfiles`を含むため、効率的なファイル変更監視が利用できます。###確認方法`backend/app/main.py`のルートエンドポイントを変更して保存すると、FastAPIが自動再起動されます。---##9-3.依存関係を変更した場合ソースコード変更と依存関係変更は異なります。###Next.jsの依存関係を変更した場合例:```bashcdfrontendnpminstallsome-package```この場合は、コンテナ内の`node_modules`も更新が必要です。```bashdockercomposeexecfrontendnpminstalldockercomposerestartfrontend````package-lock.json`を使っている場合は:```bashdockercomposeexecfrontendnpmcidockercomposerestartfrontend```###FastAPIの依存関係を変更した場合`backend/requirements.txt`を変更した場合は、イメージを再ビルドします。```bashdockercomposeup--build```---#10.環境変数の管理方法##10-1.環境変数の役割この構成では、環境変数を以下の3層で扱います。|層|ファイル/設定|役割||---|---|---||ホスト/Compose変数展開|ルート`.env`|DockerCompose内の`${VAR}`を展開するための値||コンテナ環境変数|`docker-compose.yml`の`environment`|実際にコンテナ内で利用される環境変数||アプリ設定|FastAPIの`Settings`/Next.jsの`NEXT_PUBLIC_*`|アプリが読む設定|---##10-2.ルートの`.env``docker-compose.yml`では以下のように書かれています。```yamlNEXT_PUBLIC_API_BASE_URL:${NEXT_PUBLIC_API_BASE_URL:-http://localhost:8000}```この場合、ルート`.env`の`NEXT_PUBLIC_API_BASE_URL`が読み込まれます。存在しなければ、`http://localhost:8000`がデフォルトになります。重要な点:-ルートの`.env`は、DockerComposeが`dockercomposeup`する際に読みます。-ルートの`.env`が自動的に全コンテナに渡されるわけではありません。-`docker-compose.yml`の`environment`に書いてあるものだけがコンテナに渡されます。この手順では、最小限必要な変数だけコンテナに渡すようにしています。そのため、PostgreSQLのパスワードなどがフロントエンドやバックエンドすべてに入るのを避けられます。---##10-3.Frontendの環境変数Next.jsでは`NEXT_PUBLIC_`で始まる環境変数だけがブラウザ側から利用できます。```envNEXT_PUBLIC_API_BASE_URL=http://localhost:8000```この構成では、ブラウザから直接`http://localhost:8000/health`を呼び出すため、`localhost`を使用します。注意:-`NEXT_PUBLIC_`付き変数はブラウザに公開されます。-秘密情報を入れるのは避けてください。-例:APIKey、JWTシークレット、DBパスワードなどは入れない---##10-4.Backendの環境変数FastAPIでは`app/core/config.py`の`Settings`が環境変数を読み込みます。```pythonclassSettings(BaseSettings):database_url:strredis_url:strcors_origins:str````docker-compose.yml`では以下のように渡しています。```yamlenvironment:DATABASE_URL:postgresql+psycopg2://${POSTGRES_USER:-app}:${POSTGRES_PASSWORD:-app}@db:5432/${POSTGRES_DB:-app}REDIS_URL:redis://redis:6379/0CORS_ORIGINS:${CORS_ORIGINS:-http://localhost:3000}```###Docker内部のホスト名DockerComposeのネットワーク内では、ホスト名はservice名になります。|外部から見たホスト名|DockerCompose内部のホスト名||---|---||localhost|frontend/backend/db/redis||db|PostgreSQLコンテナ||redis|Redisコンテナ||backend|FastAPIコンテナ|そのため:-バックエンドからDBには`db`-バックエンドからRedisには`redis`-フロントエンドからバックエンドには、ブラウザ経由なら`localhost`-フロントエンドからコンテナ内でバックエンドを呼ぶなら`backend`という使い分けになります。---##10-5.環境変数を変更した後ルート`.env`を変更した場合は、コンテナを再作成してください。```bashdockercomposeup-d--force-recreate```ビルド関係の設定、例えば`docker-compose.yml`のimageやbuildを変更した場合は:```bashdockercomposeup--build```---#11.起動方法##11-1.`.env`を作成```bashcp.env.example.env```##11-2.ビルドして起動```bashdockercomposeup--build```初回はNext.jsとFastAPIのイメージがビルドされるため、時間がかかります。正常に起動すると、以下のようなログが見られます。Next.js:```text▲Next.js14.2.15-Local:http://localhost:3000```FastAPI:```textINFO:Startedserverprocess[...]INFO:Uvicornrunningonhttp://0.0.0.0:8000```---#12.動作確認##12-1.フロントエンドブラウザで以下を開きます。```texthttp://localhost:3000```FastAPIの`/health`結果が表示されます。---##12-2.FastAPIルート```texthttp://localhost:8000``````json{"message":"FastAPIBackendisrunning","docs":"/docs","health":"/health"}```---##12-3.FastAPIヘルスチェック```texthttp://localhost:8000/health```正常なら:```json{"status":"ok","app":"FastAPIBackend","env":"development","database":"ok","redis":"ok"}```PostgreSQLまたはRedisが接続できない場合は`503`が返ります。---##12-4.SwaggerUIFastAPIのAPIドキュメント:```texthttp://localhost:8000/docs````/api/v1/health`が表示されるはずです。---##12-5.PostgreSQLに接続```bashdockercomposeexecdbpsql-Uapp-dapp```psql内で:```sqlSELECTcurrent_user,current_database();\dt```---##12-6.Redisに接続```bashdockercomposeexecredisredis-cliping```正常なら:```textPONG```---##12-7.コンテナ状態確認```bashdockercomposeps````frontend`,`backend`,`db`,`redis`がhealthyな状態になれば成功です。---##12-8.ログ確認```bashdockercomposelogs-ffrontendbackend```Ctrl+Cでログ追跡を停止できます。---#13.停止方法##13-1.コンテナを停止```bashdockercomposedown```データvolumeは残ります。PostgreSQLとRedisのデータは保持されます。---##13-2.データも削除して停止```bashdockercomposedown-v```警告:-PostgreSQLのデータ-Redisのデータ-Frontendの`node_modules`volume-Frontendの`.next`volumeこれらが削除されます。---#14.よくある問題と対処法##14-1.ポートが既に使用中例:```textError:Portsarenotavailable:bindingforhostport3000failed:addressalreadyinuse```###対処法使用しているポートを止めるか、`docker-compose.yml`のホスト側ポートを変更します。例:```yamlports:-"3001:3000"```その場合、フロントエンドURLは:```texthttp://localhost:3001```になります。---##14-2.Next.jsのホットリロードが効かない###確認事項1.`docker-compose.yml`に以下があるか```yamlvolumes:-./frontend:/app-frontend_node_modules:/app/node_modules```2.`package.json`に`dev`スクリプトがあるか```json"dev":"nextdev-p3000-H0.0.0.0"```3.コンテナが起動しているか```bashdockercomposelogs-ffrontend```4.`.next`キャッシュが古い場合があるその場合は:```bashdockercomposedowndockervolumerm$(dockervolumels-q|grepfrontend_next_cache)dockercomposeup--build```注意:特定volume名が異なる場合は`dockervolumels`で確認してください。---##14-3.FastAPIのホットリロードが効かない###確認事項1.`requirements.txt`に`uvicorn[standard]`があるか```textuvicorn[standard]>=0.30,<1.0```2.`Dockerfile`に`--reload`があるか```dockerfile--reload```3.`docker-compose.yml`に以下があるか```yamlvolumes:-./backend:/app```4.編集しているファイルが`app`ディレクトリ配下かこの構成では`--reload-dirapp`を使用しているため、`backend/app`配下の変更を対象にしています。---##14-4.フロントエンドからAPI呼び出しでCORSエラーが出るブラウザの開発者ツールで:```textAccesstofetchat'http://localhost:8000/health'fromorigin'http://localhost:3000'hasbeenblockedbyCORSpolicy```が出る場合、`.env`の`CORS_ORIGINS`を確認します。```envCORS_ORIGINS=http://localhost:3000```変更後は:```bashdockercomposeup-d--force-recreate```---##14-5.環境変数を変更しても反映されない`docker-compose.yml`の`environment`を読み込んでいるコンテナを再作成します。```bashdockercomposeup-d--force-recreate```---##14-6.PostgreSQLパスワードに特殊文字を含む`DATABASE_URL`には`@`,`:`,`/`,`#`などが含まれるとURL解釈が破れることがあります。例:```textpostgresql+psycopg2://user:pass@word@db:5432/app```###対処法-特殊文字をURLエンコードする-ローカル開発では特殊文字を避け、例えば`app`などの単純なパスワードを使う---##14-7.Redisに接続できないまずhealthcheckを確認します。```texthttp://localhost:8000/health````redis:error`なら:```bashdockercomposeexecredisredis-cliping```で`PONG`が返るか確認します。この手順書では:```yamlcommand:["redis-server","--appendonly","yes","--protected-mode","no"]```と設定しています。ローカル開発用にパスワードなし・保護モード無効になっています。公開環境では:-`requirepass`-適切なネットワーク制限-必要ならTLSを設定してください。---#15.本番環境や共有環境での注意この手順書はローカル開発用です。以下はローカル開発向けに簡略化しています。-PostgreSQLとRedisのパスワードが弱い-Redisのprotectedmodeが無効-ポートがホストに公開されている-CORSがlocalhost向け本番環境やチームで共有する環境では、以下を強化してください。-強いパスワード-Redis認証-最小限のポート公開-CORSの厳格化-秘密情報はsecrets管理-`.env`のコミット禁止-ログの敏感情報除去-HTTPS/reverseproxy-適切なリソース制限---#16.最小実行コマンドまとめ##初回構築```bashcp.env.example.envdockercomposeup--build```##起動状態確認```bashdockercomposeps```##ログ確認```bashdockercomposelogs-ffrontendbackend```##停止```bashdockercomposedown```##データ削除を含む停止```bashdockercomposedown-v```##確認URL```texthttp://localhost:3000http://localhost:8000http://localhost:8000/docshttp://localhost:8000/health```

#DockerComposeによるローカル開発環境構築手順以下の構成をDockerComposeで起動します。|サービス|役割|ホストポート||---|---|---:||frontend|Next.js|3000||backend|FastAPI|8000||db|PostgreSQL|5432||redis|Redis|6379|##1.ディレクトリ構成```textproject-root/├──docker-compose.yml├──.env├──.env.example│├──frontend/│├──Dockerfile│├──package.json│├──package-lock.json│└──src/│├──backend/│├──Dockerfile│├──requirements.txt│└──app/│└──main.py│└──docker/├──postgres/│└──Dockerfile└──redis/└──Dockerfile```---#2.環境変数の管理##`.env.example````dotenv#PostgreSQLPOSTGRES_USER=appPOSTGRES_PASSWORD=app_passwordPOSTGRES_DB=app_db#BackendからPostgreSQLへ接続するためのURL#`db`はDockerCompose上のサービス名DATABASE_URL=postgresql+psycopg://app:app_password@db:5432/app_db#BackendからRedisへ接続するためのURL#`redis`はDockerCompose上のサービス名REDIS_URL=redis://redis:6379/0#FastAPIBACKEND_ENV=development#Next.js#ブラウザからアクセスするURLなのでlocalhostを使用するNEXT_PUBLIC_API_URL=http://localhost:8000````.env.example`をコピーして`.env`を作成します。```bashcp.env.example.env````.env`にはパスワードなどの環境依存値を設定します。通常、`.env`はGitへコミットしません。##`.gitignore````gitignore.envfrontend/node_modulesfrontend/.nextbackend/__pycache__backend/.pytest_cache*.pyc```>DockerComposeはプロジェクトルートの`.env`を自動的に読み込みます。---#3.完全な`docker-compose.yml````yamlservices:#==========================================#Next.jsフロントエンド#==========================================frontend:build:#Next.jsプロジェクトのディレクトリcontext:./frontenddockerfile:Dockerfilecontainer_name:local-frontend#Next.jsの開発サーバーcommand:npmrundev----hostname0.0.0.0ports:#ホスト:コンテナ-"3000:3000"environment:#ブラウザからアクセスするFastAPIのURL#NEXT_PUBLIC_prefixを付けるとNext.jsから公開されるNEXT_PUBLIC_API_URL:${NEXT_PUBLIC_API_URL:-http://localhost:8000}#Next.jsのファイル監視を安定させるための設定#DockerDesktopやWindows/macOS環境で有効WATCHPACK_POLLING:"true"#Node.jsの環境NODE_ENV:developmentvolumes:#ソースコードをコンテナへマウントする#ホスト側でファイルを変更するとNext.jsが検知する-./frontend:/app#ホスト側のnode_modulesでコンテナ内の依存関係を上書きしない#anonymousvolumeとしてコンテナ内のnode_modulesを保持する-frontend_node_modules:/app/node_modules#Next.jsのビルドキャッシュをコンテナ内に保持する-frontend_next:/app/.nextdepends_on:#Backendが起動してからFrontendを起動するbackend:condition:service_startedstdin_open:truetty:true#==========================================#FastAPIバックエンド#==========================================backend:build:context:./backenddockerfile:Dockerfilecontainer_name:local-backend#Uvicornのホットリロードを有効にするcommand:>uvicornapp.main:app--host0.0.0.0--port8000--reloadports:-"8000:8000"environment:#FastAPIの実行環境BACKEND_ENV:${BACKEND_ENV:-development}#PostgreSQL接続先DATABASE_URL:${DATABASE_URL}#Redis接続先REDIS_URL:${REDIS_URL}#Pythonの標準出力をバッファリングしないPYTHONUNBUFFERED:"1"volumes:#Pythonソースコードをコンテナへマウントする#--reloadと組み合わせてホットリロードを実現する-./backend:/appdepends_on:db:#PostgreSQLのヘルスチェックが成功してから起動するcondition:service_healthyredis:#Redisのヘルスチェックが成功してから起動するcondition:service_healthy#==========================================#PostgreSQL#==========================================db:build:context:./docker/postgresdockerfile:Dockerfilecontainer_name:local-postgresports:-"5432:5432"environment:#PostgreSQLの初期ユーザーPOSTGRES_USER:${POSTGRES_USER:-app}#PostgreSQLの初期パスワードPOSTGRES_PASSWORD:${POSTGRES_PASSWORD:-app_password}#PostgreSQLの初期データベースPOSTGRES_DB:${POSTGRES_DB:-app_db}#PostgreSQLコンテナのタイムゾーンTZ:Asia/Tokyovolumes:#PostgreSQLのデータを永続化する#コンテナを削除してもデータを保持できる-postgres_data:/var/lib/postgresql/datahealthcheck:#PostgreSQLが接続可能か確認するtest:["CMD-SHELL","pg_isready-U${POSTGRES_USER:-app}-d${POSTGRES_DB:-app_db}"]interval:5stimeout:5sretries:10start_period:10s#==========================================#Redis#==========================================redis:build:context:./docker/redisdockerfile:Dockerfilecontainer_name:local-redisports:-"6379:6379"command:#開発環境では永続化を無効にして簡単に利用する#Redisのデータも保持したい場合は--appendonlyyesに変更する-redis-server---appendonly-"no"volumes:#Redisのデータを保持したい場合は以下を有効にする#-redis_data:/data-/tmphealthcheck:#Redisへの疎通確認test:["CMD","redis-cli","ping"]interval:5stimeout:3sretries:10start_period:5s#==========================================#名前付きボリューム#==========================================volumes:#PostgreSQLのデータ保存領域postgres_data:#Frontendのnode_modules保持領域frontend_node_modules:#Next.jsのビルドキャッシュ保持領域frontend_next:#Redisを永続化する場合に使用#redis_data:```---#4.Next.jsのDockerfile##`frontend/Dockerfile````dockerfile#Node.jsの軽量イメージを使用するFROMnode:20-alpine#コンテナ内の作業ディレクトリWORKDIR/app#package.jsonとlockファイルを先にコピーする#Dockerのレイヤーキャッシュを利用するため、#ソースコード変更時にnpminstallを毎回実行しないCOPYpackage*.json./#npmciはpackage-lock.jsonに従って依存関係をインストールするRUNnpmci#ソースコードをコピーする#実際の開発時はdocker-compose.ymlのvolumeで上書きされるCOPY..#Next.jsが待ち受けるポートEXPOSE3000#docker-compose.yml側のcommandで開発サーバーを起動するCMD["npm","run","dev","--","--hostname","0.0.0.0"]```##`frontend/package.json`の例```json{"name":"frontend","version":"1.0.0","private":true,"scripts":{"dev":"nextdev","build":"nextbuild","start":"nextstart","lint":"nextlint"},"dependencies":{"next":"^14.2.0","react":"^18.3.0","react-dom":"^18.3.0"}}```Next.jsプロジェクトが未作成の場合は、以下のように作成できます。```bashnpxcreate-next-app@latestfrontend```---#5.FastAPIのDockerfile##`backend/Dockerfile````dockerfile#Pythonの軽量イメージを使用するFROMpython:3.12-slim#Pythonの設定#.pycファイルを作成しないENVPYTHONDONTWRITEBYTECODE=1#標準出力を即時に表示するENVPYTHONUNBUFFERED=1#コンテナ内の作業ディレクトリWORKDIR/app#Python依存関係を先にコピーするCOPYrequirements.txt.#PythonパッケージをインストールするRUNpipinstall--no-cache-dir-rrequirements.txt#アプリケーションコードをコピーする#実際の開発時はdocker-compose.ymlのvolumeで上書きされるCOPY..#FastAPIが待ち受けるポートEXPOSE8000#--reloadはdocker-compose.yml側のcommandでも指定しているCMD["uvicorn","app.main:app","--host","0.0.0.0","--port","8000","--reload"]```##`backend/requirements.txt````textfastapi==0.115.0uvicorn[standard]==0.30.6#PostgreSQL接続用psycopg[binary]==3.2.1#ORMを使用する場合sqlalchemy==2.0.35#Redis接続用redis==5.0.8#環境変数を読み込む場合python-dotenv==1.0.1```##`backend/app/main.py````pythonimportosfromfastapiimportFastAPIapp=FastAPI(title="LocalDevelopmentAPI",version="1.0.0",)@app.get("/")defread_root():return{"message":"FastAPIisrunning","environment":os.getenv("BACKEND_ENV","unknown"),}@app.get("/health")defhealth_check():return{"status":"ok"}```FastAPIには、以下のURLでアクセスできます。```texthttp://localhost:8000http://localhost:8000/docshttp://localhost:8000/health```---#6.PostgreSQLのDockerfile##`docker/postgres/Dockerfile````dockerfile#PostgreSQL公式イメージを使用するFROMpostgres:16-alpine#コンテナの説明用ラベルLABELdescription="PostgreSQLforlocaldevelopment"#PostgreSQLのデフォルトポートEXPOSE5432```PostgreSQLのデータは、Composeの名前付きボリュームである`postgres_data`に保存されます。データを完全に削除したい場合は、以下を実行します。```bashdockercomposedown-v```>`-v`を付けるとPostgreSQLのデータも削除されるため注意してください。---#7.RedisのDockerfile##`docker/redis/Dockerfile````dockerfile#Redis公式イメージを使用するFROMredis:7-alpine#コンテナの説明用ラベルLABELdescription="Redisforlocaldevelopment"#RedisのデフォルトポートEXPOSE6379#docker-compose.yml側でredis-serverを起動するCMD["redis-server"]```今回の設定では、開発環境としてRedisの永続化を無効にしています。Redisのデータを保持したい場合は、`docker-compose.yml`を以下のように変更します。```yamlredis:command:-redis-server---appendonly-"yes"volumes:-redis_data:/datavolumes:redis_data:```---#8.起動方法プロジェクトルートで以下を実行します。```bashdockercomposeup--build```バックグラウンドで起動する場合は、以下を実行します。```bashdockercomposeup-d--build```起動状態を確認します。```bashdockercomposeps```ログを確認します。```bash#全サービスのログdockercomposelogs-f#Frontendのみdockercomposelogs-ffrontend#Backendのみdockercomposelogs-fbackend```各サービスへのアクセス先は次のとおりです。```textNext.js:http://localhost:3000FastAPI:http://localhost:8000SwaggerUI:http://localhost:8000/docsPostgreSQL:localhost:5432Redis:localhost:6379```---#9.ホットリロードの仕組み##Next.js```yamlvolumes:-./frontend:/app-frontend_node_modules:/app/node_modules-frontend_next:/app/.next``````yamlcommand:npmrundev----hostname0.0.0.0```ホスト側の`frontend`ディレクトリをコンテナの`/app`へマウントし、Next.jsの開発サーバーを起動しています。`WATCHPACK_POLLING=true`を設定しているため、DockerDesktopやWindows/macOS環境でもファイル変更を検知しやすくなります。##FastAPI```yamlvolumes:-./backend:/app``````yamlcommand:>uvicornapp.main:app--host0.0.0.0--port8000--reload````uvicorn`の`--reload`オプションにより、Pythonファイルの変更時にFastAPIが自動的に再起動します。---#10.コンテナの停止・削除停止する場合：```bashdockercomposestop```コンテナ、ネットワークを削除する場合：```bashdockercomposedown```イメージも再作成したい場合：```bashdockercomposedowndockercomposebuild--no-cachedockercomposeup```PostgreSQLのデータを含めて完全に削除する場合：```bashdockercomposedown-v```---#11.コンテナ間通信に関する注意点コンテナ間の接続では、`localhost`ではなくComposeのサービス名を使用します。```textBackend→PostgreSQLdb:5432Backend→Redisredis:6379```そのため、Backendコンテナ内の環境変数は次のようになります。```dotenvDATABASE_URL=postgresql+psycopg://app:app_password@db:5432/app_dbREDIS_URL=redis://redis:6379/0```一方、ブラウザからFrontend経由でBackendへアクセスする場合は、ブラウザから到達可能な`localhost`を使用します。```dotenvNEXT_PUBLIC_API_URL=http://localhost:8000```このように、以下の2種類のURLを使い分けます。|接続元|接続先URL||---|---||Backendコンテナ|`db:5432`||Backendコンテナ|`redis:6379`||ホストのブラウザ|`localhost:3000`||ホストのブラウザ|`localhost:8000`|

以下は、**ソースコードを変更すると自動反映されるローカル開発環境**の構築例です。-Next.js：`http://localhost:3000`-FastAPI：`http://localhost:8000`-PostgreSQL：`localhost:5432`-Redis：`localhost:6379`DBとRedisのデータはDockerの名前付きボリュームに保存します。公開ポートは`127.0.0.1`に限定し、同じネットワークの別端末からアクセスされない設定にします。>この構成は開発専用です。本番環境では開発サーバーやソースコードのbindmountを使わず、シークレット管理なども別途設計してください。---##1.前提条件とディレクトリ構成DockerEngineとDockerComposev2を用意してください。DockerDesktopでも構いません。```bashdocker--versiondockercomposeversion```以下の構成でファイルを作成します。```textmy-app/├──docker-compose.yml├──.env.example├──.env#.env.exampleから作成。Git管理しない├──.gitignore├──frontend/│├──Dockerfile│├──.dockerignore│├──package.json│├──package-lock.json#後述のコマンドで生成│└──app/│├──layout.js│└──page.js├──backend/│├──Dockerfile│├──.dockerignore│├──requirements.txt│└──app/│└──main.py├──postgres/│└──Dockerfile└──redis/└──Dockerfile```以降のコマンドは、特記がなければ`my-app/`で実行します。---##2.環境変数を定義する###`.env.example````dotenv#ホスト側に公開するポートFRONTEND_PORT=3000BACKEND_PORT=8000POSTGRES_PORT=5432REDIS_PORT=6379#PostgreSQLの初期ユーザー・データベースPOSTGRES_DB=appPOSTGRES_USER=appPOSTGRES_PASSWORD=local_postgres_password#Redisの認証パスワードREDIS_PASSWORD=local_redis_password#ブラウザーからアクセスするAPIのURL#BACKEND_PORTを変更した場合は、こちらも合わせて変更するNEXT_PUBLIC_API_BASE_URL=http://localhost:8000#FastAPIが許可するブラウザーのオリジン。複数指定はカンマ区切り#FRONTEND_PORTを変更した場合は、こちらも合わせて変更するCORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000```コピーして、必要に応じて値を変更します。```bashcp.env.example.env```###`.gitignore````gitignore#実際の認証情報はコミットしない.env.env.*!.env.example#フロントエンドの生成物frontend/node_modules/frontend/.next/#Pythonの生成物・仮想環境__pycache__/*.py[cod].venv/```###環境変数管理のポイント-ルートの`.env`は、Composeの`${変数名}`を置換するために使います。-`.env`の全項目がコンテナへ自動的に渡されるわけではありません。今回は`environment`で必要な値だけ渡します。-`.env.example`はGit管理し、実際の`.env`はGit管理しません。-`NEXT_PUBLIC_`で始まる変数はブラウザーに公開されます。**パスワードや秘密鍵を設定しないでください。**-コンテナの環境変数はDockerの管理権限があれば参照できます。この方式は開発用途です。---##3.完全な`docker-compose.yml````yaml#DockerComposev2では、トップレベルのversion指定は不要services:frontend:build:#frontend/Dockerfileを使ってビルドするcontext:./frontenddockerfile:Dockerfileports:#ホストのループバックアドレスに限定して公開する#ホスト側ポート:コンテナ側ポート-"127.0.0.1:${FRONTEND_PORT:-3000}:3000"environment:NODE_ENV:developmentNEXT_TELEMETRY_DISABLED:"1"#ブラウザーで実行するコードが参照するAPIURLNEXT_PUBLIC_API_BASE_URL:"${NEXT_PUBLIC_API_BASE_URL:?SetNEXT_PUBLIC_API_BASE_URLin.env}"#Next.jsのServerComponentなど、コンテナ内からAPIを呼ぶ場合のURL#このサンプルのページでは使用しないAPI_INTERNAL_URL:"http://backend:8000"#DockerDesktopなどでもファイル変更を検知しやすくする#この構成ではNext.jsをWebpackモードで起動するWATCHPACK_POLLING:"true"volumes:#ホストのソースコードをコンテナへ即時反映する-./frontend:/app#ホスト側のnode_modulesとコンテナ側を分離する-frontend_node_modules:/app/node_modules#Next.jsの生成物もコンテナ用ボリュームに分離する-frontend_next:/app/.next#明示的にWebpackを使用し、0.0.0.0で待ち受けるcommand:npmrundev----hostname0.0.0.0--port3000--webpack#Node.jsの子プロセス回収などを補助するinit:true#backendが起動する順番を制御する。APIの応答可能状態までは保証しないdepends_on:backend:condition:service_startedbackend:build:context:./backenddockerfile:Dockerfileports:-"127.0.0.1:${BACKEND_PORT:-8000}:8000"environment:#コンテナ間通信ではlocalhostではなくサービス名を使うPOSTGRES_HOST:postgresPOSTGRES_PORT:"5432"POSTGRES_DB:"${POSTGRES_DB:?SetPOSTGRES_DBin.env}"POSTGRES_USER:"${POSTGRES_USER:?SetPOSTGRES_USERin.env}"POSTGRES_PASSWORD:"${POSTGRES_PASSWORD:?SetPOSTGRES_PASSWORDin.env}"REDIS_HOST:redisREDIS_PORT:"6379"REDIS_PASSWORD:"${REDIS_PASSWORD:?SetREDIS_PASSWORDin.env}"CORS_ORIGINS:"${CORS_ORIGINS:?SetCORS_ORIGINSin.env}"#bindmount上の変更をポーリングで検知するWATCHFILES_FORCE_POLLING:"true"volumes:#Pythonコードの変更を即時反映する-./backend:/app#--reloadでPythonファイル変更時にAPIプロセスを再起動するcommand:-uvicorn-app.main:app---host-0.0.0.0---port-"8000"---reload---reload-dir-/app/appinit:true#DBとRedisが接続可能になってからAPIを起動するdepends_on:postgres:condition:service_healthyredis:condition:service_healthypostgres:build:context:./postgresdockerfile:Dockerfileports:-"127.0.0.1:${POSTGRES_PORT:-5432}:5432"environment:#データディレクトリが空の場合、公式イメージが初期化に使用するPOSTGRES_DB:"${POSTGRES_DB:?SetPOSTGRES_DBin.env}"POSTGRES_USER:"${POSTGRES_USER:?SetPOSTGRES_USERin.env}"POSTGRES_PASSWORD:"${POSTGRES_PASSWORD:?SetPOSTGRES_PASSWORDin.env}"volumes:#PostgreSQL17のデータ保存先-postgres_data:/var/lib/postgresql/datahealthcheck:#$$はCompose側での変数展開を避け、コンテナ内で展開するための記法#pg_isreadyはサーバーが接続を受け付ける状態かを確認するtest:-CMD-SHELL-'pg_isready-U"$$POSTGRES_USER"-d"$$POSTGRES_DB"'interval:5stimeout:5sretries:10start_period:10sredis:build:context:./redisdockerfile:Dockerfileports:-"127.0.0.1:${REDIS_PORT:-6379}:6379"environment:REDIS_PASSWORD:"${REDIS_PASSWORD:?SetREDIS_PASSWORDin.env}"#AOFでデータを永続化し、開発環境でもパスワード認証を有効化する#公式entrypointへredis-serverを渡し、公式イメージの初期処理を維持するcommand:-sh--c-'exec/usr/local/bin/docker-entrypoint.shredis-server--appendonlyyes--requirepass"$$REDIS_PASSWORD"'volumes:-redis_data:/datahealthcheck:#パスワードを使ってPINGし、PONGが返ることを確認するtest:-CMD-SHELL-'REDISCLI_AUTH="$$REDIS_PASSWORD"redis-cliping|grep-qPONG'interval:5stimeout:5sretries:10start_period:5s#名前付きボリューム。通常のdockercomposedownでは削除されないvolumes:frontend_node_modules:frontend_next:postgres_data:redis_data:```>ホスト側のポートを変更しても、コンテナ間通信では`backend:8000`、`postgres:5432`、`redis:6379`を使います。---##4.各サービスのDockerfile###`frontend/Dockerfile````dockerfile#Next.js16を実行できるNode.js22を使用FROMnode:22-alpine#以降の作業ディレクトリWORKDIR/app#開発依存も含めてインストールするENVNODE_ENV=developmentENVNEXT_TELEMETRY_DISABLED=1#依存定義だけを先にコピーし、Dockerのキャッシュを活用するCOPYpackage.jsonpackage-lock.json./#lockファイルに従って依存関係をインストールするRUNnpmci#アプリケーションコードをコピーする#開発時はComposeのbindmountでホスト側コードを重ねるCOPY..#ドキュメント用途。ホストへの公開はComposeのportsで行うEXPOSE3000#Compose側でも同じ起動コマンドを指定するCMD["npm","run","dev","--","--hostname","0.0.0.0","--port","3000","--webpack"]```###`backend/Dockerfile````dockerfile#psycopgのバイナリパッケージを扱いやすいDebian系イメージを使用FROMpython:3.12-slimWORKDIR/app#.pycファイルを作らず、ログをバッファリングせずに出力するENVPYTHONDONTWRITEBYTECODE=1ENVPYTHONUNBUFFERED=1#依存関係を先にコピーしてキャッシュを活用するCOPYrequirements.txt./#開発用依存関係をインストールするRUNpipinstall--no-cache-dir-rrequirements.txtCOPY..EXPOSE8000#開発専用。コード変更時に自動再起動するCMD["uvicorn","app.main:app","--host","0.0.0.0","--port","8000","--reload"]```###`postgres/Dockerfile````dockerfile#データ保存先はPostgreSQL17向けにCompose側で設定するFROMpostgres:17-alpine#起動処理と初期化処理は公式イメージのものを使用するEXPOSE5432```###`redis/Dockerfile````dockerfileFROMredis:7-alpine#起動オプション、認証、永続化はCompose側で設定するEXPOSE6379```PostgreSQLとRedisはカスタマイズしない場合、Dockerfileを作らずComposeで`image:`を指定しても構いません。ここでは各サービスのDockerfileを用意しています。###`frontend/.dockerignore````dockerignore#ホスト側の依存・生成物をイメージへコピーしないnode_modules.next.git#認証情報をイメージへ入れない.env.env.*```###`backend/.dockerignore````dockerignore__pycache__*.py[cod].venv.git.env.env.*```---##5.最小限のNext.jsアプリを作成する###`frontend/package.json`JSONにはコメントを書けないため、項目の説明はファイル外に記載します。```json{"name":"local-next-fastapi","version":"1.0.0","private":true,"scripts":{"dev":"nextdev","build":"nextbuild","start":"nextstart"},"dependencies":{"next":"^16.0.0","react":"^19.2.0","react-dom":"^19.2.0"}}```-`private`：誤ってnpmへ公開することを防止します。-`dev`：ホットリロード付きの開発サーバーです。-`build`・`start`：本番ビルド用です。今回のComposeでは使用しません。-実際にインストールするバージョンは`package-lock.json`で固定します。###`frontend/app/layout.js````javascript//AppRouterで必須のルートレイアウトexportdefaultfunctionRootLayout({children}){return(<htmllang="ja"><body>{children}</body></html>);}```###`frontend/app/page.js````javascript"useclient";import{useEffect,useState}from"react";exportdefaultfunctionHome(){const[result,setResult]=useState("接続確認中...");useEffect(()=>{//このfetchはブラウザーで実行されるためlocalhostのURLを使うconstapiUrl=process.env.NEXT_PUBLIC_API_BASE_URL;fetch(`${apiUrl}/health`).then((response)=>{if(!response.ok){thrownewError(`HTTP${response.status}`);}returnresponse.json();}).then((data)=>setResult(JSON.stringify(data,null,2))).catch((error)=>setResult(`接続エラー:${error.message}`));},[]);return(<main><h1>Next.js+FastAPI</h1><p>API・PostgreSQL・Redisの接続結果</p><pre>{result}</pre></main>);}```###`package-lock.json`の生成ホストにNode.jsがある場合：```bashcdfrontendnpminstall--package-lock-onlycd..```ホストにNode.jsがない場合、macOS／Linux／WSLでは次のコマンドでも生成できます。```bashdockerrun--rm\--user"$(id-u):$(id-g)"\-enpm_config_cache=/tmp/npm-cache\-v"$PWD/frontend:/app"\-w/app\node:22-alpine\npminstall--package-lock-only```生成した`package-lock.json`はGit管理してください。---##6.FastAPIアプリを作成する###`backend/requirements.txt````text#APIフレームワークfastapi>=0.115,<1.0#standardにはホットリロード用のwatchfilesなどが含まれるuvicorn[standard]>=0.30,<1.0#PostgreSQLドライバー。ローカル開発を簡単にするためbinary版を使用psycopg[binary]>=3.2,<4.0#Redisクライアントredis>=5.0,<7.0```この例では互換範囲を指定しています。チームで完全に同じ依存を再現する場合は、検証済みバージョンへの固定やロックファイルの導入を推奨します。###`backend/app/main.py````pythonimportosimportpsycopgfromfastapiimportFastAPI,HTTPExceptionfromfastapi.middleware.corsimportCORSMiddlewarefromredisimportRedisfromredis.exceptionsimportRedisErrorapp=FastAPI(title="LocalDevelopmentAPI")#ブラウザーのOriginを明示的に許可するorigins=[origin.strip()fororigininos.environ["CORS_ORIGINS"].split(",")iforigin.strip()]app.add_middleware(CORSMiddleware,allow_origins=origins,allow_credentials=False,allow_methods=["*"],allow_headers=["*"],)#Redisクライアントは内部でコネクションプールを利用するredis_client=Redis(host=os.environ["REDIS_HOST"],port=int(os.environ["REDIS_PORT"]),password=os.environ["REDIS_PASSWORD"],decode_responses=True,socket_connect_timeout=3,socket_timeout=3,)@app.get("/")defroot():return{"message":"HellofromFastAPI"}@app.get("/health")defhealth():#同期ドライバーを使うため通常のdefで定義する#FastAPIはこの処理をスレッドプールで実行するtry:#接続情報を個別に渡し、URL内のパスワードのエスケープを不要にするwithpsycopg.connect(host=os.environ["POSTGRES_HOST"],port=int(os.environ["POSTGRES_PORT"]),dbname=os.environ["POSTGRES_DB"],user=os.environ["POSTGRES_USER"],password=os.environ["POSTGRES_PASSWORD"],connect_timeout=3,)asconnection:withconnection.cursor()ascursor:cursor.execute("SELECT1")cursor.fetchone()redis_client.ping()except(psycopg.Error,RedisError)asexc:#クライアントへ接続情報などの詳細を返さないraiseHTTPException(status_code=503,detail="Databaseorcacheisunavailable",)fromexcreturn{"status":"ok","postgres":"ok","redis":"ok",}```このサンプルでは、接続確認のたびにPostgreSQLへ接続します。実際のアプリケーションでは接続プールやマイグレーションの導入も検討してください。---##7.ビルド・起動・動作確認###設定の検証```bashdockercomposeconfig--quiet```>`dockercomposeconfig`を`--quiet`なしで実行すると、展開済みのパスワードも表示されます。出力を共有する際は注意してください。###ビルドして起動```bashdockercomposeup--build-d```###状態とログの確認```bashdockercomposepsdockercomposelogs-ffrontendbackend```初回は依存インストールやNext.jsのコンパイルに時間がかかります。###ブラウザーから確認|対象|URL||---|---||Next.js|http://localhost:3000||FastAPI|http://localhost:8000||SwaggerUI|http://localhost:8000/docs||DB・Redis接続確認|http://localhost:8000/health|`/health`が以下を返せば、バックエンドからDBとRedisへ接続できています。```json{"status":"ok","postgres":"ok","redis":"ok"}```CLIでも確認できます。```bashcurlhttp://localhost:8000/health#PostgreSQLへ接続dockercomposeexecpostgressh-c\'psql-U"$POSTGRES_USER"-d"$POSTGRES_DB"'#Redisの認証付きPINGdockercomposeexecredissh-c\'REDISCLI_AUTH="$REDIS_PASSWORD"redis-cliping'```---##8.ホットリロードと変更時の操作###ソースコード変更|変更対象|動作||---|---||`frontend/app/page.js`など|Next.jsのFastRefreshで反映||`backend/app/main.py`など|UvicornがAPIプロセスを再起動|通常、ソースコードだけの変更ではイメージの再ビルドは不要です。ポーリングはDockerDesktopなどでの変更検知を安定させますが、CPU使用量が増えることがあります。ネイティブLinuxで問題なく検知できる場合は、ポーリング用環境変数を外しても構いません。###フロントエンドの依存追加```bash#ホストへbindmountされたpackage.jsonとlockファイルも更新されるdockercomposeexecfrontendnpminstallaxios#開発サーバーを再起動するdockercomposerestartfrontend```イメージ内の依存も更新しておく場合：```bashdockercomposebuildfrontend```別の開発者が更新した`package-lock.json`を取り込んだ場合は、名前付きボリューム内の依存を同期します。```bashdockercomposestopfrontenddockercomposerun--rm--no-depsfrontendnpmcidockercomposeup-d--buildfrontend```**イメージの再ビルドだけでは、既存の`frontend_node_modules`ボリュームの内容は更新されません。**###バックエンドの依存変更`requirements.txt`を編集して再ビルドします。```bashdockercomposeup-d--buildbackend```###`.env`変更環境変数の変更にはコンテナの再作成が必要です。```bashdockercomposeup-d--force-recreate````dockercomposerestart`だけでは新しい環境変数は反映されません。また、`POSTGRES_USER`・`POSTGRES_DB`・`POSTGRES_PASSWORD`は**データの初期作成時にだけ適用**されます。既存DBのユーザーやパスワードは、`.env`を変更しても更新されません。既存データを保持するなら、SQLで変更してください。---##9.停止と初期化###停止する：データは保持```bashdockercomposedown```###完全に初期化する：データを削除```bash#注意：PostgreSQL・Redisのデータと、フロントエンド用ボリュームを削除するdockercomposedown-vdockercomposeup--build-d````down-v`はDBデータも削除します。依存関係の更新だけを目的として実行しないでください。---##10.接続先を間違えないための一覧|接続元|接続先||---|---||ブラウザー→Next.js|`http://localhost:3000`||ブラウザー→FastAPI|`http://localhost:8000`||Next.jsコンテナ→FastAPI|`http://backend:8000`||FastAPIコンテナ→PostgreSQL|`postgres:5432`||FastAPIコンテナ→Redis|`redis:6379`||ホストのDBツール→PostgreSQL|`localhost:5432`||ホストのRedisツール→Redis|`localhost:6379`|Composeは同一ネットワーク上でサービス名を名前解決します。**コンテナ内の`localhost`は、そのコンテナ自身**を指す点が重要です。