#nb init

現在のワークスペースを初期化して、coding agent が NocoBase に接続して利用できるようにします。

nb init は、新しいローカル NocoBase アプリをインストールすることも、既存アプリの接続情報を保存することもできます。

また、nb init はデフォルトで NocoBase AI coding skills も同期します。すでに skills を自分で管理している場合、または CI やオフライン環境で実行する場合にのみ、--skip-skills を追加する必要があります。

#使い方

nb init [flags]

#対話モード

nb init は 3 つの対話モードをサポートしています:

• nb init: ターミナルでガイドに従って 1 ステップずつセットアップを完了する
• nb init --ui: ローカルブラウザでフォームを開き、ビジュアルウィザードで setup を完了する
• nb init --yes --env app1: プロンプトをスキップして flags を直接使う。明示的に渡していないパラメータはデフォルト値で処理される

--yes モードは、スクリプト、CI/CD、その他の非対話シナリオに適しています。このモードでは、--env <envName> は必須です。通常はデフォルトで新しいローカルアプリをインストールします。--source を指定しない場合、インストール元として docker がデフォルトで使用されます。

#中断した初期化の再開

インストール系フローでは、まず env 設定を保存し、その後にダウンロード、データベース、アプリのインストールを実行します。途中で失敗した場合は、次のように続行できます:

nb init --env app1 --resume

--resume は、すでに env 設定が保存されている初期化フローにのみ適用でき、--env を明示的に渡す必要があります。

#先に env を準備し、アプリのインストールは後で行う

--prepare-only は、最初に env を準備し、その後 license を有効化し、最後にアプリをインストールして起動する必要があるフロー向けです。

env 設定を先に保存し、データベースを準備しつつ、依存関係のダウンロード、実際のアプリインストール、初回起動を後回しにしたい場合は、次のように実行できます:

nb init --env app1 --prepare-only
nb init --env app1 --prepare-only --ui
nb init --env app1 --prepare-only --yes

このモードは --ui ウィザードを含むローカルインストールフローで利用できますが、リモート接続フローでは利用できません。CLI は現在の env を prepared 状態として保存するため、後で次のようなフローで続行できます:

nb license activate --env app1
nb app start --env app1

その後、nb app start が初回インストールを完了し、env を prepared 状態から通常の installed 状態へ切り替えます。

#インストールディレクトリの説明

完全なパスは nb env info app1 --field app.appPath で確認できます。

デフォルトでは、CLI は app-path 配下のローカルファイルを次の規約で構成します:

<app-path>/
├── .nb/      # この env 用の CLI メタデータ。例: hooks.mjs
├── source/   # アプリのソースコードまたはダウンロード内容のデフォルトディレクトリ
├── storage/  # ランタイムデータディレクトリ
└── .env      # オプションのアプリ環境変数ファイル

通常は次の通りです:

• .nb/ には CLI が管理するメタデータを保存します。--hook-script で渡したスクリプトは <app-path>/.nb/hooks.mjs にコピーされ、後続の nb app upgrade やローカル source の復元で再利用されます
• source/ は主に npm / Git env のローカルアプリディレクトリに対応します。Docker env についても CLI はこのデフォルトのパス導出を維持しますが、ほとんどの場合は手動で気にする必要はありません。アップグレード時には特に注意してください。source/ ディレクトリは削除されたあと再ダウンロードされるため、保持したいファイルをここに置かないでください
• storage/ には、組み込みデータベースのデータ、プラグイン、ログなどのランタイムデータを格納します
• .env はオプションのアプリ環境変数ファイルです。環境変数をカスタマイズしたい場合にのみ <app-path>/.env に追加する必要があります。このファイルが存在する場合、Docker、npm、Git の各インストール元はデフォルトでこれを読み取ります

これは CLI のデフォルトディレクトリ規約を表しています。インストール元、プラグイン、実行段階によって、実際に生成されるディレクトリ内容は完全には同じでない場合があります。

#注意事項

#Steps ですばやく位置を確認する

表示される Steps は setup パスによって完全には同じではありません。たとえば既存アプリに接続する場合は、通常 Getting started と Remote connection だけを使います。

ローカル UI ウィザードに従って 1 ステップずつ操作する場合は、まず次の表で該当箇所をすばやく確認できます:

#パラメータ

パラメータは多いため、利用シナリオごとに分けて見るとわかりやすくなります。

以下の「デフォルト値」は、そのパラメータを省略したときに nb init が通常採用する値または動作を意味します。

#基本と対話

#既存アプリへの接続

#ローカルインストールの基本パラメータ

#データベースパラメータ

#ダウンロードとソースコードのパラメータ

#例

もっとも一般的な使い方は次の通りです。

#ターミナルでガイドに従って 1 ステップずつ完了する

nb init

#ローカルブラウザウィザードを開く

nb init --ui
nb init --ui --ui-port 3000

#先に準備し、その後で license を有効化して起動する

