--- name: dokploy-webapp description: NodeSrv配下（apps/）にNode.js WEBアプリを新規作成し、ローカル開発から既存Dokploy環境（AWS Lightsail上で稼働中のセルフホストPaaS）へのデプロイ・運用までを行う。「新しいアプリを作って」「Dokployにデプロイして」「アプリをNodeSrvに追加して」「動作検証して」等の依頼で使う。 --- # NodeSrv アプリ開発 & Dokployデプロイ `NodeSrv/apps/` を1アプリ1フォルダ1Dokploy Composeとして管理する。アプリ同士は完全に独立し、片方の開発・再デプロイがもう片方に影響しない設計。 ## 新規アプリ作成 1. `NodeSrv/apps/_template` を `NodeSrv/apps/` としてコピー 2. `package.json` の `name` を `` に変更 3. 必要な依存関係を追加、`src/index.js` に実装を追加していく 4. `/health` エンドポイントは削除・変更しない（Dokployのヘルスチェック対象） ## ローカル開発 ``` cd NodeSrv/apps/ npm install cp .env.example .env npm run dev ``` `http://localhost:/` と `/health` で動作確認。 ## デプロイ前のDocker動作確認（必須） Dokployは本番でDockerfileから直接ビルドするため、pushする前にローカルでも同じ手順でビルド・起動できることを確認する。 ``` docker compose -f docker-compose.local.yml up --build ``` エラー無く起動し `/health` が200を返すことを確認してから次に進む。 ## Gitソース: Gitea GitHub直接連携ではなく、Dokploy上に自前ホストしたGitea（`https://git73.next-hd.net/mygit-admin/ken_nogi.git`、リモート名`gitea`）を経由する。理由: モノレポ（`ken_nogi`）のプライベートリポジトリをDokployのGit Provider連携で直接使う設定がうまくいかず、Gitea自前ホストに切り替えた経緯がある（詳細はプロジェクトメモリ参照）。 **注意（2026-09-19判明）**: 当初はGitea上に`NodeSrv`という単体リポジトリを作って運用していたが、その後`dev`配下（NodeSrv/Pleasanter等）を`ken_nogi`という1つのGiteaリポジトリへ統合した。`NodeSrv`単体リポジトリは既に削除済み（`git73.next-hd.net/mygit-admin/NodeSrv`は404）。Dokploy側の既存Compose（app-portal/n8n等）は統合後もしばらく古い`giteaRepository: "NodeSrv"`のままになっていて、pushしても反映されない状態だった。2026-09-19に全Compose（app-portal/authgw-poc/auth-redirect/portal-sample-batch/n8n/keycloak-monitor/lineworks-user-auth）を`giteaRepository: "ken_nogi"`・`composePath`の先頭に`NodeSrv/`を付ける形へ`dokploy compose update`で修正済み。**新規Compose作成時は`giteaRepository`に`ken_nogi`、`composePath`は必ず`NodeSrv/apps//docker-compose.yml`（先頭に`NodeSrv/`が要る）を指定すること。** ``` git remote -v # "gitea" が登録済みか確認 git push gitea main ``` **注意**: Windows環境でBashツールからpushすると、Git Credential Manager (GCM) がGUIダイアログを出そうとして `tty` が無い環境では失敗する（`fatal: helper error (-1): User cancelled dialog.`）。その場合は一時的な `GIT_ASKPASS` スクリプトで認証情報（`AUTH_SECRETS.md` の Gitea項目）を渡し、push後は必ずスクリプトを削除する。認証情報を `git push` のURLやBashコマンド引数に直接書かない。 ## Dokployへの接続 `@dokploy/cli`（`npm install -g @dokploy/cli`）をインストール済みで使う。認証は `dokploy auth -u https://dokploy45.next-hd.net -t ` 済みでセッションが保持されている前提（**トークンは絶対にチャットに貼らせない・貼られたら即Revoke指示**。認証はユーザー自身のターミナルで実行させる）。以後は `dokploy ` をそのまま実行してよい（本番操作なので実行前に毎回内容を提示し確認を取る）。 **既存環境の実態**（2026-07-25確認、CLI v0.29.4）: - NodeSrv用アプリは `webapps` Project配下に **Compose**（Docker Compose、Provider: Gitea、`sourceType: gitea`）として追加する。Dokploy標準の「Application」type・「Domains」タブは使わない（README.md「共通ルール」参照） - `projectId: 3T-drY1Q377JcLeTiNTDK` / `environmentId: Cm0HjMIFyl11UdIcIGRy8`（`production`環境） - **CLIのGET系コマンドはほぼ全滅**（`compose one`, `docker get-containers*` 等が軒並み `Request failed with status code 400`）。POST/PUT系（`compose deploy`等）は動く。状態確認はCLIに頼らずSSH直接調査（下記）を使う - **原因特定済み（2026-07-25）**: `@dokploy/cli`（`dist/client.js`の`apiGet`関数）がtRPCのGETクエリを組み立てる際、`apiPost`と違い`{json: params}`でラップせず生の`params`を`?input=`にJSON化しているだけの実装バグ。DokployのtRPCサーバーは`{"json": {...}}`形式のラップを要求するため、これがない全てのGETリクエストが400になる - Dokploy tRPC API自体は正常。`x-api-key`ヘッダー付きで`GET {DOKPLOY_URL}/api/trpc/?input=`の形式で直接叩けば200が返ることを確認済み（`compose.one`で実証）。ポータル等でDokploy API連携が必要な場合は、CLIを介さずこの正しい形式で自前クライアントを実装すること - CLI自体へのパッチは行わない方針（グローバルnpmパッケージの一時修正は`npm update`等で消えるため、恒常的な対応にならない） ## Dokployへのデプロイ（CLI手順） 1アプリ = 1 Dokploy "Compose"。`webapps` Project配下に、`apps//docker-compose.yml` をCompose Pathとして指定する。 ### 新規Compose作成（CLI手順、2026-07-25実地検証済み） `dokploy compose create`はGitHub向けのデフォルト値で作成されるため、直後に`dokploy compose update`でGitea連携用の値へ切り替える2段階が必要。 ``` # 1. Compose自体を作成（webapps projectのenvironmentIdを指定） dokploy compose create \ --name "" \ --environmentId "Cm0HjMIFyl11UdIcIGRy8" \ --composeType "docker-compose" \ --appName "" \ --json # → composeId が返る # 2. sourceTypeをgiteaへ切替、リポジトリ・パスを指定 dokploy compose update \ --composeId "<上で得たcomposeId>" \ --sourceType "gitea" \ --giteaId "O5-CqLQwVdlzXw3KfmN-8" \ --giteaOwner "mygit-admin" \ --giteaRepository "ken_nogi" \ --giteaBranch "main" \ --composePath "NodeSrv/apps//docker-compose.yml" \ --json # 3. デプロイ実行 dokploy compose deploy --composeId "" --title "<変更内容>" --json ``` `serverId`は省略可（単一サーバー構成のため）。 ## デプロイ後の検証 CLIの `compose one` 等GET系コマンドは400エラーで使えないため、以下のいずれかで代替する。 ``` # SSH経由でコンテナ状態・ラベルを直接確認 ssh -i NodeSrv/Keys/LightsailDefaultKey-ap-northeast-1.pem ubuntu@dokploy45.next-hd.net \ "sudo docker ps --filter name=" ssh -i NodeSrv/Keys/LightsailDefaultKey-ap-northeast-1.pem ubuntu@dokploy45.next-hd.net \ "sudo docker inspect --format '{{json .Config.Labels}}'" # 外部疎通確認 curl -I https://.next-hd.net/health ``` **SSHが自動モード分類器にブロックされる場合**（2026-07-26確認、`sudo`付きコマンド等でブロックされることがある）は、上記57行目の自前fetchクライアント方式でDokploy側の状態（デプロイ履歴の`status`、compose設定等）を確認する。認証情報はCLIの`config.json`（`C:/Users/k.nogi/AppData/Roaming/npm/node_modules/@dokploy/cli/config.json`）から読み取り、結果は必ずファイルへ書き出してから必要な値だけ抽出する（レスポンスに機密情報が含まれるため画面に出さない）。デプロイ完了確認は`deployment.allByCompose`エンドポイントの`status`(`done`か)を見る。 - 割り当てたドメインへ `curl` し `/health` が200 - 別アプリを同時にredeployし、対象アプリ以外が無停止であることを確認（独立性の担保） ## アプリポータルへの登録(任意) 新規アプリを`NodeSrv/apps/app-portal`のダッシュボードに登録したい場合、`.env.example`にPORTAL_*変数を追加する(詳細は`NodeSrv/apps/_template/README.md`「アプリポータルへの登録」章、実装は`NodeSrv/apps/app-portal/src/dokployClient.js`参照)。 ## 参考 - 全体の運用方針・認証ゲートウェイの詳細: [../../../NodeSrv/README.md](../../../NodeSrv/README.md) - Dokployインフラの経緯: プロジェクトメモリ `project_nodesrv-dokploy-lightsail`