diff --git a/README.md b/README.md index abf5fff..fb22796 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,10 @@ 設定値(config)の配置ルールと定数一覧は [packages/shared/src/config/README.md](packages/shared/src/config/README.md) を参照してください。 -## クライアント環境変数(Vite) +## デプロイ・環境変数 -`apps/client/src/config/index.ts` の `PROD_SERVER_URL` は `import.meta.env.VITE_PROD_SERVER_URL` を参照します。 - -- `VITE_PROD_SERVER_URL` はクライアント用の環境変数です(Viteビルド時に埋め込まれます)。 -- Renderでは server サービスではなく、client をビルドして配信するサービス側で設定してください。 -- 値を変更した場合は再デプロイ(再ビルド)が必要です。 -- `VITE_*` の値はブラウザから参照可能なため、秘密情報は設定しないでください。 - -### Render での設定手順 - -1. Render ダッシュボードで client サービスを開く -2. `Environment` で環境変数を追加する -3. `Key`: `VITE_PROD_SERVER_URL` -4. `Value`: `https://` -5. 保存後に再デプロイする - -### ローカル開発での例 - -`apps/client/.env.development` - -```env -VITE_PROD_SERVER_URL=https:// -``` +| ドキュメント | 内容 | +|---|---| +| [ENV_08_環境変数設定.txt](docs/02_ENV/ENV_08_環境変数設定.txt) | 全デプロイ先共通の環境変数一覧と設定方法 | +| [ENV_09_Renderデプロイ手順.txt](docs/02_ENV/ENV_09_Renderデプロイ手順.txt) | Render へのデプロイ手順 | +| [ENV_10_研究室サーバデプロイ手順書.txt](docs/02_ENV/ENV_10_研究室サーバデプロイ手順書.txt) | 研究室サーバへのデプロイ手順 | diff --git "a/docs/02_ENV/ENV_08_\347\222\260\345\242\203\345\244\211\346\225\260\350\250\255\345\256\232.txt" "b/docs/02_ENV/ENV_08_\347\222\260\345\242\203\345\244\211\346\225\260\350\250\255\345\256\232.txt" new file mode 100644 index 0000000..3ba0860 --- /dev/null +++ "b/docs/02_ENV/ENV_08_\347\222\260\345\242\203\345\244\211\346\225\260\350\250\255\345\256\232.txt" @@ -0,0 +1,48 @@ +======================================================================== +環境変数設定 (Environment Variables) +======================================================================== + +1. 概要 (Overview) +------------------------------------------------------------------------ + +1-1. 目的 + 本ドキュメントは,Pixel Paint War のビルド・実行時に必要な環境変数の + 一覧と設定方法を記す. + デプロイ先ごとの固有手順は各デプロイ手順書を参照すること. + + ・Render へのデプロイ: ENV_09_Renderデプロイ手順.txt + ・研究室サーバへのデプロイ: ENV_10_研究室サーバデプロイ手順書.txt + + +2. クライアント環境変数(Vite) (Client Environment Variables) +------------------------------------------------------------------------ + +2-1. 変数一覧 + + ■ VITE_PROD_SERVER_URL + ・用途: 本番環境でクライアントが接続するサーバの URL + ・参照箇所: apps/client/src/config/index.ts の PROD_SERVER_URL + ・設定タイミング: Vite ビルド時に静的ファイルへ埋め込まれる + ・注意事項: + - VITE_* の値はブラウザから参照可能なため,秘密情報は設定しないこと + - 値を変更した場合は再ビルド・再デプロイが必要 + +2-2. ローカル開発での設定例 + 開発時は以下のファイルに記述する. + + ファイル: apps/client/.env.development + + VITE_PROD_SERVER_URL=http://localhost:3000 + + ※ .env.development は .gitignore に含めること + + +3. サーバ環境変数 (Server Environment Variables) +------------------------------------------------------------------------ + +3-1. 変数一覧 + + ■ NODE_ENV + ・用途: 実行環境の識別 + ・値: production(本番)/ development(開発) + ・設定箇所: docker-compose.prod.yml の environment セクション diff --git "a/docs/02_ENV/ENV_09_Render\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206.txt" "b/docs/02_ENV/ENV_09_Render\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206.txt" new file mode 100644 index 0000000..4d2d429 --- /dev/null +++ "b/docs/02_ENV/ENV_09_Render\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206.txt" @@ -0,0 +1,71 @@ +======================================================================== +Render デプロイ手順 (Render Deployment Guide) +======================================================================== + +1. 概要 (Overview) +------------------------------------------------------------------------ + +1-1. 目的 + 本ドキュメントは,Pixel Paint War を Render にデプロイする手順を記す. + 環境変数の詳細については ENV_08_環境変数設定.txt を参照すること. + +1-2. 構成 + Render 上で以下の2サービスを運用する. + + ・client サービス: Vite でビルドした静的ファイルを配信 + ・server サービス: Node.js バックエンドを動作させる Web Service + + +2. 環境変数の設定 (Environment Variables) +------------------------------------------------------------------------ + +2-1. client サービスへの設定 + VITE_PROD_SERVER_URL はビルド時に埋め込まれるため, + server サービスではなく client サービス側で設定すること. + + 1. Render ダッシュボードで client サービスを開く + 2. 「Environment」タブを開く + 3. 以下の環境変数を追加する + Key: VITE_PROD_SERVER_URL + Value: https:// + 4. 保存後に「Manual Deploy」または自動デプロイで再ビルドする + + ※ 値を変更した場合は必ず再デプロイ(再ビルド)すること + + +3. デプロイ手順 (Deployment Steps) +------------------------------------------------------------------------ + +3-1. server サービスの設定 + 1. Render ダッシュボードで「New +」→「Web Service」を選択する + 2. リポジトリを接続する + 3. 以下の設定を行う + ・Environment: Node + ・Build Command: pnpm --filter @repo/shared build && pnpm --filter server build + ・Start Command: node apps/server/dist/index.js + 4. 「Create Web Service」で作成する + +3-2. client サービスの設定 + 1. Render ダッシュボードで「New +」→「Static Site」を選択する + 2. リポジトリを接続する + 3. 以下の設定を行う + ・Build Command: pnpm --filter @repo/shared build && pnpm --filter client build + ・Publish Directory: apps/client/dist + 4. 2章の手順で環境変数 VITE_PROD_SERVER_URL を設定する + 5. 「Create Static Site」で作成する + +3-3. 動作確認 + 1. server サービスのログで起動エラーがないことを確認する + 2. client サービスの URL にブラウザからアクセスしてゲーム画面を確認する + + +4. 再デプロイ手順 (Redeployment) +------------------------------------------------------------------------ + +4-1. コード変更時 + main ブランチへのマージを契機に自動デプロイが走る(Auto-Deploy 有効時). + 手動で行う場合は各サービスの「Manual Deploy」ボタンを押す. + +4-2. 環境変数変更時 + client サービスの環境変数を変更した場合は, + 変更後に必ず再デプロイ(再ビルド)を実施すること. diff --git "a/docs/02_ENV/ENV_10_\347\240\224\347\251\266\345\256\244\343\202\265\343\203\274\343\203\220\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206\346\233\270.txt" "b/docs/02_ENV/ENV_10_\347\240\224\347\251\266\345\256\244\343\202\265\343\203\274\343\203\220\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206\346\233\270.txt" new file mode 100644 index 0000000..6f4179d --- /dev/null +++ "b/docs/02_ENV/ENV_10_\347\240\224\347\251\266\345\256\244\343\202\265\343\203\274\343\203\220\343\203\207\343\203\227\343\203\255\343\202\244\346\211\213\351\240\206\346\233\270.txt" @@ -0,0 +1,279 @@ +======================================================================== +研究室サーバデプロイ手順書 (Lab Server Deployment Guide) +======================================================================== + +1. 概要 (Overview) +------------------------------------------------------------------------ +本ドキュメントは,Pixel Paint War を1台の研究室サーバ上に本番デプロイする +手順をまとめたものである. +Nginx をリバースプロキシとして使用し,外部公開ポートは 8803 のみとする. +フロントエンド(静的ファイル)とバックエンド(Socket.IO)は同一サーバ内で +ポートを分けて動作させ,外部デバイスは Nginx 経由でのみ通信する. + + +1-1. 構成図 + + [デバイス] ──HTTP(8803)──▶ [Nginx (:8803)] + ├── / → 静的ファイル配信(Viteビルド済み) + └── /socket.io → proxy_pass http://127.0.0.1:3000 + (サーバ内部のみ,外部非公開) + + ・外部公開ポート: 8803 のみ + ・バックエンド(ポート3000)は localhost バインドで外部アクセス不可 + ・HTTPS化する場合は Nginx で SSL 終端を行う(6章参照) + + +2. 前提条件 (Prerequisites) +------------------------------------------------------------------------ + +2-1. サーバ環境 + ・OS: Linux(Ubuntu 20.04 以上推奨) + ・Docker / Docker Compose がインストール済みであること + ・Nginx がインストール済みであること + ・Git がインストール済みであること + ・ポート 8803 がファイアウォールで許可されていること + +2-2. 確認コマンド + $ docker --version + $ docker compose version + $ nginx -v + $ git --version + + +3. デプロイ手順 (Deployment Steps) +------------------------------------------------------------------------ + +3-1. リポジトリの取得 + 1. サーバ上で任意のディレクトリにクローンする + $ git clone <リポジトリURL> /opt/pixel-paint-war + $ cd /opt/pixel-paint-war + + 2. デプロイ対象のブランチ・タグに切り替える + $ git checkout main + $ git pull origin main + +3-2. フロントエンドのビルド + フロントエンドは静的ファイルとしてビルドし,Nginx から配信する. + VITE_PROD_SERVER_URL にはデバイスからアクセスする URL を指定する. + + ■ ローカルネットワーク(HTTP)の場合 + $ docker run --rm -v $(pwd):/app -w /app node:20-slim \ + bash -c "corepack enable && pnpm install --frozen-lockfile \ + && pnpm --filter @repo/shared build \ + && VITE_PROD_SERVER_URL=http://<サーバIP>:8803 pnpm --filter client build" + + ■ ドメイン運用(HTTPS)の場合 + $ docker run --rm -v $(pwd):/app -w /app node:20-slim \ + bash -c "corepack enable && pnpm install --frozen-lockfile \ + && pnpm --filter @repo/shared build \ + && VITE_PROD_SERVER_URL=https://yourdomain.example.com:8803 pnpm --filter client build" + + ※ ビルド成果物は apps/client/dist/ に出力される + +3-3. バックエンドの起動(Docker Compose) + 本番用の docker-compose.prod.yml を使用してバックエンドを起動する. + ポートは localhost バインドとし,Nginx 経由でのみアクセスさせる. + + 1. docker-compose.prod.yml を以下の内容に編集する + + services: + game-server: + build: + context: . + dockerfile: Dockerfile + container_name: pixel-paint-server-prod + restart: unless-stopped + ports: + - "127.0.0.1:3000:3000" + environment: + - NODE_ENV=production + + ※ ポイント: ports を "127.0.0.1:3000:3000" にすることで, + localhost からのみアクセス可能となり外部に直接公開されない + + 2. コンテナをビルド・起動する + $ docker compose -f docker-compose.prod.yml up -d --build + + 3. 起動確認 + $ docker compose -f docker-compose.prod.yml ps + + STATUS が「Up」になっていることを確認する + + 4. ヘルスチェック + $ curl http://127.0.0.1:3000 + + 「ok」と返れば正常 + +3-4. Nginx の設定 + Nginx の設定ファイルを作成し,ポート 8803 でリクエストを受け付ける. + + 1. 設定ファイルを作成する + $ sudo vi /etc/nginx/sites-available/pixel-paint-war + + 2. 以下の内容を記述する + + server { + listen 8803; + server_name _; + + # フロントエンド(静的ファイル配信) + root /opt/pixel-paint-war/apps/client/dist; + index index.html; + + location / { + try_files $uri $uri/ /index.html; + } + + # バックエンド(Socket.IO → 内部ポート3000へプロキシ) + location /socket.io/ { + proxy_pass http://127.0.0.1:3000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + + 3. シンボリックリンクを作成して有効化する + $ sudo ln -s /etc/nginx/sites-available/pixel-paint-war /etc/nginx/sites-enabled/ + + 4. 設定の文法チェック + $ sudo nginx -t + + 「syntax is ok」「test is successful」と表示されること + + 5. Nginx を再起動する + $ sudo systemctl restart nginx + +3-5. 動作確認 + 1. ブラウザからアクセスする + http://<サーバIP>:8803 + + 2. ゲーム画面が表示され,ルーム作成・参加が正常に動作することを確認する + + 3. バックエンドへの直接アクセスが遮断されていることを確認する + $ curl http://<サーバIP>:3000 + → 接続拒否またはタイムアウトになること + + +4. ファイアウォール設定 (Firewall) +------------------------------------------------------------------------ +外部に公開するポートを 8803 のみに制限する. + +4-1. ufw を使用する場合 + $ sudo ufw allow 8803/tcp + $ sudo ufw deny 3000/tcp + $ sudo ufw enable + $ sudo ufw status + +4-2. 確認事項 + ・ポート 8803: 外部からアクセス可能であること + ・ポート 3000: 外部からアクセス不可であること + ・SSH ポート(22): 許可済みであること(ロックアウト防止) + + +5. 運用コマンド (Operations) +------------------------------------------------------------------------ + +5-1. 基本操作 + ■ バックエンドの状態確認 + $ docker compose -f docker-compose.prod.yml ps + + ■ ログ確認(リアルタイム) + $ docker compose -f docker-compose.prod.yml logs -f + + ■ バックエンドの停止 + $ docker compose -f docker-compose.prod.yml down + + ■ バックエンドの再起動 + $ docker compose -f docker-compose.prod.yml restart + + ■ Nginx の状態確認 + $ sudo systemctl status nginx + +5-2. アップデート手順 + コードを更新して再デプロイする場合の手順. + + 1. 最新コードを取得する + $ cd /opt/pixel-paint-war + $ git pull origin main + + 2. フロントエンドを再ビルドする(3-2 の手順を再実行) + + 3. バックエンドを再ビルド・再起動する + $ docker compose -f docker-compose.prod.yml up -d --build + + 4. Nginx を再読み込みする(設定変更がある場合のみ) + $ sudo systemctl reload nginx + +5-3. キャッシュクリア再ビルド + ビルドキャッシュが原因で問題が発生する場合に実行する. + + $ docker compose -f docker-compose.prod.yml build --no-cache + $ docker compose -f docker-compose.prod.yml up -d --force-recreate + + +6. HTTPS化(任意) (HTTPS Setup) +------------------------------------------------------------------------ +ドメインを使用して HTTPS でアクセスさせる場合の追加手順. + +6-1. Let's Encrypt で証明書を取得する + $ sudo apt install certbot python3-certbot-nginx + $ sudo certbot --nginx -d yourdomain.example.com + +6-2. Nginx 設定を HTTPS 対応に変更する + + server { + listen 8803 ssl; + server_name yourdomain.example.com; + + ssl_certificate /etc/letsencrypt/live/yourdomain.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/yourdomain.example.com/privkey.pem; + + root /opt/pixel-paint-war/apps/client/dist; + index index.html; + + location / { + try_files $uri $uri/ /index.html; + } + + location /socket.io/ { + proxy_pass http://127.0.0.1:3000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + +6-3. 証明書の自動更新を確認する + $ sudo certbot renew --dry-run + + +7. トラブルシューティング (Troubleshooting) +------------------------------------------------------------------------ + +7-1. ブラウザでゲーム画面が表示されない + ・Nginx のエラーログを確認する + $ sudo tail -50 /var/log/nginx/error.log + ・静的ファイルのパスが正しいか確認する + $ ls /opt/pixel-paint-war/apps/client/dist/index.html + +7-2. Socket.IO 接続がエラーになる + ・バックエンドコンテナが起動しているか確認する + $ docker compose -f docker-compose.prod.yml ps + ・ローカルからバックエンドに疎通できるか確認する + $ curl http://127.0.0.1:3000 + ・Nginx のプロキシ設定で WebSocket ヘッダーが正しいか確認する + +7-3. ポート 8803 にアクセスできない + ・ファイアウォールでポート 8803 が許可されているか確認する + $ sudo ufw status + ・Nginx がポート 8803 で listen しているか確認する + $ sudo ss -tlnp | grep 8803 diff --git "a/docs/02_ENV/ENV_11_TypeScript\346\246\202\350\246\201.txt" "b/docs/02_ENV/ENV_11_TypeScript\346\246\202\350\246\201.txt" new file mode 100644 index 0000000..e489c79 --- /dev/null +++ "b/docs/02_ENV/ENV_11_TypeScript\346\246\202\350\246\201.txt" @@ -0,0 +1,90 @@ +======================================================================== +TypeScript概要 (TypeScript Overview) +======================================================================== + +1. 概要 (Overview) +------------------------------------------------------------------------ +本プロジェクト(Pixel Paint War)において採用するプログラミング言語「TypeScript」に関する基礎知識,選定理由,およびAI活用開発における優位性を定義する. +本ドキュメントは,開発チーム内での技術認識の統一を目的とする. + + +2. TypeScriptとは (What is TypeScript) +------------------------------------------------------------------------ +Microsoftによって開発されたオープンソースのプログラミング言語である.JavaScriptのスーパーセット(上位互換)として設計されており,大規模なアプリケーション開発に適した機能が拡張されている. + +2-1. JavaScriptとの違い + ・静的型付け (Static Typing): + 変数や関数の引数,戻り値に「型(Type)」を指定できる.JavaScriptは動的型付け言語であり,実行時まで型が決まらないが,TypeScriptはコンパイル(トランスパイル)時に整合性をチェックする. + ・クラスベースオブジェクト指向: + インターフェース(Interface),ジェネリクス(Generics),アクセス修飾子(public/private)など,JavaやC#に近いオブジェクト指向構文をサポートする. + ・コンパイルの必要性: + ブラウザやNode.jsはTypeScriptを直接実行できないため,JavaScriptファイルへ変換(トランスパイル)して使用する. + +2-2. 一般的な利用目的 + ・大規模Webアプリケーション開発: + コード量が増えても型定義により保守性を維持しやすい. + ・チーム開発: + 型定義がそのまま「仕様書」としての役割を果たし,メンバー間の認識齟齬を防ぐ. + ・フルスタック開発: + フロントエンド(React/Vue/Angular等)とバックエンド(Node.js/Deno等)で言語を統一し,型定義を共有する. + + +3. 言語の強み (Strengths) +------------------------------------------------------------------------ + +3-1. 安全性と品質向上 + ・コンパイルエラーによる早期発見: + 「undefinedのプロパティ参照」や「数値と文字列の誤った演算」など,JavaScriptで頻発する実行時エラーを,コードを書いている段階(コンパイル時)で検出できる. + +3-2. 開発効率の向上 + ・強力な入力補完 (IntelliSense): + VS Code等のエディタにおいて,型情報を元にした正確なコード補完,メソッドの候補表示,定義元へのジャンプが可能となる. + ・リファクタリングの容易さ: + 変数名や関数名の変更を行っても,依存する箇所をエディタが一括で修正・検知できるため,改修コストが低い. + + +4. AI活用型開発における利点 (Benefits in AI-Assisted Development) +------------------------------------------------------------------------ +本プロジェクトの方針である「AI活用型開発(Gemini Pro / GitHub Copilot Pro)」において,TypeScriptはJavaScriptと比較して以下の決定的な優位性を持つ. + +■ コンテキストの正確な伝達 + 型定義(Type/Interface)が存在することで,AIは変数の意図やデータ構造を推測ではなく「確定情報」として認識できる.これにより,提案されるコードの精度が向上する. + +■ ハルシネーション(嘘の生成)の抑制 + 存在しないプロパティや誤ったメソッドをAIが提案した場合でも,TypeScriptのコンパイラが即座にエラーを出すため,誤ったコードが実装に含まれるリスクを自動的に排除できる. + +■ 意図の明示化 + 「ENV_01」で定義された `packages/shared` のような共通型定義を参照させることで,AIはクライアント・サーバー間の通信仕様を正確に理解し,一貫性のあるロジックを生成可能となる. + + +5. 歴史と現状 (History and Current Status) +------------------------------------------------------------------------ + +5-1. 歴史 + ・開発者: Anders Hejlsberg(C#やTurbo Pascalの設計者)らが中心となり開発. + ・初版公開: 2012年10月. + ・背景: 当時,大規模化するWebアプリ開発においてJavaScriptの仕様(ES5)では保守が困難であったため,静的型付けの需要が高まっていた. + +5-2. 現在のステータス + ・世界No.1の使用率 (GitHub Octoverse 2025): + 2025年のGitHub年次レポートにおいて,長年トップであったPythonおよびJavaScriptを上回り,世界で最も使用されている言語(第1位)となった. + このランキングは,単なるコードの総量ではなく「貢献者数(Unique Contributors)」に基づいており,現在世界中で最も多くのアクティブユーザーが開発を行っている言語であることを示している. + ・デファクトスタンダード: + 現在,モダンなフロントエンド開発(React, Next.js, Vue.jsなど)において,TypeScriptは標準的な選択肢となっている. + ・普及率: + 「State of JS」などの開発者アンケートにおいて,長年「使用率」および「満足度」で上位を維持している.また,Google社内の標準言語としても採用されている(Alligator等). + + +6. 参考文献 (References) +------------------------------------------------------------------------ +・TypeScript Official Website + https://www.typescriptlang.org/ + +・The State of JS 2022/2023 (Usage & Satisfaction) + https://stateofjs.com/ + +・GitHub Octoverse 2025 + https://octoverse.github.com/ + +・Google Engineering Practices Documentation + https://google.github.io/eng-practices/ \ No newline at end of file