nb init --env app1 --prepare-only
nb license activate --env app1
nb app start --env app1

#非対話モードで新しいローカルアプリをインストールする

--source を指定しない場合、通常は Docker がインストール元として使用されます。

nb init --env app1 --yes
nb init --env app1 --yes --source docker --version latest
nb init --env app1 --yes --source docker --version beta
nb init --env app1 --yes --source docker --version alpha
nb init --env app1 --yes --source docker --version main \
  --docker-registry registry.cn-beijing.aliyuncs.com/nocobase/nocobase
nb init --env app1 --yes --source npm --version latest
nb init --env app1 --yes --source npm --version beta
nb init --env app1 --yes --source npm --version alpha
nb init --env app1 --yes --source npm --version beta --app-port 13080
nb init --env app1 --yes --source git --version latest
nb init --env app1 --yes --source git --version beta
nb init --env app1 --yes --source git --version alpha
nb init --env app1 --yes --source git --version feat/plugin-workflow-timeout
nb init --env app1 --yes --source git --version latest \
  --git-url https://gitee.com/nocobase/nocobase.git

#hook スクリプトでインストールフローを拡張する

インストール中に追加コンテンツを準備したい場合は、--hook-script でローカル ESM モジュールを渡します:

nb init --env app1 --yes --source git --hook-script ./hooks.mjs

CLI はこのファイルを <app-path>/.nb/hooks.mjs にコピーし、env config に hookScript: ".nb/hooks.mjs" を保存します。後続の nb app start、nb app restart、nb app upgrade はこの場所から再利用します。

hook ファイルはオブジェクトを default export する必要があります。必要なメソッドだけ実装してください:

export default {
  beforeDependencyInstall: async (context) => {
    // Runs after git clone / npm scaffold and before yarn install.
  },
  beforeAppInstall: async (context) => {
    // Runs before the app-level install or upgrade command.
  },
  afterAppStart: async (context) => {
    // Runs after the app actually starts and passes the health check.
  },
};

• beforeDependencyInstall npm/Git source のみに適用され、実際の yarn install の直前に実行されます。Docker source では実行されません
• beforeAppInstall アプリレベルの install または upgrade コマンドの前に実行され、npm/Git/Docker source に適用されます
• afterAppStart アプリが実際に起動し、__health_check に通った後に実行されます。nb app start、nb app restart、nb app upgrade で実行される場合があります

--prepare-only は env config の保存と hook ファイルのコピーだけを行います。hook は実行されません。後で初回の nb app start を実行すると、CLI は初回インストール用 hook を context.phase が init、context.command が app:start の状態で実行します。

context には phase、command、source、version、appPath、sourcePath、storagePath、hookScript、envConfig などのライフサイクル情報が含まれます。hook がエラーを投げると、現在の CLI コマンドは失敗します。afterAppStart は start、restart、upgrade で繰り返し実行される可能性があるため、冪等にしてください。

#すばやくインストールして basic 認証を使う

非対話モードでローカルアプリをすばやくインストールし、インストール完了後に basic 認証もそのまま保存したい場合は、このようにも書けます。こうすると、OAuth を完了するためにブラウザを開く必要がありません。

--yes モードのデフォルト管理者アカウントをそのまま使う場合、最短では次のように書けます。

省略時、デフォルトの管理者アカウントは nocobase、デフォルトパスワードは admin123 です:

nb init --env app1 --yes --auth-type basic

管理者アカウントも同時にカスタマイズしたい場合は、次のように書けます:

nb init --env app1 --yes \
  --auth-type basic \
  --root-username admin \
  --root-password secret123

#既存アプリに接続する

通常はデフォルトで OAuth を使えば十分です。CI/CD など一部のシナリオでブラウザを開くのが不便な場合は、basic 認証を直接保存することもできます。すでに API token を持っている場合は、token 認証を直接保存することもできます。

nb init --env staging --yes \
  --api-base-url https://demo.example.com/api

nb init --env staging --yes \
  --api-base-url https://demo.example.com/api \
  --auth-type basic \
  --username <username> \
  --password <password>

nb init --env staging --yes \
  --api-base-url https://demo.example.com/api \
  --auth-type token \
  --access-token <token>

nb init --env staging --yes \
  --api-base-url https://demo.example.com/api \
  --auth-type oauth \
  --skip-auth

#データベース命名をカスタマイズする

PostgreSQL schema、テーブルプレフィックス、またはアンダースコア命名を指定する必要がある場合は、次のようにパラメータを渡せます:

nb init --env app1 --yes \
  --db-dialect postgres \
  --db-schema public \
  --db-table-prefix nb_ \
  --db-underscored

#前回中断した初期化を続行する

nb init --env app1 --resume

#トラブルシューティング時に詳細ログを表示する

nb init --env app1 --yes --source docker --version latest --verbose

#関連コマンド

• nb env add
• nb env auth
• nb source download