ce58cb4be4
GitHub(nextgroup2706/ken_nogi)は今後使わず自社Gitea運用に切替え。 NodeSrvは旧リポジトリの履歴を破棄しファイルのみ統合(Dokploy用サービスアカウントは 別途mygit-admin/NodeSrv.gitに履歴あり)。notepmエクスポート(12GB)とPleasanter インストーラzip(208MB)はサイズが大きいため.gitignoreで除外。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
124 lines
7.8 KiB
Markdown
124 lines
7.8 KiB
Markdown
---
|
||
name: dokploy-webapp
|
||
description: 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](../../README.md)
|
||
- Dokployインフラの経緯: プロジェクトメモリ `project_nodesrv-dokploy-lightsail`
|