# app-template

新規WEBアプリを作る際のひな形。新しいアプリを作るときは、このフォルダを `NodeSrv/apps/<新アプリ名>` としてコピーして使う。

## ローカル開発

```
npm install
cp .env.example .env
npm run dev
```

`http://localhost:3000/` と `http://localhost:3000/health` で動作確認。

## 本番同等の動作確認（Docker）

Dokployへデプロイする前に、ローカルでも同じDockerfileでビルド・起動できることを確認する。

```
docker compose -f docker-compose.local.yml up --build
```

`docker-compose.local.yml` はローカル検証専用。Dokploy側は `docker-compose.yml` を使う（Compose「Raw」プロバイダ、Traefikラベルを手書きしたもの）。

## Dokployへのデプロイ

詳細手順は `.claude/skills/dokploy-webapp/SKILL.md` および NodeSrvリポジトリ直下の `README.md` を参照。概要:

1. `docker-compose.yml` 内の `your-app-name`（Dockerサービス名・Traefikルーター識別子）と `yourapp.apps.next-hd.net`（公開ドメイン）をそれぞれ実際の値に置換。両者は独立した値でよく、一致させる必要はない
2. Gitea（`https://git73.next-hd.net/mygit-admin/NodeSrv.git`）へpush
3. Dokployで新規Compose（`webapps` project、Provider: Gitea、sourceType: gitea、Compose Path: `apps/<アプリ名>/docker-compose.yml`）を作成
4. 環境変数（`.env.example` の内容）をDokployのEnvironment画面に設定（`.env` 自体はgit管理しない）
5. Deploy実行 → `https://<公開ドメイン>.apps.next-hd.net/health` が200を返すことを確認

認証ゲートウェイ（Keycloak/oauth2-proxy）は既定では付けない。必要な場合のみ、リポジトリ直下 `README.md` の「認証ゲートウェイ」章を参照して個別に追加する。

## アプリポータル(apps/app-portal)への登録

`webapps` project配下のアプリは、`.env.example`のPORTAL_*変数をDokploy Environment画面で設定することで、`apps/app-portal`のダッシュボードに一覧表示・操作対象として登録できる(任意)。

- 常駐WEBサービス(`PORTAL_APP_TYPE=web`): ダッシュボードからStart/Stop/Restart、「開く」で`PORTAL_APP_URL`へ遷移
- バッチジョブ(`PORTAL_APP_TYPE=batch`): ダッシュボードの「今すぐ実行」から`PORTAL_APP_URL${PORTAL_TRIGGER_PATH}`へPOSTされる。アプリ側は以下のパターンでトリガーエンドポイントを実装する:

```js
app.post(process.env.PORTAL_TRIGGER_PATH, (req, res) => {
  if (req.headers['x-portal-secret'] !== process.env.PORTAL_SECRET) {
    return res.sendStatus(403);
  }
  // 実処理を非同期でキューイングし即座に202を返す
  res.sendStatus(202);
});
```

`PORTAL_SECRET`はポータルとアプリ間で共有する値。`AUTH_SECRETS.md`同様、機密情報として扱いDokploy Environment画面でのみ設定する。実装例は`apps/portal-sample-batch/src/index.js`参照。