ken_nogi/NodeSrv/.claude/skills/dokploy-webapp/SKILL.md

name	description
dokploy-webapp	NodeSrv配下（apps/<app-name>）にNode.js WEBアプリを新規作成し、ローカル開発から既存Dokploy環境（AWS Lightsail上で稼働中のセルフホストPaaS）へのデプロイ・運用までを行う。「新しいアプリを作って」「Dokployにデプロイして」「アプリをNodeSrvに追加して」「動作検証して」等の依頼で使う。

NodeSrv アプリ開発 & Dokployデプロイ

NodeSrv/apps/<app-name> を1アプリ1フォルダ1Dokploy Composeとして管理する。アプリ同士は完全に独立し、片方の開発・再デプロイがもう片方に影響しない設計。

新規アプリ作成

1. NodeSrv/apps/_template を NodeSrv/apps/<app-name> としてコピー
2. package.json の name を <app-name> に変更
3. 必要な依存関係を追加、src/index.js に実装を追加していく
4. /health エンドポイントは削除・変更しない（Dokployのヘルスチェック対象）

ローカル開発

cd NodeSrv/apps/<app-name>
npm install
cp .env.example .env
npm run dev

http://localhost:<PORT>/ と /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/NodeSrv.git、リモート名gitea）を経由する。理由: モノレポ（ken_nogi）のプライベートリポジトリをDokployのGit Provider連携で直接使う設定がうまくいかず、Gitea自前ホストに切り替えた経緯がある（詳細はプロジェクトメモリ参照）。

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 <token> 済みでセッションが保持されている前提（トークンは絶対にチャットに貼らせない・貼られたら即Revoke指示。認証はユーザー自身のターミナルで実行させる）。以後は dokploy <command> をそのまま実行してよい（本番操作なので実行前に毎回内容を提示し確認を取る）。

既存環境の実態（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/<endpoint>?input=<encodeURIComponent('{"json":{...}}')>の形式で直接叩けば200が返ることを確認済み（compose.oneで実証）。ポータル等でDokploy API連携が必要な場合は、CLIを介さずこの正しい形式で自前クライアントを実装すること
  • CLI自体へのパッチは行わない方針（グローバルnpmパッケージの一時修正はnpm update等で消えるため、恒常的な対応にならない）

Dokployへのデプロイ（CLI手順）

1アプリ = 1 Dokploy "Compose"。webapps Project配下に、apps/<app-name>/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 "<app-name>" \
  --environmentId "Cm0HjMIFyl11UdIcIGRy8" \
  --composeType "docker-compose" \
  --appName "<app-name>" \
  --json
# → composeId が返る

# 2. sourceTypeをgiteaへ切替、リポジトリ・パスを指定
dokploy compose update \
  --composeId "<上で得たcomposeId>" \
  --sourceType "gitea" \
  --giteaId "O5-CqLQwVdlzXw3KfmN-8" \
  --giteaOwner "mygit-admin" \
  --giteaRepository "NodeSrv" \
  --giteaBranch "main" \
  --composePath "apps/<app-name>/docker-compose.yml" \
  --json

# 3. デプロイ実行
dokploy compose deploy --composeId "<composeId>" --title "<変更内容>" --json

serverIdは省略可（単一サーバー構成のため）。

デプロイ後の検証

CLIの compose one 等GET系コマンドは400エラーで使えないため、以下のいずれかで代替する。

# SSH経由でコンテナ状態・ラベルを直接確認
ssh -i Keys/LightsailDefaultKey-ap-northeast-1.pem ubuntu@dokploy45.next-hd.net \
  "sudo docker ps --filter name=<app-name>"
ssh -i Keys/LightsailDefaultKey-ap-northeast-1.pem ubuntu@dokploy45.next-hd.net \
  "sudo docker inspect <container-name> --format '{{json .Config.Labels}}'"

# 外部疎通確認
curl -I https://<app-name>.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し、対象アプリ以外が無停止であることを確認（独立性の担保）

アプリポータルへの登録(任意)

新規アプリをapps/app-portalのダッシュボードに登録したい場合、.env.exampleにPORTAL_*変数を追加する(詳細はapps/_template/README.md「アプリポータルへの登録」章、実装はapps/app-portal/src/dokployClient.js参照)。

参考

• 全体の運用方針・認証ゲートウェイの詳細: ../../README.md
• Dokployインフラの経緯: プロジェクトメモリ project_nodesrv-dokploy-lightsail