diff --git a/docs/plugin-dev/compose-profiles.md b/docs/plugin-dev/compose-profiles.md index 84b147ca..b531328f 100644 --- a/docs/plugin-dev/compose-profiles.md +++ b/docs/plugin-dev/compose-profiles.md @@ -7,7 +7,7 @@ dev のほかに app / db などのサービスを持つプロジェクトで、 | 項目 | 条件 | | --- | --- | | Docker Compose | **2.20.0 以上**。`depends_on` の `required` を使うため。動作を確かめたのは v5.1.4 | -| devbase | `devbase project profile` があるバージョン | +| devbase | **3.5.0 以上**。`devbase project profile` が入った版です（CHANGELOG の `[3.5.0]`）。Plugin として配るなら [`plugin.yml` の `requires.devbase` も上げます](#plugin-として配るなら-requiresdevbase-を-350-以上へ上げる) | ## 1. `compose.yml` の書き方 @@ -43,6 +43,26 @@ services: プロファイル名に `__devbase_none__` は使わないでください。devbase が「どのプロファイルも有効にしない」ために予約している名前です。 +### Plugin として配るなら `requires.devbase` を 3.5.0 以上へ上げる + +`profiles:` を使うプロジェクトを含む Plugin は、`plugin.yml` の `requires.devbase` を +`">=3.5.0"` へ上げてください。`compose.yml` を書き換えたのと同じ Pull Request で上げます。 + +```yaml +# /plugin.yml +requires: + devbase: ">=3.5.0" +``` + +3.5.0 未満の devbase では、`profiles:` を付けたサービスが `devbase up` の起動対象から外れたまま、 +後から起動する手段（`devbase project profile up`）もありません。テスト用サーバ群が黙って起動 +しない状態になります。 + +`requires.devbase` を上げておけば、新規の `devbase plugin install` はその場で拒否され、 +`devbase plugin update` では警告が出ます。仕組みは既にあるため、Plugin 側でやることは版数を +書くことだけです。書式（必ずクォートする）と検証の詳細は +[`plugin.yml` リファレンスの `requires`](plugin-yml-reference.md#requires) を参照してください。 + ## 2. コマンド ```bash diff --git a/docs/plugin-dev/plugin-yml-reference.md b/docs/plugin-dev/plugin-yml-reference.md index 94a39fd5..44f91aa0 100644 --- a/docs/plugin-dev/plugin-yml-reference.md +++ b/docs/plugin-dev/plugin-yml-reference.md @@ -169,8 +169,15 @@ WARNING プラグイン 'carmo-web' は devbase >=4.0.0 を要求しています devbase 本体を更新してください (この警告を止める場合は DEVBASE_IGNORE_PLUGIN_REQUIRES=1)。 ``` -> `requires.devbase` を上げるのは、**Plugin が `project.yml` 形式へ移行したタイミング**です。 -> 本体の版数と一緒に自動では上がりません。 +> **`requires.devbase` は本体の版数と一緒に自動では上がりません。** 上げるのは、**Plugin が +> devbase の新しい機能に依存しはじめたタイミング**です。契機は次のとおりです。 +> +> | 契機 | 上げる版数 | +> | --- | --- | +> | Plugin が `project.yml` 形式へ移行した | その形式を読める版 | +> | Plugin のプロジェクトが `compose.yml` に `profiles:` を使う | `">=3.5.0"`（[テスト用サーバを後から起動・停止する](compose-profiles.md#plugin-として配るなら-requiresdevbase-を-350-以上へ上げる)） | +> +> どちらも、その機能を使い始めた Pull Request で一緒に上げます。 ### `priority` diff --git a/docs/specifications/compose-profiles.md b/docs/specifications/compose-profiles.md index b135ba5f..ed146e3f 100644 --- a/docs/specifications/compose-profiles.md +++ b/docs/specifications/compose-profiles.md @@ -193,7 +193,7 @@ subcommand より前に置く。`<サービス...>` はプロファイル X に `cli._dispatch` が `project profile list` を `project list`（プロジェクト一覧）へ流すためである - 前方一致の省略は `project p` / `container p` を従来どおり `ps` に解決し（`SUBCMD_PREFIX_PREFERENCES`）、 `project pr` は `profile` に解決する -- `bin/devbase` の `_PROJECT_NAME_SUBCOMMANDS`（`up down ps logs scale rebuild`）に `profile` は +- `bin/devbase` の `_PROJECT_NAME_SUBCOMMANDS`（`up down ps logs scale rebuild open`）に `profile` は 入れない。wrapper は 3 番目の引数をプロジェクト名として解決するが、`profile` ではそこに `up` / `down` / `list` が来るため、同名のプロジェクトが実在すると誤って移動する。名前の解決は Python 側の `_dispatch_lifecycle` が行う diff --git a/docs/specifications/remote-docker-context.md b/docs/specifications/remote-docker-context.md index d0f6a1e1..f428dfce 100644 --- a/docs/specifications/remote-docker-context.md +++ b/docs/specifications/remote-docker-context.md @@ -4,7 +4,7 @@ devbase は、プロジェクトごとの個人設定 `projects//project.local.yml` に docker context の 名前を書くと、そのプロジェクトの `up` / `down` / `ps` / `logs` / `login` / `scale` / `build` / -`rebuild` を別ホストの docker daemon へ向ける。compose クライアントと機密の復号は手元で行い、 +`rebuild` / `open` を別ホストの docker daemon へ向ける。compose クライアントと機密の復号は手元で行い、 daemon だけがリモートにある。リモートに要るのは docker CLI・dockerd・sshd で、devbase・ `projects/`・機密鍵をリモートへ複製しない。`devbase up` が開く VS Code は、attach URI の `settings.context` でそのホストのコンテナへ接続する。 @@ -40,8 +40,9 @@ daemon だけがリモートにある。リモートに要るのは docker CLI この段階では docker を呼ばない。 `--context` は `project` / `container` 配下の `up` / `down` / `ps` / `logs` / `login` / `scale` / -`build` / `rebuild`、トップレベルのショートカット `up` / `down` / `ps` / `login` / `scale` / -`build` / `rebuild`、および `env exec` が受け付ける。空文字と空白のみは終了コード 2 で拒む +`build` / `rebuild` / `open` / `profile up` / `profile down` / `profile list`、トップレベルの +ショートカット `up` / `down` / `ps` / `login` / `scale` / `build` / `rebuild` / `open`、および +`env exec` / `env token` が受け付ける。空文字と空白のみは終了コード 2 で拒む （Python の parser と `bin/devbase` の両方）。 ### リモート扱いの判定 diff --git a/docs/user/cli-reference/02-project.md b/docs/user/cli-reference/02-project.md index 126e7f81..9b1f44d5 100644 --- a/docs/user/cli-reference/02-project.md +++ b/docs/user/cli-reference/02-project.md @@ -6,7 +6,7 @@ ## プロジェクト名指定（CWD 非依存） -`up` / `down` / `ps` / `logs` / `scale` は省略可能な `[name]` 引数を取ります。`[name]` +`up` / `down` / `ps` / `logs` / `scale` / `rebuild` / `open` は省略可能な `[name]` 引数を取ります。`[name]` を指定すると、**現在のディレクトリに依存せず** `$DEVBASE_ROOT/projects/` を対象に 操作できます。 @@ -18,6 +18,13 @@ devbase project up adminer cd $DEVBASE_ROOT/projects/adminer && devbase project up ``` +> **`profile` も `[name]` を取りますが、解決の経路が違います。** `project profile up` / +> `profile down` / `profile list` は `[name]` を受け付けますが、`bin/devbase` の +> `_PROJECT_NAME_SUBCOMMANDS`（`up` / `down` / `ps` / `logs` / `scale` / `rebuild` / `open`） +> には入っていません。`profile` では 3 番目の引数に `up` / `down` / `list` が来るため、 +> ラッパーでは位置で名前を解決できないからです。名前の解決は Python 側の +> `_dispatch_lifecycle` が行います。 + - `` は `$DEVBASE_ROOT/projects/` 配下のプロジェクト名（`devbase project list` で確認可能） - 名前として受け付ける形は、英数字で始まり英数字・`.`・`-`・`_` だけからなる文字列です （`carmo`、`github_work_time`、`carmo-ai`、`carmo.takemi`）。`../etc` や `a/b` のように @@ -57,7 +64,7 @@ cd $DEVBASE_ROOT/projects/adminer && devbase project up ## `--context NAME`（共通オプション） -`up` / `down` / `ps` / `logs` / `login` / `scale` / `build` / `rebuild` / `profile`（`project` / +`up` / `down` / `ps` / `logs` / `login` / `scale` / `build` / `rebuild` / `open` / `profile`（`project` / `container` 配下と、トップレベルのショートカット）は `--context NAME` を受け付けます。 そのコマンドの `docker` / `docker compose` を、指定した docker context の daemon へ向けます。 diff --git a/docs/user/cli-reference/README.md b/docs/user/cli-reference/README.md index 5e88b450..0dfe1b74 100644 --- a/docs/user/cli-reference/README.md +++ b/docs/user/cli-reference/README.md @@ -5,7 +5,7 @@ devbase の全コマンドの構文、オプション、使用例をまとめた | ファイル | 内容 | |---------|------| | [トップレベルコマンド](01-toplevel.md) | `init` / `status` / `bin/rc` | -| [project グループ](02-project.md) | コンテナのライフサイクル管理・一覧（`up` / `down` / `login` / `ps` / `logs` / `scale` / `build` / `rebuild` / `list`）と非推奨の `container` グループ | +| [project グループ](02-project.md) | コンテナのライフサイクル管理・一覧（`up` / `down` / `login` / `ps` / `logs` / `scale` / `build` / `rebuild` / `open` / `profile` / `list`）と非推奨の `container` グループ | | [env グループ](03-env.md) | 環境変数の管理（`init` / `sync` / `list` / `set` / `get` / `delete` / `edit` / `project` / `keygen` / `encrypt` / `decrypt` / `exec` / `token` / `rekey` / `doctor` / `export` / `import`） | | [plugin グループ](04-plugin.md) | プラグインの管理（`list` / `install` / `uninstall` / `update` / `info` / `sync` / `migrate` / `repo *`） | | [snapshot グループ](05-snapshot.md) | スナップショットの管理（`create` / `list` / `restore` / `copy` / `delete` / `rotate`） | @@ -22,9 +22,10 @@ graph TD A --> E[env] A --> F[plugin / pl] A --> G[snapshot / ss] - D --> D1["up / down / ps / logs / scale [name]"] + D --> D1["up / down / ps / logs / scale / open [name]"] D --> D3["login [index]"] D --> D4["build [image] / rebuild [name]"] + D --> D5["profile up / down / list [name]"] D --> D2["list [--no-interactive]"] E --> E1[init / sync / list / set / get / delete / edit / project] E --> E2[keygen / encrypt / decrypt / exec / token / rekey / doctor] @@ -61,10 +62,16 @@ graph TD | `devbase ps [name]` | `devbase project ps [name]` | | `devbase scale [name] ` | `devbase project scale [name] ` | | `devbase rebuild [name]` | `devbase project rebuild [name]` | +| `devbase open [name]` | `devbase project open [name]` | | `devbase list` | `devbase project list` | > **Note:** `logs` はトップレベルシノニムを持ちません。`devbase project logs` を使用してください。 > +> **`profile` について:** `devbase project profile up|down|list` もトップレベルシノニムを持ちません。 +> `[name]` は受け付けますが、3 番目の引数に `up` / `down` / `list` が来るためラッパーでは位置で +> 解決できず、名前の解決は Python 側が行います。詳細は +> [project グループの「プロジェクト名指定」](02-project.md#プロジェクト名指定cwd-非依存)を参照してください。 +> > **※ `build` の転送先について:** `devbase build`（既定 / `--no-cache` / `--project-no-cache`）は他の > ショートカットのように `project` グループ（Python 実装）へ転送されるのではなく、`bin/devbase` の > シェル実装 `cmd_build` に直接委譲されます。base イメージの段階ビルド等を CWD で行う必要があるため diff --git a/docs/user/container-operations.md b/docs/user/container-operations.md index 2ad6018d..34c69a69 100644 --- a/docs/user/container-operations.md +++ b/docs/user/container-operations.md @@ -5,8 +5,10 @@ devbase のコンテナ管理機能について、ライフサイクル、並行 > **コマンド体系について:** コンテナ操作は `devbase project ` グループ（および > トップレベルショートカット `devbase up` 等）で行います。旧 `devbase container ` は > 非推奨となり、`project` へのエイリアスとして警告付きで当面動作します。`project` では -> `up` / `down` / `ps` / `logs` / `scale` に `[name]` を指定することで **任意のディレクトリ -> から** 対象プロジェクトを操作できます。プロジェクト一覧は `devbase project list` を参照 +> `up` / `down` / `ps` / `logs` / `scale` / `rebuild` / `open` に `[name]` を指定することで +> **任意のディレクトリから** 対象プロジェクトを操作できます。`profile up` / `profile down` / +> `profile list` も `[name]` を取りますが、ラッパーでは位置で解決できず Python 側が解決する +> 点が違います。プロジェクト一覧は `devbase project list` を参照 > してください。詳細は [CLI リファレンス: project グループ](cli-reference/02-project.md) を参照。 ## コンテナライフサイクル diff --git a/docs/user/environment-variables.md b/docs/user/environment-variables.md index 58f35cd8..8098bc57 100644 --- a/docs/user/environment-variables.md +++ b/docs/user/environment-variables.md @@ -368,8 +368,8 @@ DEVBASE_WINDOW_TITLE=0 `devbase up` は既定で **コマンドを実行した環境の Docker** にコンテナを立てます。 `projects//project.local.yml` に docker context の名前を書くと、そのプロジェクトの -`up` / `down` / `ps` / `logs` / `login` / `scale` / `build` / `rebuild` を**別ホストの daemon** -へ向けられます。用途は、CUDA が使える Windows（WSL2）の GPU、負荷分散のための 3 台目の PC、 +`up` / `down` / `ps` / `logs` / `login` / `scale` / `build` / `rebuild` / `open` を +**別ホストの daemon** へ向けられます。用途は、CUDA が使える Windows（WSL2）の GPU、負荷分散のための 3 台目の PC、 AWS EC2 の計算資源などです。 仕組みは「compose クライアントは手元、daemon はリモート」です。devbase・`projects/`・機密鍵を