diff --git a/CHANGELOG.md b/CHANGELOG.md index ae3f2c86..2431f348 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,8 +20,29 @@ DAYS 日（既定 7、`DEVBASE_IMAGE_MAX_AGE_DAYS` で上書き可）以上のときのみ no-cache で 再ビルドし、未満なら再ビルドしません（既存イメージを使用）。親イメージ（`FROM devbase-*`）の 作成日は独立して判定します。`devbase build` の `--no-cache` も明示フラグとして整理しました。 +- **外部リポジトリ連携プロジェクト向けドキュメント (`docs/plugin-dev/repo-backed-projects.md`)** + を追加しました。アプリ本体のリポジトリを共有 work ボリュームへ取り込み、複数コンテナで動かす + プロジェクトのための `pre-up` populate パターン（初回のみ populate し、2 回目以降はコンテナ側の + ソース・環境ファイルを上書きしない冪等スキップ）と、その設計意図・更新運用・チェックリストを + 解説しています。あわせて、本パターンが `CONTAINER_SCALE=1` 前提である理由（`pre-up` は + インデックスなしで 1 回しか実行されず、scale 生成で `/work` が差し替わるのは dev サービス + のみ）と、同一リポジトリの複数インスタンス分離が現行実装では未サポートである点、 + work ボリュームが全プロジェクト共有のグローバル external ボリュームであることを踏まえた + 安全な再 populate 手順（ボリュームごとではなく `/work/` サブディレクトリを削除） + も明記しています。 ### Changed +- **CLI リファレンス (`docs/user/cli-reference.md`) をコマンドグループ別ディレクトリ + (`docs/user/cli-reference/`) に分割**しました。目次 (`README.md`) とトップレベル / project / + env / plugin / snapshot の各ファイルに再編し、1 ファイルあたりの分量を抑えて目的のコマンドへ + 辿りやすくしました。ルート `README.md`（3 箇所）を含む他ドキュメントからの参照リンクも + 新パス (`docs/user/cli-reference/README.md`) へ更新しています。 +- **コンテナ操作ガイドの work ボリューム記述を実装に合わせて訂正**しました。 + `docs/user/container-operations.md` のボリューム表が `{project}_work_{index}` / + 「各コンテナ専用」となっていましたが、実際は project 接頭辞の付かない external ボリューム + `devbase_work_{index}` で、同じ index を使う限り**別プロジェクトからも同じ実体**を参照します。 + 表記を訂正し、`docker volume rm` が他プロジェクトの作業ファイルを巻き添えにする旨の注意も + 追記しました。 - **`build` / `rebuild` / `up` の再ビルド仕様を統一**しました (i07)。キャッシュの 扱いを 3 モード（既定=キャッシュビルド / `--no-cache`=無条件 no-cache / `--expires=N`= 期限切れ時のみ no-cache・期限内は再ビルドしない）に整理し、`devbase rebuild` を @@ -81,7 +102,7 @@ - `devbase project list` で `$DEVBASE_ROOT/projects/` 配下を `NAME` / `PLUGIN` / `STATUS` の一覧表示します。`PLUGIN` 列はシンボリックリンク先から解決するため、PLAN04 の同名衝突 suffix（例 `carmo.takemi`）が付いていても正しいプラグイン名を表示します。**TTY ではデフォルトで対話選択**になり、一覧から番号で選んだプロジェクトを `project up` で起動します。`--no-interactive`（`--plain` / `-P`）で一覧表示のみに切り替えられ、パイプ・リダイレクト・CI などの非 TTY 環境では自動的に一覧表示へフォールバックします（`--interactive` / `-i` は後方互換として引き続き受け付けます）。 - トップレベルシノニム `devbase up/down/ps/scale [name]` / `devbase build [image]` / `devbase login [index]` / `devbase list` を整備しました（`logs` はシノニムを持たず `devbase project logs` のみ）。 - bash / zsh のシェル補完に `project` グループとプロジェクト名補完（`$DEVBASE_ROOT/projects/` 配下を列挙）を追加しました。 - - 利用者向けドキュメント [`docs/user/cli-reference.md`](docs/user/cli-reference.md) / [`docs/user/container-operations.md`](docs/user/container-operations.md) を `project` 体系に更新しました。 + - 利用者向けドキュメント `docs/user/cli-reference.md`（現 [`docs/user/cli-reference/`](docs/user/cli-reference/README.md)） / [`docs/user/container-operations.md`](docs/user/container-operations.md) を `project` 体系に更新しました。 - `devbase env export` / `devbase env import` で **S3 URI (`s3://bucket/key`) を入出力先として指定**できるようになりました (PLAN03-1 PR3)。 - 既定でオブジェクト単位の SSE (`aws:kms` または `AES256`) を強制し、export 時はバケット側のデフォルト暗号化も `GetBucketEncryption` で事前確認します。 - 暗号化が未設定のバケットへ export する場合は `--unsafe-allow-unencrypted-bucket` の明示が必要です (オブジェクト単位の SSE はこのフラグに関係なく常に付与されます)。 diff --git a/README.md b/README.md index 3d08d0d3..c995ce06 100644 --- a/README.md +++ b/README.md @@ -119,11 +119,11 @@ devbaseのコマンドは4つのグループにまとめられています。 > **`container`（略記 `ct`）グループは非推奨です。** `devbase project ` のエイリアスとして当面動作しますが、非推奨警告を表示します。新しいコマンドは `project` を使用してください。 -- **ショートカット**: `up [name]`, `down [name]`, `login [index]`, `build [image]`, `ps [name]`, `scale [name] `, `rebuild [name]`, `list` はトップレベルから直接使用可能（`project` グループへ自動転送。`logs` はシノニムを持ちません）。なお `build` のみ挙動が一部異なります（詳細は [CLI リファレンス](docs/user/cli-reference.md#ショートカットコマンド)） +- **ショートカット**: `up [name]`, `down [name]`, `login [index]`, `build [image]`, `ps [name]`, `scale [name] `, `rebuild [name]`, `list` はトップレベルから直接使用可能（`project` グループへ自動転送。`logs` はシノニムを持ちません）。なお `build` のみ挙動が一部異なります（詳細は [CLI リファレンス](docs/user/cli-reference/README.md#ショートカットコマンド)） - **プレフィックス略記**: `devbase p l` → `devbase plugin list` - **トップレベルコマンド**: `init`, `status` -全コマンドの構文・オプション・使用例は [CLIリファレンス](docs/user/cli-reference.md) を参照してください。 +全コマンドの構文・オプション・使用例は [CLIリファレンス](docs/user/cli-reference/README.md) を参照してください。 ## 前提条件 @@ -142,7 +142,7 @@ devbaseのコマンドは4つのグループにまとめられています。 | ドキュメント | 内容 | |-------------|------| | [はじめに](docs/user/getting-started.md) | 前提条件、初回セットアップ、日常ワークフロー | -| [CLIリファレンス](docs/user/cli-reference.md) | 全コマンドの構文・オプション・使用例 | +| [CLIリファレンス](docs/user/cli-reference/README.md) | 全コマンドの構文・オプション・使用例（コマンドグループ別） | | [プラグインレジストリ](docs/user/plugin-registries.md) | 公開・社内レジストリの一覧と追加方法 | | [環境変数ガイド](docs/user/environment-variables.md) | 3レベル構造、コレクター、ソース同期 | | [環境変数の export/import ガイド](docs/user/env-export-import.md) | バンドル形式・age 暗号化・S3 連携・merge/replace の運用 | diff --git a/docs/README.md b/docs/README.md index 182e3ca4..eae57239 100644 --- a/docs/README.md +++ b/docs/README.md @@ -43,7 +43,7 @@ graph TD | ドキュメント | 内容 | |-------------|------| | [はじめに](user/getting-started.md) | 前提条件、初回セットアップ、日常ワークフロー | -| [CLI リファレンス](user/cli-reference.md) | 全コマンドの構文・オプション・使用例 | +| [CLI リファレンス](user/cli-reference/README.md) | 全コマンドの構文・オプション・使用例 | | [プラグインレジストリ](user/plugin-registries.md) | 公開・社内レジストリの一覧と追加方法 | | [環境変数ガイド](user/environment-variables.md) | 3レベル構造、コレクター、ソース同期 | | [コンテナ操作ガイド](user/container-operations.md) | ライフサイクル、並行開発、ボリューム構造 | @@ -73,6 +73,7 @@ graph LR | [プラグイン開発クイックスタート](plugin-dev/quickstart.md) | 最小構成プラグインの作成手順 | | [plugin.yml リファレンス](plugin-dev/plugin-yml-reference.md) | プラグイン定義ファイルの全フィールド | | [compose.yml ガイドライン](plugin-dev/compose-yml-guidelines.md) | Docker Compose 設定のベストプラクティス | +| [repo 連携プロジェクトと pre-up populate](plugin-dev/repo-backed-projects.md) | 外部リポジトリを共有 work ボリュームへ populate する `pre-up` パターンと冪等スキップ | ### devbase 開発者（devbase 本体を改善したい方） @@ -91,7 +92,13 @@ docs/ ├── README.md ← このファイル（ドキュメント索引） ├── user/ ← 利用者向け │ ├── getting-started.md ← はじめに -│ ├── cli-reference.md ← CLI リファレンス +│ ├── cli-reference/ ← CLI リファレンス（コマンドグループ別） +│ │ ├── README.md ← 目次・コマンド体系 +│ │ ├── 01-toplevel.md ← init / status / rc +│ │ ├── 02-project.md ← project グループ +│ │ ├── 03-env.md ← env グループ +│ │ ├── 04-plugin.md ← plugin グループ +│ │ └── 05-snapshot.md ← snapshot グループ │ ├── plugin-registries.md ← プラグインレジストリ │ ├── environment-variables.md ← 環境変数ガイド │ ├── container-operations.md ← コンテナ操作ガイド @@ -100,7 +107,8 @@ docs/ ├── plugin-dev/ ← プラグイン開発者向け │ ├── quickstart.md ← クイックスタート │ ├── plugin-yml-reference.md ← plugin.yml リファレンス -│ └── compose-yml-guidelines.md ← compose.yml ガイドライン +│ ├── compose-yml-guidelines.md ← compose.yml ガイドライン +│ └── repo-backed-projects.md ← repo 連携 / pre-up populate パターン └── developer/ ← devbase 開発者向け ├── architecture.md ← アーキテクチャ ├── contributing.md ← コントリビューション @@ -114,7 +122,7 @@ docs/ | やりたいこと | 参照先 | |-------------|--------| | devbase を初めてインストールする | [はじめに](user/getting-started.md#セットアップ手順) | -| コマンドの使い方を調べる | [CLI リファレンス](user/cli-reference.md) | +| コマンドの使い方を調べる | [CLI リファレンス](user/cli-reference/README.md) | | 環境変数を設定する | [環境変数ガイド](user/environment-variables.md#環境変数の操作) | | 複数コンテナで並行開発する | [コンテナ操作ガイド](user/container-operations.md#並行開発) | | データをバックアップ・復元する | [スナップショットガイド](user/snapshot-guide.md) | diff --git a/docs/plugin-dev/quickstart.md b/docs/plugin-dev/quickstart.md index ad15db86..e607daae 100644 --- a/docs/plugin-dev/quickstart.md +++ b/docs/plugin-dev/quickstart.md @@ -148,6 +148,8 @@ fi > **Note:** どちらのフックも `bash` で実行されます。`chmod +x` で実行可能ビットを立てておいてください。`pre-up` が非ゼロ終了すると `devbase up` は中断します。`deploy` は各インスタンスに対して `DEVBASE_INSTANCE_INDEX` を環境変数として渡しますが、失敗してもデプロイは続行されます。 +> **応用:** 外部リポジトリを共有 work ボリュームへ取り込み、app / nginx / db など複数コンテナで動かすプロジェクトでは、`pre-up` で clone/pull と work ボリュームへの populate を行い、2 回目以降はコンテナ側を上書きしないよう冪等にスキップするのが定石です。詳細は [repo 連携プロジェクトと pre-up populate パターン](repo-backed-projects.md) を参照してください。 + --- ## 3. ローカルでの開発・テスト diff --git a/docs/plugin-dev/repo-backed-projects.md b/docs/plugin-dev/repo-backed-projects.md new file mode 100644 index 00000000..ae1c61a8 --- /dev/null +++ b/docs/plugin-dev/repo-backed-projects.md @@ -0,0 +1,211 @@ +# repo 連携プロジェクトと `pre-up` populate パターン + +外部リポジトリ（アプリ本体）を丸ごと取り込み、複数コンテナ（app / nginx / db 等）で共有して動かすタイプのプロジェクト向けのガイドです。`pre-up` ライフサイクルフックで **ホスト側リポジトリの clone/pull** と **共有 work ボリュームへの populate** を行い、2 回目以降の `devbase up` では populate 済みを検出して同期をスキップする冪等パターンを解説します。 + +リファレンス実装は Laravel Sail ベースの `carmo-system-console` プラグインです。**このリポジトリには含まれません** — 社内向けの private プラグインレジストリで配布されており、`devbase plugin install` 後に `projects/carmo-system-console/`（`projects/` は `.gitignore` 対象）へ展開されます。アクセス権が無い場合でも、本書のコード断片と [チェックリスト](#7-チェックリスト新規に-repo-連携プロジェクトを作るとき) だけでパターンを再現できます。 + +> **前提:** ライフサイクルフック自体の基本は [プラグイン開発クイックスタート](quickstart.md#25-ライフサイクルフック任意) を、共有ボリュームや `CONTAINER_SCALE` の一般論は [compose.yml ガイドライン](compose-yml-guidelines.md) と [コンテナ操作ガイド](../user/container-operations.md#並行開発) を参照してください。本書はそれらを組み合わせた「repo 連携」パターンに絞って説明します。 + +--- + +## 1. なぜこのパターンが必要か + +`devbase-general` / `devbase-php` のような単一 dev コンテナのプロジェクトでは、各コンテナが専用の `/work` ボリュームを持ち、ソースはコンテナ内で `git clone` すれば十分です。 + +一方で、アプリ本体のリポジトリに付属する `docker-compose.dev.yml` 相当（app / nginx / mysql / redis …）を devbase 上で再現したい場合、次の要件が生じます。 + +- **複数コンテナが同一のソースツリーを共有**する必要がある（app が書いた成果物を nginx が配信する等）。 +- app サービスは **リポジトリ内の `Dockerfile` をビルドコンテキスト**として使うため、ホスト側にソースの実体が必要。 +- コンテナ内 `git clone` に頼ると、複数コンテナの起動順で **clone レース**が起きる。 + +これを解決するのが「ホスト `repo/` を用意し、それを共有 work ボリュームへ populate してから全コンテナを起動する」パターンです。populate を `pre-up`（`docker compose up` の前）に寄せることで、app / nginx / mysql が立ち上がる前にソースを確定できます。 + +--- + +## 2. 全体構成 + +```mermaid +graph TD + S["リモート git リポジトリ
(volareinc/app 等)"] -->|"pre-up ① clone/pull"| R["ホスト ./repo
(app のビルドコンテキスト)"] + S3["S3
env/<env>.env"] -->|"pre-up ② 取得"| E["ホスト ./.env
(compose 変数展開用)"] + R -->|"pre-up ③ populate"| V["共有 work ボリューム
/work/<GIT_REPO>"] + E -->|"pre-up ④ 配置"| V + V --> A["app コンテナ /work"] + V --> N["nginx コンテナ /work:ro"] + V --> M["mysql コンテナ /work:ro"] + V --> D["dev コンテナ /work"] +``` + +| 要素 | 実体 | 役割 | +|------|------|------| +| ホスト `./repo` | `git clone` した作業コピー | app イメージのビルドコンテキスト兼、work ボリュームの populate 元 | +| ホスト `./.env` | S3 から取得 | `docker compose` の変数展開（`${DB_DATABASE}` 等）に使用 | +| 共有 work ボリューム | `external: true` の named volume | 全コンテナが `/work` にマウントする実行時ソース | + +`compose.yml` では work ボリュームを **external** として宣言し、インスタンスごとに名前を切り替えます。 + +```yaml +services: + app: + build: + context: ./repo # ← ホスト repo/ をビルドコンテキストに + dockerfile: docker/Dockerfile + volumes: + - work:/work # ← 共有 work ボリューム + nginx: + volumes: + - work:/work:ro + # ... +volumes: + work: + external: true + name: ${DEVBASE_WORK_VOLUME:-devbase_work_${DEVBASE_INSTANCE_INDEX:-1}} +``` + +> **Note:** `pre-up` は子プロセスのため `export DEVBASE_WORK_VOLUME` しても後続の `docker compose up` へは伝播しません。`compose.yml` 側は `${DEVBASE_WORK_VOLUME:-devbase_work_${DEVBASE_INSTANCE_INDEX:-1}}` のフォールバック式で解決し、加えて `pre-up` が同じ値を `.env` に書き出すことで整合を取ります。 + +### スケール前提: `CONTAINER_SCALE=1` + +**このパターンは scale=1（1 プロジェクト = 1 work ボリューム）を前提としています。** devbase の既定は `CONTAINER_SCALE=2` なので、プロジェクトの `env` に `CONTAINER_SCALE=1` を明示してください。 + +現行実装では、scale>1 にすると「全コンテナが同一のソースツリーを共有する」という本パターンの前提が次の 2 点で崩れます。 + +- **`pre-up` はインデックスなしで 1 回しか実行されない。** devbase が `DEVBASE_INSTANCE_INDEX` を環境変数として渡すのは、インスタンスごとに実行される `deploy` フックだけです。`pre-up` には渡らないため、populate されるのは `.env`（または既定値 `1`）で解決される **単一の work ボリュームのみ**で、`devbase_work_2` 以降は空のまま残ります。 +- **scale 生成が書き換えるのは dev サービスの `/work` だけ。** `.docker-compose.scale.yml` の生成では `dev-` の `/work` マウントが `devbase_work_` へ固定で差し替えられる一方、app / nginx / mysql などの非 dev サービスは `compose.yml` に書いた共有 work ボリュームを参照し続けます。結果として dev-2 以降だけが別（空の）ボリュームを見ることになります。 + +さらに、**同一リポジトリを複数インスタンスへ分離して並行稼働させることは現行実装では未サポート**です。回避策として思いつく 2 つの手はいずれも成立しません。 + +- **`DEVBASE_WORK_VOLUME` で名前を分ける。** scale 生成は dev サービスの `/work` を `devbase_work_`（scale=1 なら常に `devbase_work_1`）へ無条件に差し替えます（`compose.yml` に `/work` マウントを書いていなくても追加されます）。`DEVBASE_WORK_VOLUME` が効くのは app / nginx など非 dev サービスだけなので、既定名以外を指定すると dev だけが別ボリュームを見る分裂状態になります。 +- **プロジェクトディレクトリごと複製する。** work ボリュームは `COMPOSE_PROJECT_NAME` の接頭辞が付かない[グローバルな external ボリューム](#クリーンに作り直す再-populate)なので、複製先も同じ `devbase_work_1` を共有します。分離になりません。 + +同一リポジトリを同時に複数環境で動かす必要がある場合は、Docker ホスト（`docker context`）そのものを分けてください。なお **別リポジトリ**の repo 連携プロジェクト同士は、populate 先が `/work/` とサブディレクトリで分かれるため、同じ work ボリュームを共有したまま共存できます。 + +--- + +## 3. `pre-up` の 4 つの責務 + +`pre-up` は毎回の `devbase up` 前に次を行います。 + +| # | 処理 | 内容 | +|---|------|------| +| ① | `repo/` の clone / pull | 無ければ `git clone`、あれば `git pull --ff-only`（app ビルドコンテキストの最新化） | +| ② | `.env` の取得 | S3 等から取得してホスト `./.env` に配置（`docker compose` の変数展開前に必要） | +| ③ | work ボリュームへ populate | `repo/` の内容を `/work/` へコピー | +| ④ | `.env` を work ボリュームへ配置 | Laravel 等のランタイムが `/work//.env` を参照するため | + +② を `deploy`（`up` 後フック）ではなく `pre-up` で行うのは、`compose.yml` の `MYSQL_DATABASE: ${DB_DATABASE:-...}` のような変数展開が `docker compose` パース時（＝ MySQL コンテナ初回起動前）に `.env` を要求するためです。`deploy` 段階では間に合わず、DB がデフォルト名で初期化されてしまいます。 + +--- + +## 4. 冪等性 — populate 済みならスキップ（重要） + +**このパターンの肝は「初回だけ populate し、2 回目以降はコンテナ側に触れない」ことです。** + +`pre-up` は work ボリューム上に `/work//.git` が存在するかどうかで populate 済みを判定し、済みの場合は ②③④ をスキップします。 + +| # | 処理 | 未populate（初回） | populate 済み（2回目以降） | +|---|------|:---:|:---:| +| ① | `repo/` の `git pull` | 実行 | **実行**（構成変更をビルドに追従） | +| ② | `.env` の S3 取得 | 実行 | スキップ | +| ③ | ソース populate | 実行 | スキップ | +| ④ | `.env` を volume へ配置 | 実行 | スキップ | + +### なぜスキップするのか + +populate 済みの work ボリュームを毎回ホスト `repo/` で上書き同期すると、次の破壊が起きます。 + +- **同期の除外リスト（`storage/` / `vendor/` / `node_modules/` / `.env` 等）に無いファイルが消える。** コンテナ内で生成した認証ファイルや作業ファイルが `devbase up` のたびに削除される。 +- **コンテナ側で編集した `.env` が上書きされる。** + +これを避けるため、実行時ソースと `.env` の供給は初回 populate 時に限定し、以降はコンテナ側を手動管理に委ねます。これはアプリ本体リポジトリが取る一般的な開発フローと同じ考え方です。多くのリポジトリでは、環境ファイルの取得やソースの用意は**ビルド時のセットアップスクリプト**が担い、日常の**起動（`docker compose up`）は環境ファイルやソースに触れません**。devbase の初回 populate がこのビルド時セットアップに相当し、2 回目以降の `up` は起動だけを行います。 + +一方で ①（`repo/` の pull）は常に実行します。これはホスト側のビルドコンテキストであり、`compose.yml` / `Dockerfile` / `docker/` 構成の変更を次回の app イメージ再ビルドへ反映するためです（アプリのソースコードそのものは work ボリューム側で管理）。 + +--- + +## 5. ソース・`.env` の更新運用 + +populate 済み以降、更新経路は次のように分かれます。 + +| 対象 | 場所 | 更新方法 | +|------|------|---------| +| ビルドコンテキスト | ホスト `./repo` | `pre-up` が毎回 `git pull`（自動） | +| 実行時ソース | work ボリューム `/work/` | **コンテナ内で手動 `git pull`** | +| 実行時 `.env` | work ボリューム `/work//.env` | コンテナ内で手動編集 | + +```bash +# 実行時ソースの更新（dev コンテナ内） +cd /work/ +git pull origin main +``` + +### クリーンに作り直す（再 populate） + +`.env` やソースを S3 / `repo/` の内容からやり直したい場合は、populate 済み判定に使われる `/work/` を消して、次回 `up` で populate を再実行させます。 + +> **Warning:** work ボリューム（既定 `devbase_work_1`）は `COMPOSE_PROJECT_NAME` の接頭辞が付かない **グローバルな external ボリューム**で、同じインスタンス index を使う **すべての devbase プロジェクトが共有**します。`docker volume rm` でボリュームごと消すと、停止中の別プロジェクトのソースや生成物まで巻き添えで失われます。プロジェクトの分離単位はボリュームではなく `/work/` サブディレクトリなので、**通常はサブディレクトリだけを削除**してください。 + +**推奨: このプロジェクトのサブディレクトリだけを削除する** + +```bash +devbase down + +# 何が入っているか（＝他プロジェクトが同居していないか）を確認 +docker run --rm -v devbase_work_1:/work alpine ls -la /work + +# このプロジェクトのソースだけを削除（ は env の値） +docker run --rm -v devbase_work_1:/work alpine rm -rf /work/ + +devbase up # pre-up が ②③④ を再実行 +``` + +**ボリュームごと作り直す場合**（他プロジェクトが同じ work ボリュームを使っていないことを確認してから） + +```bash +devbase down + +# このボリュームをマウントしているコンテナを列挙（停止中も含む） +docker ps -a --filter volume=devbase_work_1 --format '{{.Names}}' + +docker volume rm devbase_work_1 # external volume のため project 名の接頭辞は付かない + # DEVBASE_WORK_VOLUME を設定している場合はその名前 +devbase up +``` + +> **Note:** どちらの手順でも、削除前にコンテナ内で加えた変更（未コミットのソース変更、編集した `.env`）をコミット / 退避してください。DB 等の `sail-*` ボリュームは別管理なので、work ボリュームを消してもデータは残ります。 + +--- + +## 6. 関連する環境変数 + +| 変数 | 既定 | 効果 | +|------|------|------| +| `DEVBASE_REPO_PULL` | `1` | `0` にすると ①（`repo/` の `git pull`）を抑止。オフラインや意図的にビルドコンテキストを固定したいとき | +| `DEVBASE_ENV_OVERWRITE` | `backup` | 未 populate 時の既存ホスト `.env` の扱い。`backup`（`.env.bak.` に退避して上書き）/ `skip`（既存があれば S3 取得しない）/ `force`（退避せず上書き） | +| `DEVBASE_WORK_VOLUME` | `devbase_work_` | `compose.yml` が参照する共有 work ボリューム名の明示指定。未指定なら `DEVBASE_INSTANCE_INDEX` から解決。ただし効くのは **app / nginx など非 dev サービスだけ**で、dev サービスの `/work` は scale 生成時に `devbase_work_` へ無条件に差し替えられます。dev から実行時ソースを触る本パターンでは **既定名のまま**にしてください（[スケール前提](#スケール前提-container_scale1) を参照） | +| `DEVBASE_INSTANCE_INDEX` | `1` | work ボリューム名のインデックス。**devbase 本体が渡すのは `deploy` フックに対してのみ**で、`pre-up` や `docker compose` のプロセス環境には渡りません。`compose.yml` の `${DEVBASE_INSTANCE_INDEX:-1}` は `.env` に書かれた値、無ければ `1` に解決されます（[スケール前提](#スケール前提-container_scale1) を参照） | + +> **Note:** `.env` の環境選択（例: `s3://.../env/local.env` の `local` 部分）など、S3 パスやプロファイルはプロジェクト固有の変数（例: `CARMO_ENV`）で制御することがあります。プロジェクトの `pre-up` 冒頭コメントを参照してください。 + +--- + +## 7. チェックリスト（新規に repo 連携プロジェクトを作るとき） + +- [ ] `env` に `GIT_USER` / `GIT_REPO` を定義した +- [ ] `env` に `CONTAINER_SCALE=1` を明記した（既定は `2`。[スケール前提](#スケール前提-container_scale1) を参照） +- [ ] `compose.yml` で work ボリュームを `external: true` + `name: ${DEVBASE_WORK_VOLUME:-devbase_work_${DEVBASE_INSTANCE_INDEX:-1}}` で宣言した +- [ ] app サービスの `build.context` をホスト `./repo` にした +- [ ] `pre-up` で ①clone/pull → ②`.env`取得 → ③populate → ④`.env`配置 を実装した +- [ ] `pre-up` が `/work//.git` の有無で populate 済みを判定し、②③④ をスキップする +- [ ] populate 時の owner を `1000:1000`（コンテナ内ユーザー）に設定した +- [ ] `storage/` / `vendor/` / `node_modules/` 等、初回のみ生成され上書きしたくないパスの扱いを決めた +- [ ] README にソース・`.env` の更新運用（手動 pull / 再 populate）を記載した + +--- + +## 参考 + +- リファレンス実装: `carmo-system-console` プラグインの `pre-up` / `compose.yml` / `README.md`（社内 private レジストリ配布。インストール後は `projects/carmo-system-console/` 配下に展開され、このリポジトリには含まれません） +- [プラグイン開発クイックスタート](quickstart.md) — ライフサイクルフックの基本 +- [compose.yml ガイドライン](compose-yml-guidelines.md) — 共有ボリューム・スケール構成 +- [コンテナ操作ガイド](../user/container-operations.md) — `/work` ボリュームの一般論 diff --git a/docs/user/cli-reference/01-toplevel.md b/docs/user/cli-reference/01-toplevel.md new file mode 100644 index 00000000..f9e06b83 --- /dev/null +++ b/docs/user/cli-reference/01-toplevel.md @@ -0,0 +1,41 @@ +# トップレベルコマンド + +[CLI リファレンス目次に戻る](README.md) + +## `devbase init` + +devbase の初期セットアップを実行します。 + +``` +devbase init +``` + +実行内容: +- `bin/devbase` を PATH に追加（`~/.bashrc` / `~/.zshrc`） +- シェル補完スクリプトの登録 +- `plugins.yml` の作成（存在しない場合） + +## `devbase status` + +現在の環境の状態をまとめて表示します。 + +``` +devbase status +``` + +表示項目: +- コンテナの状態（起動中 / 停止中 / 未ビルド） +- インストール済みプラグイン一覧 +- 環境変数の設定状況 +- スナップショットの状態 + +## `bin/rc`（いまのシェルで有効化） + +`devbase init` 後に **いま開いているシェル**で devbase（PATH / 補完）を即時有効化するための source 用スクリプトです。`devbase` のサブコマンドではなく、`bin/rc` を直接 source して使います。 + +```bash +./bin/devbase init +. ./bin/rc # = source ./bin/rc （bash / zsh 共通） +``` + +`bin/rc` は自身の場所から `DEVBASE_ROOT` を解決し、`DEVBASE_ROOT/bin` を PATH へ追加（冪等）したうえで、シェル補完を読み込みます（`init` が rc ファイルへ追記する有効化と同じ内容）。新しく開くシェルは init が rc に追記したブロックで自動有効化されるため、この手順は不要です。 diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference/02-project.md similarity index 51% rename from docs/user/cli-reference.md rename to docs/user/cli-reference/02-project.md index 9fb90f23..1f2ae9e0 100644 --- a/docs/user/cli-reference.md +++ b/docs/user/cli-reference/02-project.md @@ -1,125 +1,10 @@ -# CLI リファレンス - -devbase の全コマンドの構文、オプション、使用例をまとめたリファレンスです。 - -## コマンド体系 - -devbase のコマンドは 4 つのグループとトップレベルコマンドで構成されています。 - -```mermaid -graph TD - A[devbase] --> B[init] - A --> C[status] - A --> D[project] - A --> E[env] - A --> F[plugin / pl] - A --> G[snapshot / ss] - D --> D1["up / down / ps / logs / scale [name]"] - D --> D3["login [index]"] - D --> D4["build [image] / rebuild [name]"] - D --> D2["list [--no-interactive]"] - E --> E1[init / sync / list / set / get / delete / edit / project / export / import] - F --> F1[list / install / uninstall / update / info / sync / migrate] - F --> F2[repo add / repo remove / repo list / repo refresh] - G --> G1[create / list / restore / copy / delete / rotate] -``` - -> **`container` グループは非推奨になりました。** 旧 `devbase container ` は -> `devbase project ` のエイリアスとして当面動作しますが、実行時に非推奨警告を -> 表示します（移行期間後のリリースで削除予定）。新しいコマンドは `project` を使用してください。 - -### グループエイリアス - -各グループには短縮形が用意されています。 - -| グループ名 | エイリアス | 備考 | -|-----------|-----------|------| -| `plugin` | `pl` | | -| `snapshot` | `ss` | | -| `container` | `ct` | **非推奨**（`project` へ移行してください） | - -### ショートカットコマンド - -頻繁に使用するプロジェクト操作はトップレベルから直接実行できます。これらは `project` グループに自動転送されます。 - -| ショートカット | 転送先 | -|--------------|--------| -| `devbase up [name]` | `devbase project up [name]` | -| `devbase down [name]` | `devbase project down [name]` | -| `devbase login [index]` | `devbase project login [index]` | -| `devbase build [image]` | `bin/devbase` の `cmd_build`（シェル実装）※ | -| `devbase ps [name]` | `devbase project ps [name]` | -| `devbase scale [name] ` | `devbase project scale [name] ` | -| `devbase rebuild [name]` | `devbase project rebuild [name]` | -| `devbase list` | `devbase project list` | - -> **Note:** `logs` はトップレベルシノニムを持ちません。`devbase project logs` を使用してください。 -> -> **※ `build` の転送先について:** `devbase build`（既定 / `--no-cache` / ``）は他の -> ショートカットのように `project` グループ（Python 実装）へ転送されるのではなく、`bin/devbase` の -> シェル実装 `cmd_build` に直接委譲されます。base イメージの段階ビルド等を CWD で行う必要があるため -> です（名前指定はラッパーの `cd` で解決）。ただし `devbase build --expires[=DAYS]` のみ、作成日の -> 判定が必要なため例外的に Python 経路（`project build`）へ委譲されます。挙動上の入出力は同等です。 - -### ユニークプレフィックスマッチング - -コマンド名が一意に特定できる場合、先頭の数文字だけで実行できます。 - -```bash -# 以下は全て同じコマンド -devbase plugin list -devbase pl list -devbase p l -devbase pl l -``` - -> **Note:** 一意に特定できない場合は候補が表示されます。 - -## トップレベルコマンド - -### `devbase init` - -devbase の初期セットアップを実行します。 - -``` -devbase init -``` - -実行内容: -- `bin/devbase` を PATH に追加（`~/.bashrc` / `~/.zshrc`） -- シェル補完スクリプトの登録 -- `plugins.yml` の作成（存在しない場合） - -### `devbase status` - -現在の環境の状態をまとめて表示します。 - -``` -devbase status -``` - -表示項目: -- コンテナの状態（起動中 / 停止中 / 未ビルド） -- インストール済みプラグイン一覧 -- 環境変数の設定状況 -- スナップショットの状態 - -### `bin/rc`（いまのシェルで有効化） +# project グループ -`devbase init` 後に **いま開いているシェル**で devbase（PATH / 補完）を即時有効化するための source 用スクリプトです。`devbase` のサブコマンドではなく、`bin/rc` を直接 source して使います。 - -```bash -./bin/devbase init -. ./bin/rc # = source ./bin/rc （bash / zsh 共通） -``` - -`bin/rc` は自身の場所から `DEVBASE_ROOT` を解決し、`DEVBASE_ROOT/bin` を PATH へ追加（冪等）したうえで、シェル補完を読み込みます（`init` が rc ファイルへ追記する有効化と同じ内容）。新しく開くシェルは init が rc に追記したブロックで自動有効化されるため、この手順は不要です。 - -## project グループ +[CLI リファレンス目次に戻る](README.md) プロジェクト（コンテナ）のライフサイクル管理と一覧表示を行うコマンド群です。 -### プロジェクト名指定（CWD 非依存） +## プロジェクト名指定（CWD 非依存） `up` / `down` / `ps` / `logs` / `scale` は省略可能な `[name]` 引数を取ります。`[name]` を指定すると、**現在のディレクトリに依存せず** `$DEVBASE_ROOT/projects/` を対象に @@ -155,7 +40,7 @@ cd $DEVBASE_ROOT/projects/adminer && devbase project up > トレードオフです。**回避策:** 衝突する場合は対象プロジェクトのディレクトリ内で実行するか、 > 明示的にそのプロジェクトへ切り替えてから（`cd` 済みの状態で）コマンドを実行してください。 -### `devbase project up` +## `devbase project up` コンテナを起動します。 @@ -186,7 +71,7 @@ devbase up [name] > ことがあります。確実に反映するには **`devbase build [name] --no-cache`** で再ビルドしてから > `devbase up` してください（`--no-cache` は `build` のオプションで、`rebuild` にはありません）。 -### `devbase project down` +## `devbase project down` コンテナを停止・削除します。 @@ -197,7 +82,7 @@ devbase down [name] - 停止時にスナップショットのローテーションを自動実行 -### `devbase project login` +## `devbase project login` コンテナにログインします。 @@ -218,7 +103,7 @@ devbase login devbase login 2 ``` -### `devbase project ps` +## `devbase project ps` 対象プロジェクトのコンテナ状態を `docker compose ps` で表示します。複数プロジェクトの 横断一覧は `devbase project list` を使用してください。 @@ -232,7 +117,7 @@ devbase ps [name] [-a] |-----------|------| | `-a` | 停止中のコンテナも表示 | -### `devbase project logs` +## `devbase project logs` コンテナのログを表示します（トップレベルシノニムはありません）。 @@ -250,7 +135,7 @@ devbase project logs [name] [-f] [--tail N] devbase project logs -f --tail 50 ``` -### `devbase project scale` +## `devbase project scale` 既存のコンテナを再起動せずにスケールします。 @@ -272,7 +157,7 @@ devbase project scale 3 devbase project scale adminer 3 ``` -### `devbase project build` +## `devbase project build` コンテナイメージをビルドします。キャッシュの扱いは 3 モードあります。 @@ -297,7 +182,7 @@ devbase build [image] [--no-cache | --expires[=DAYS]] > 単体ビルドでは `--no-cache` のみ反映され、`--expires` は対象外です。`--expires` 付きビルドは > 作成日判定のため Python 経路（`project build`）で処理されます。 -### `devbase project rebuild` +## `devbase project rebuild` `devbase build --expires=7` のシノニムです（既定 7 日）。プロジェクトイメージが 7 日以上古ければ no-cache で再ビルドし、未満なら再ビルドしません（既存イメージを使用）。親イメージ（`FROM devbase-*`）の @@ -312,7 +197,7 @@ devbase rebuild [name] |-----------|------|------| | `name` | いいえ | 対象プロジェクト名（省略時はカレント） | -### `devbase project list` +## `devbase project list` `$DEVBASE_ROOT/projects/` 配下のプロジェクトを `NAME` / `PLUGIN` / `STATUS` の一覧で 表示します。 @@ -332,7 +217,7 @@ devbase list [--no-interactive|--plain|-P] | `--no-interactive` / `--plain` / `-P` | TUI を起動せず一覧表示のみ | | `--interactive` / `-i` | （後方互換）TUI 起動。デフォルトのため通常は不要 | -#### TUI の画面構成とキー操作 +### TUI の画面構成とキー操作 ``` ? プロジェクトまたは操作を選択 (↑↓ 移動 / 名前で絞り込み / ←→ 下部メニュー / Enter 決定 / Esc・Ctrl-C 終了): @@ -406,335 +291,3 @@ devbase container up devbase project up devbase up ``` - -## env グループ - -環境変数の管理を行うコマンド群です。詳細は [環境変数ガイド](environment-variables.md) を参照してください。 - -### `devbase env init` - -環境変数の対話式初期セットアップを実行します。 - -``` -devbase env init [--reset] -``` - -| オプション | 説明 | -|-----------|------| -| `--reset` | 既存の設定をリセットして再設定 | - -### `devbase env sync` - -ソースファイル（`~/.aws/config` 等）の変更を検出し、環境変数を再同期します。 - -``` -devbase env sync -``` - -### `devbase env list` - -設定済みの環境変数を一覧表示します。 - -``` -devbase env list [-g|-p] [-r] [-k] -``` - -| オプション | 説明 | -|-----------|------| -| `-g` | グローバル変数のみ表示 | -| `-p` | プロジェクト変数のみ表示 | -| `-r` | 値も表示（デフォルトではキーのみ） | -| `-k` | キー名でソート | - -```bash -# グローバル変数のみ、値付きで表示 -devbase env list -g -r - -# プロジェクト変数をキー名順で表示 -devbase env list -p -k -``` - -### `devbase env set` - -環境変数を設定します。 - -``` -devbase env set KEY=VALUE [-p] -``` - -| オプション | 説明 | -|-----------|------| -| `-p` | プロジェクトレベルに設定（デフォルトはグローバル） | - -```bash -# グローバルに設定 -devbase env set ANTHROPIC_API_KEY=sk-xxx - -# プロジェクトレベルに設定 -devbase env set GCP_ACTIVE_PROFILE=my-project -p -``` - -### `devbase env get` - -環境変数の値を取得します。 - -``` -devbase env get KEY -``` - -```bash -devbase env get AWS_PROFILE -``` - -### `devbase env delete` - -環境変数を削除します。 - -``` -devbase env delete KEY -``` - -### `devbase env edit` - -デフォルトエディタで `.env` ファイルを開きます。 - -``` -devbase env edit -``` - -### `devbase env project` - -プロジェクト固有の環境変数を対話式で設定します。 - -``` -devbase env project -``` - -### `devbase env export` - -複数プロジェクトの `.env` 群を暗号化したまま 1 つのバンドルにまとめて書き出します。 - -``` -devbase env export -``` - -オプション（age 鍵 / passphrase / S3 入出力など）の詳細は -[環境変数の export / import ガイド](env-export-import.md#devbase-env-export-リファレンス)を参照してください。 - -### `devbase env import` - -`devbase env export` で作成したバンドルを復号し、環境変数を取り込みます。 - -``` -devbase env import -``` - -`--dry-run` での確認や identity 鍵指定などの詳細は -[環境変数の export / import ガイド](env-export-import.md#devbase-env-import-リファレンス)を参照してください。 - -## plugin (pl) グループ - -プラグインの管理を行うコマンド群です。 - -### `devbase plugin list` - -インストール済み、または利用可能なプラグインを一覧表示します。 - -``` -devbase plugin list [--available] -``` - -| オプション | 説明 | -|-----------|------| -| `--available` | リポジトリから取得可能なプラグインを表示 | - -### `devbase plugin install` - -プラグインをインストールします。 - -``` -devbase plugin install -``` - -ソースの指定形式: - -| 形式 | 説明 | 例 | -|------|------|----| -| 名前のみ | 登録済みリポジトリから検索 | `devbase plugin install adminer` | -| リポジトリ直接指定 | 特定リポジトリのプラグイン | `devbase plugin install user/repo:plugin-name` | -| 全プラグイン一括 | リポジトリの全プラグインをインストール | `devbase plugin install user/repo --all` | -| ローカルリンク | ローカルディレクトリからリンク | `devbase plugin install /path:plugin-name --link` | - -### `devbase plugin uninstall` - -プラグインをアンインストールします。 - -``` -devbase plugin uninstall -``` - -### `devbase plugin update` - -プラグインを最新バージョンに更新します。 - -``` -devbase plugin update [name] -``` - -| パラメータ | 必須 | 説明 | -|-----------|------|------| -| `name` | いいえ | 更新するプラグイン名（省略時は全プラグイン） | - -### `devbase plugin info` - -プラグインの詳細情報を表示します。 - -``` -devbase plugin info -``` - -### `devbase plugin sync` - -プロジェクトのシンボリックリンクを再同期します。 - -``` -devbase plugin sync -``` - -### `devbase plugin migrate` - -旧形式 (`plugins/` へのコピー) でインストールされたプラグインを、`repos/` 配下の永続クローンへ移行します。`install` / `update` 実行時にも自動で呼び出されるため、通常は手動実行不要です。 - -``` -devbase plugin migrate -``` - -移行の挙動: - -| 状況 | 動作 | -|---|---| -| コピーがクローンと一致 | 旧コピーを削除し `repos/` へ移行 (migrated) | -| コピーにローカル変更あり | 旧コピーを `plugins/.bak` として保全 (preserved、手動で reconcile) | -| 移行できない (ソース未登録 等) | スキップしてエラーを表示 (skipped) | - -`--link` でインストールしたプラグインは移行対象外です。 - -### `devbase plugin repo add` - -プラグインリポジトリを登録します。 - -``` -devbase plugin repo add -``` - -```bash -# GitHub ショートハンド -devbase plugin repo add user/repo - -# 完全な URL -devbase plugin repo add https://github.com/user/repo.git -``` - -### `devbase plugin repo remove` - -リポジトリの登録を削除します。 - -``` -devbase plugin repo remove -``` - -### `devbase plugin repo list` - -登録済みリポジトリの一覧を表示します。 - -``` -devbase plugin repo list -``` - -### `devbase plugin repo refresh` - -プラグイン一覧をリポジトリから再取得します。 - -``` -devbase plugin repo refresh [name] -``` - -| パラメータ | 必須 | 説明 | -|-----------|------|------| -| `name` | いいえ | 更新するリポジトリ名（省略時は全リポジトリ） | - -## snapshot (ss) グループ - -スナップショットの管理を行うコマンド群です。詳細は [スナップショットガイド](snapshot-guide.md) を参照してください。 - -### `devbase snapshot create` - -スナップショットを作成します。 - -``` -devbase snapshot create [--name NAME] [--full] -``` - -| オプション | 説明 | -|-----------|------| -| `--name NAME` | スナップショット名を指定（デフォルトはタイムスタンプ） | -| `--full` | フルバックアップを強制作成 | - -```bash -# 自動命名で差分スナップショット -devbase snapshot create - -# 名前付きフルバックアップ -devbase snapshot create --name before-upgrade --full -``` - -### `devbase snapshot list` - -スナップショットの一覧を表示します。 - -``` -devbase snapshot list -``` - -### `devbase snapshot restore` - -スナップショットから復元します。 - -``` -devbase snapshot restore [--point N] -``` - -| パラメータ / オプション | 必須 | 説明 | -|----------------------|------|------| -| `` | はい | 復元するスナップショット名 | -| `--point N` | いいえ | N 番目の差分まで復元（省略時は最新まで全適用） | - -> **Warning:** 復元前に現在の状態が `pre-restore-` として自動バックアップされます。 - -### `devbase snapshot copy` - -スナップショットをコピーします。 - -``` -devbase snapshot copy -``` - -### `devbase snapshot delete` - -スナップショットを削除します。 - -``` -devbase snapshot delete -``` - -### `devbase snapshot rotate` - -古い世代のスナップショットを削除します。 - -``` -devbase snapshot rotate [--keep N] -``` - -| オプション | 説明 | -|-----------|------| -| `--keep N` | 保持する世代数（デフォルト: `3`） | diff --git a/docs/user/cli-reference/03-env.md b/docs/user/cli-reference/03-env.md new file mode 100644 index 00000000..408102d8 --- /dev/null +++ b/docs/user/cli-reference/03-env.md @@ -0,0 +1,126 @@ +# env グループ + +[CLI リファレンス目次に戻る](README.md) + +環境変数の管理を行うコマンド群です。詳細は [環境変数ガイド](../environment-variables.md) を参照してください。 + +## `devbase env init` + +環境変数の対話式初期セットアップを実行します。 + +``` +devbase env init [--reset] +``` + +| オプション | 説明 | +|-----------|------| +| `--reset` | 既存の設定をリセットして再設定 | + +## `devbase env sync` + +ソースファイル（`~/.aws/config` 等）の変更を検出し、環境変数を再同期します。 + +``` +devbase env sync +``` + +## `devbase env list` + +設定済みの環境変数を一覧表示します。 + +``` +devbase env list [-g|-p] [-r] [-k] +``` + +| オプション | 説明 | +|-----------|------| +| `-g` | グローバル変数のみ表示 | +| `-p` | プロジェクト変数のみ表示 | +| `-r` | 値も表示（デフォルトではキーのみ） | +| `-k` | キー名でソート | + +```bash +# グローバル変数のみ、値付きで表示 +devbase env list -g -r + +# プロジェクト変数をキー名順で表示 +devbase env list -p -k +``` + +## `devbase env set` + +環境変数を設定します。 + +``` +devbase env set KEY=VALUE [-p] +``` + +| オプション | 説明 | +|-----------|------| +| `-p` | プロジェクトレベルに設定（デフォルトはグローバル） | + +```bash +# グローバルに設定 +devbase env set ANTHROPIC_API_KEY=sk-xxx + +# プロジェクトレベルに設定 +devbase env set GCP_ACTIVE_PROFILE=my-project -p +``` + +## `devbase env get` + +環境変数の値を取得します。 + +``` +devbase env get KEY +``` + +```bash +devbase env get AWS_PROFILE +``` + +## `devbase env delete` + +環境変数を削除します。 + +``` +devbase env delete KEY +``` + +## `devbase env edit` + +デフォルトエディタで `.env` ファイルを開きます。 + +``` +devbase env edit +``` + +## `devbase env project` + +プロジェクト固有の環境変数を対話式で設定します。 + +``` +devbase env project +``` + +## `devbase env export` + +複数プロジェクトの `.env` 群を暗号化したまま 1 つのバンドルにまとめて書き出します。 + +``` +devbase env export +``` + +オプション（age 鍵 / passphrase / S3 入出力など）の詳細は +[環境変数の export / import ガイド](../env-export-import.md#devbase-env-export-リファレンス)を参照してください。 + +## `devbase env import` + +`devbase env export` で作成したバンドルを復号し、環境変数を取り込みます。 + +``` +devbase env import +``` + +`--dry-run` での確認や identity 鍵指定などの詳細は +[環境変数の export / import ガイド](../env-export-import.md#devbase-env-import-リファレンス)を参照してください。 diff --git a/docs/user/cli-reference/04-plugin.md b/docs/user/cli-reference/04-plugin.md new file mode 100644 index 00000000..f6350567 --- /dev/null +++ b/docs/user/cli-reference/04-plugin.md @@ -0,0 +1,132 @@ +# plugin (pl) グループ + +[CLI リファレンス目次に戻る](README.md) + +プラグインの管理を行うコマンド群です。 + +## `devbase plugin list` + +インストール済み、または利用可能なプラグインを一覧表示します。 + +``` +devbase plugin list [--available] +``` + +| オプション | 説明 | +|-----------|------| +| `--available` | リポジトリから取得可能なプラグインを表示 | + +## `devbase plugin install` + +プラグインをインストールします。 + +``` +devbase plugin install +``` + +ソースの指定形式: + +| 形式 | 説明 | 例 | +|------|------|----| +| 名前のみ | 登録済みリポジトリから検索 | `devbase plugin install adminer` | +| リポジトリ直接指定 | 特定リポジトリのプラグイン | `devbase plugin install user/repo:plugin-name` | +| 全プラグイン一括 | リポジトリの全プラグインをインストール | `devbase plugin install user/repo --all` | +| ローカルリンク | ローカルディレクトリからリンク | `devbase plugin install /path:plugin-name --link` | + +## `devbase plugin uninstall` + +プラグインをアンインストールします。 + +``` +devbase plugin uninstall +``` + +## `devbase plugin update` + +プラグインを最新バージョンに更新します。 + +``` +devbase plugin update [name] +``` + +| パラメータ | 必須 | 説明 | +|-----------|------|------| +| `name` | いいえ | 更新するプラグイン名（省略時は全プラグイン） | + +## `devbase plugin info` + +プラグインの詳細情報を表示します。 + +``` +devbase plugin info +``` + +## `devbase plugin sync` + +プロジェクトのシンボリックリンクを再同期します。 + +``` +devbase plugin sync +``` + +## `devbase plugin migrate` + +旧形式 (`plugins/` へのコピー) でインストールされたプラグインを、`repos/` 配下の永続クローンへ移行します。`install` / `update` 実行時にも自動で呼び出されるため、通常は手動実行不要です。 + +``` +devbase plugin migrate +``` + +移行の挙動: + +| 状況 | 動作 | +|---|---| +| コピーがクローンと一致 | 旧コピーを削除し `repos/` へ移行 (migrated) | +| コピーにローカル変更あり | 旧コピーを `plugins/.bak` として保全 (preserved、手動で reconcile) | +| 移行できない (ソース未登録 等) | スキップしてエラーを表示 (skipped) | + +`--link` でインストールしたプラグインは移行対象外です。 + +## `devbase plugin repo add` + +プラグインリポジトリを登録します。 + +``` +devbase plugin repo add +``` + +```bash +# GitHub ショートハンド +devbase plugin repo add user/repo + +# 完全な URL +devbase plugin repo add https://github.com/user/repo.git +``` + +## `devbase plugin repo remove` + +リポジトリの登録を削除します。 + +``` +devbase plugin repo remove +``` + +## `devbase plugin repo list` + +登録済みリポジトリの一覧を表示します。 + +``` +devbase plugin repo list +``` + +## `devbase plugin repo refresh` + +プラグイン一覧をリポジトリから再取得します。 + +``` +devbase plugin repo refresh [name] +``` + +| パラメータ | 必須 | 説明 | +|-----------|------|------| +| `name` | いいえ | 更新するリポジトリ名（省略時は全リポジトリ） | diff --git a/docs/user/cli-reference/05-snapshot.md b/docs/user/cli-reference/05-snapshot.md new file mode 100644 index 00000000..d55ad16c --- /dev/null +++ b/docs/user/cli-reference/05-snapshot.md @@ -0,0 +1,77 @@ +# snapshot (ss) グループ + +[CLI リファレンス目次に戻る](README.md) + +スナップショットの管理を行うコマンド群です。詳細は [スナップショットガイド](../snapshot-guide.md) を参照してください。 + +## `devbase snapshot create` + +スナップショットを作成します。 + +``` +devbase snapshot create [--name NAME] [--full] +``` + +| オプション | 説明 | +|-----------|------| +| `--name NAME` | スナップショット名を指定（デフォルトはタイムスタンプ） | +| `--full` | フルバックアップを強制作成 | + +```bash +# 自動命名で差分スナップショット +devbase snapshot create + +# 名前付きフルバックアップ +devbase snapshot create --name before-upgrade --full +``` + +## `devbase snapshot list` + +スナップショットの一覧を表示します。 + +``` +devbase snapshot list +``` + +## `devbase snapshot restore` + +スナップショットから復元します。 + +``` +devbase snapshot restore [--point N] +``` + +| パラメータ / オプション | 必須 | 説明 | +|----------------------|------|------| +| `` | はい | 復元するスナップショット名 | +| `--point N` | いいえ | N 番目の差分まで復元（省略時は最新まで全適用） | + +> **Warning:** 復元前に現在の状態が `pre-restore-` として自動バックアップされます。 + +## `devbase snapshot copy` + +スナップショットをコピーします。 + +``` +devbase snapshot copy +``` + +## `devbase snapshot delete` + +スナップショットを削除します。 + +``` +devbase snapshot delete +``` + +## `devbase snapshot rotate` + +古い世代のスナップショットを削除します。 + +``` +devbase snapshot rotate [--keep N] +``` + +| オプション | 説明 | +|-----------|------| +| `--keep N` | 保持する世代数（デフォルト: `3`） | diff --git a/docs/user/cli-reference/README.md b/docs/user/cli-reference/README.md new file mode 100644 index 00000000..b81e0ad2 --- /dev/null +++ b/docs/user/cli-reference/README.md @@ -0,0 +1,84 @@ +# CLI リファレンス + +devbase の全コマンドの構文、オプション、使用例をまとめたリファレンスです。コマンドグループごとにファイルを分けています。 + +| ファイル | 内容 | +|---------|------| +| [トップレベルコマンド](01-toplevel.md) | `init` / `status` / `bin/rc` | +| [project グループ](02-project.md) | コンテナのライフサイクル管理・一覧（`up` / `down` / `login` / `ps` / `logs` / `scale` / `build` / `rebuild` / `list`）と非推奨の `container` グループ | +| [env グループ](03-env.md) | 環境変数の管理（`init` / `sync` / `list` / `set` / `get` / `delete` / `edit` / `project` / `export` / `import`） | +| [plugin グループ](04-plugin.md) | プラグインの管理（`list` / `install` / `uninstall` / `update` / `info` / `sync` / `migrate` / `repo *`） | +| [snapshot グループ](05-snapshot.md) | スナップショットの管理（`create` / `list` / `restore` / `copy` / `delete` / `rotate`） | + +## コマンド体系 + +devbase のコマンドは 4 つのグループとトップレベルコマンドで構成されています。 + +```mermaid +graph TD + A[devbase] --> B[init] + A --> C[status] + A --> D[project] + A --> E[env] + A --> F[plugin / pl] + A --> G[snapshot / ss] + D --> D1["up / down / ps / logs / scale [name]"] + D --> D3["login [index]"] + D --> D4["build [image] / rebuild [name]"] + D --> D2["list [--no-interactive]"] + E --> E1[init / sync / list / set / get / delete / edit / project / export / import] + F --> F1[list / install / uninstall / update / info / sync / migrate] + F --> F2[repo add / repo remove / repo list / repo refresh] + G --> G1[create / list / restore / copy / delete / rotate] +``` + +> **`container` グループは非推奨になりました。** 旧 `devbase container ` は +> `devbase project ` のエイリアスとして当面動作しますが、実行時に非推奨警告を +> 表示します（移行期間後のリリースで削除予定）。新しいコマンドは `project` を使用してください。 + +### グループエイリアス + +各グループには短縮形が用意されています。 + +| グループ名 | エイリアス | 備考 | +|-----------|-----------|------| +| `plugin` | `pl` | | +| `snapshot` | `ss` | | +| `container` | `ct` | **非推奨**（`project` へ移行してください） | + +### ショートカットコマンド + +頻繁に使用するプロジェクト操作はトップレベルから直接実行できます。これらは `project` グループに自動転送されます。 + +| ショートカット | 転送先 | +|--------------|--------| +| `devbase up [name]` | `devbase project up [name]` | +| `devbase down [name]` | `devbase project down [name]` | +| `devbase login [index]` | `devbase project login [index]` | +| `devbase build [image]` | `bin/devbase` の `cmd_build`（シェル実装）※ | +| `devbase ps [name]` | `devbase project ps [name]` | +| `devbase scale [name] ` | `devbase project scale [name] ` | +| `devbase rebuild [name]` | `devbase project rebuild [name]` | +| `devbase list` | `devbase project list` | + +> **Note:** `logs` はトップレベルシノニムを持ちません。`devbase project logs` を使用してください。 +> +> **※ `build` の転送先について:** `devbase build`（既定 / `--no-cache` / ``）は他の +> ショートカットのように `project` グループ（Python 実装）へ転送されるのではなく、`bin/devbase` の +> シェル実装 `cmd_build` に直接委譲されます。base イメージの段階ビルド等を CWD で行う必要があるため +> です（名前指定はラッパーの `cd` で解決）。ただし `devbase build --expires[=DAYS]` のみ、作成日の +> 判定が必要なため例外的に Python 経路（`project build`）へ委譲されます。挙動上の入出力は同等です。 + +### ユニークプレフィックスマッチング + +コマンド名が一意に特定できる場合、先頭の数文字だけで実行できます。 + +```bash +# 以下は全て同じコマンド +devbase plugin list +devbase pl list +devbase p l +devbase pl l +``` + +> **Note:** 一意に特定できない場合は候補が表示されます。 diff --git a/docs/user/container-operations.md b/docs/user/container-operations.md index c5b1838f..efe84d05 100644 --- a/docs/user/container-operations.md +++ b/docs/user/container-operations.md @@ -7,7 +7,7 @@ devbase のコンテナ管理機能について、ライフサイクル、並行 > 非推奨となり、`project` へのエイリアスとして警告付きで当面動作します。`project` では > `up` / `down` / `ps` / `logs` / `scale` に `[name]` を指定することで **任意のディレクトリ > から** 対象プロジェクトを操作できます。プロジェクト一覧は `devbase project list` を参照 -> してください。詳細は [CLI リファレンス](cli-reference.md#project-グループ) を参照。 +> してください。詳細は [CLI リファレンス: project グループ](cli-reference/02-project.md) を参照。 ## コンテナライフサイクル @@ -136,7 +136,7 @@ devbase のコンテナは 2 種類のボリュームを使用します。 | ボリューム名 | マウント先 | 共有範囲 | 用途 | |-------------|-----------|---------|------| | `devbase_home_ubuntu` | `/persistent/ai` | 全コンテナで共有 | AI CLI 設定（`.claude` / `.codex` / `.gemini` 等）、SSH 鍵、共有ファイル置き場（`share`）。詳細は「AI 設定の永続化」参照 | -| `{project}_work_{index}` | `/work` | 各コンテナ専用 | プロジェクトのソースコード、作業ファイル | +| `devbase_work_{index}` | `/work` | 同じ index のコンテナで共有（プロジェクト間も共有） | プロジェクトのソースコード、作業ファイル | > **Note:** `devbase_home_ubuntu` は **`/persistent/ai`** にマウントされます（`/home/ubuntu` への直接マウントは廃止）。`/home/ubuntu` 直下はコンテナ層（揮発）で、永続化されるのは entrypoint が `/persistent/ai` 配下へ symlink する設定ファイルのみです。シェル履歴など symlink 対象外のファイルは再生成で失われます。 @@ -146,6 +146,8 @@ devbase のコンテナは 2 種類のボリュームを使用します。 - コンテナの再起動（`devbase up`）で同じボリュームが再マウントされます - ボリュームを明示的に削除するには `docker volume rm` を使用します +> **Warning:** `devbase_work_{index}` は `COMPOSE_PROJECT_NAME` の接頭辞が付かない **external ボリューム**です。同じ index（コンテナ 1 なら `devbase_work_1`）を使う限り **別プロジェクトからも同じ実体**を参照するため、`docker volume rm devbase_work_1` は停止中の他プロジェクトの作業ファイルまで削除します。削除前に `docker ps -a --filter volume=devbase_work_1` で利用コンテナを確認してください。 + ### ボリュームの確認 ```bash @@ -181,7 +183,7 @@ AI CLI ツールの設定や認証情報は、コンテナを再生成しても - `share` 配下に置いた VS Code ワークスペースファイルは `DEVBASE_WORKSPACE` で開けます（[環境変数](environment-variables.md) 参照）。 > **Note:** symlink 対象は entrypoint にビルド時 `COPY` で焼き込まれます。エントリを増減した場合は -> イメージの再ビルドが必要です（`devbase up` 単体では反映されない場合があります。[CLI リファレンス](cli-reference.md) の `devbase project up` の注記参照）。 +> イメージの再ビルドが必要です（`devbase up` 単体では反映されない場合があります。[CLI リファレンス: project グループ](cli-reference/02-project.md#devbase-project-up) の `devbase project up` の注記参照）。 ## コンテナイメージ階層 @@ -278,7 +280,7 @@ devbase list --no-interactive # --plain / -P も同義 > スナップショット / ステータス）へ ←→ キーで移動して各管理操作を実行できます。 > パイプ・リダイレクト・CI などの非 TTY 環境では自動的に一覧表示のみに > フォールバックします。画面構成とキー操作の詳細は -> [CLI リファレンス](cli-reference.md#devbase-project-list) を参照してください。 +> [CLI リファレンス: project グループ](cli-reference/02-project.md#devbase-project-list) を参照してください。 `devbase project ps` が「対象プロジェクト 1 つのコンテナ状態」を表示するのに対し、 `devbase list` は「全プロジェクトの横断一覧」を表示します。 diff --git a/docs/user/env-export-import.md b/docs/user/env-export-import.md index 6f515d56..8eb9ce26 100644 --- a/docs/user/env-export-import.md +++ b/docs/user/env-export-import.md @@ -452,5 +452,5 @@ Phase 2 (commit) の途中で異常終了した可能性があります。次回 ## 関連ドキュメント - [環境変数ガイド](environment-variables.md) — 3 レベル構造とコレクター -- [CLI リファレンス](cli-reference.md) — 全コマンド一覧 +- [CLI リファレンス](cli-reference/README.md) — 全コマンド一覧 - [はじめに](getting-started.md) — 初回セットアップ diff --git a/docs/user/getting-started.md b/docs/user/getting-started.md index 0b5112f7..5940abbf 100644 --- a/docs/user/getting-started.md +++ b/docs/user/getting-started.md @@ -249,7 +249,7 @@ devbase/ ## 次のステップ -- [CLI リファレンス](cli-reference.md) -- 全コマンドの詳細な使い方 +- [CLI リファレンス](cli-reference/README.md) -- 全コマンドの詳細な使い方 - [環境変数ガイド](environment-variables.md) -- 環境変数の3レベル構造とコレクター - [コンテナ操作ガイド](container-operations.md) -- 並行開発やボリュームの詳細 - [スナップショットガイド](snapshot-guide.md) -- バックアップと復元の仕組み diff --git a/docs/user/plugin-registries.md b/docs/user/plugin-registries.md index 6a3872a2..66e8d4c8 100644 --- a/docs/user/plugin-registries.md +++ b/docs/user/plugin-registries.md @@ -62,6 +62,6 @@ devbase plugin repo refresh ## 関連ドキュメント - [はじめに](getting-started.md) -- [CLI リファレンス](cli-reference.md) -- `plugin repo` サブコマンドの詳細 +- [CLI リファレンス: plugin グループ](cli-reference/04-plugin.md) -- `plugin repo` サブコマンドの詳細 - [プラグイン開発クイックスタート](../plugin-dev/quickstart.md) - [plugin.yml リファレンス](../plugin-dev/plugin-yml-reference.md)