From b8729584a11d869ce5c27126f33104f81ca21951 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Sat, 27 Jun 2026 10:46:17 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=E3=83=9B=E3=83=BC=E3=83=A0=E3=83=9C?= =?UTF-8?q?=E3=83=AA=E3=83=A5=E3=83=BC=E3=83=A0=E3=81=AE=E3=83=9E=E3=82=A6?= =?UTF-8?q?=E3=83=B3=E3=83=88=E5=85=88=E3=82=92=20/persistent/ai=20?= =?UTF-8?q?=E3=81=AB=E4=BF=AE=E6=AD=A3=E3=81=97=20AI=20=E8=A8=AD=E5=AE=9A?= =?UTF-8?q?=E6=B0=B8=E7=B6=9A=E5=8C=96=E3=82=92=E6=98=8E=E6=96=87=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ドキュメントが実装と乖離していた点を是正する。 ## 修正内容 1. マウント先の誤り訂正 (/home/ubuntu → /persistent/ai) - devbase_home_ubuntu ボリュームは /persistent/ai にマウントされる (lib/devbase/volume/compose.py:13-14 で /home/ubuntu は _DEPRECATED_TARGET として除去、/persistent/ai にマップ)。 - /home/ubuntu 直下はコンテナ層(揮発)で、永続化されるのは entrypoint が /persistent/ai 配下へ symlink する設定のみ。「シェル履歴等も永続」という 記述は誤りだったため訂正。 - 対象: container-operations.md / compose-yml-guidelines.md / quickstart.md / snapshot-guide.md / troubleshooting.md / README.md 2. AI 設定の永続化を明文化 (container-operations.md に新セクション) - symlink 機構と対象一覧 (.claude / .codex / .gemini / .serena / .ssh / .kiro / share) を記載。PR #77 で追加した .kiro / share を反映。 - share が全コンテナ共有のファイル置き場であること、DEVBASE_WORKSPACE との 関連を追記。 3. rebuild / --no-cache の説明訂正 (README.md) - 「devbase rebuild で docker compose build --no-cache 相当」は誤り。 rebuild は build --expires=7 で齢ゲート付き。無条件 no-cache は devbase build --no-cache であることを明記。 4. entrypoint/Dockerfile 変更時の再ビルド注記 (cli-reference.md) - devbase up はイメージ齢 7 日未満だと再ビルドをスキップするため、 entrypoint 変更は build --no-cache が必要な旨を追記。 Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 4 +-- docs/plugin-dev/compose-yml-guidelines.md | 8 +++-- docs/plugin-dev/quickstart.md | 10 +++--- docs/user/cli-reference.md | 6 ++++ docs/user/container-operations.md | 37 ++++++++++++++++++++--- docs/user/environment-variables.md | 2 +- docs/user/snapshot-guide.md | 6 ++-- docs/user/troubleshooting.md | 4 +-- 8 files changed, 57 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 6999329..20df646 100644 --- a/README.md +++ b/README.md @@ -13,10 +13,10 @@ devbaseは、Docker Composeを使った再現性の高い開発環境を提供 - **豊富なツールセット**: Docker CLI、AWS CLI、gcloud SDK、Terraform、Node.js、AI CLIツールがプリインストール - **複数コンテナの並行開発**: `devbase project scale`で既存コンテナを再起動せずにスケール可能 - **データ永続化**: 名前付きボリュームでコンテナ再起動後もデータを保持 -- **スナップショット管理**: `/home/ubuntu` 共通ボリュームの増分バックアップ・復元・世代管理 +- **スナップショット管理**: 共通ボリューム `devbase_home_ubuntu`（コンテナ内 `/persistent/ai`。AI 設定・共有ファイル）の増分バックアップ・復元・世代管理 - **環境変数の自動収集**: `devbase env init`でAWS/Git/GCP認証情報を対話的に設定 - **階層メニュー TUI**: `devbase list` のプロジェクト一覧（矢印キー移動・名前絞り込み対応）から起動・操作（up / down / login / ps / logs / scale / build / rebuild）を選択。画面最下部の常設メニュー（環境変数 / プラグイン / スナップショット / ステータス）へは ←→ キーで移動できます -- **キャッシュ無効リビルド**: `devbase rebuild [name]` で `docker compose build --no-cache` 相当のイメージ再ビルドができます +- **イメージ再ビルド**: `devbase build [name] --no-cache` でキャッシュ無効の完全再ビルド。`devbase rebuild [name]`（= `build --expires=7`）はイメージが既定 7 日より古いときのみ再ビルドします ## クイックスタート diff --git a/docs/plugin-dev/compose-yml-guidelines.md b/docs/plugin-dev/compose-yml-guidelines.md index 30b2627..977b92a 100644 --- a/docs/plugin-dev/compose-yml-guidelines.md +++ b/docs/plugin-dev/compose-yml-guidelines.md @@ -103,15 +103,19 @@ devbaseでは2種類のボリュームパターンを使い分けます。 ```yaml volumes: - - devbase_home_ubuntu:/home/ubuntu # 全コンテナ共有 + - devbase_home_ubuntu:/persistent/ai # 全コンテナ共有（AI設定） - ${COMPOSE_PROJECT_NAME}_work_${CONTAINER_INDEX:-1}:/work # コンテナ専用 ``` | ボリューム | マウント先 | 共有範囲 | 用途 | |-----------|-----------|----------|------| -| `devbase_home_ubuntu` | `/home/ubuntu` | 全コンテナ | シェル設定、SSH鍵、Git設定 | +| `devbase_home_ubuntu` | `/persistent/ai` | 全コンテナ | AI CLI 設定（`.claude` 等）、SSH鍵、共有ファイル置き場（`share`）。`~/.claude` 等は entrypoint が symlink | | `${COMPOSE_PROJECT_NAME}_work_${CONTAINER_INDEX:-1}` | `/work` | コンテナ専用 | ソースコード、ビルド成果物 | +> **Note:** マウント先は **`/persistent/ai`** です（旧 `/home/ubuntu` 直接マウントは廃止）。 +> これらの標準ボリュームは compose.yml に明記しなくても devbase がスケール用 compose 生成時に +> 自動注入します。明記する場合も必ず `/persistent/ai` を使ってください。 + ### 3.2 Docker Socketのマウント コンテナ内からDockerコマンドを使用する場合は、Docker Socketをマウントし、`group_add` でDockerグループに追加します。 diff --git a/docs/plugin-dev/quickstart.md b/docs/plugin-dev/quickstart.md index e03c419..ad15db8 100644 --- a/docs/plugin-dev/quickstart.md +++ b/docs/plugin-dev/quickstart.md @@ -252,12 +252,12 @@ flowchart LR ### 5.3 ボリューム設計 -| 用途 | ボリューム名パターン | 共有範囲 | -|------|---------------------|----------| -| ホームディレクトリ | `devbase_home_ubuntu` | 全コンテナ共有 | -| 作業ディレクトリ | `${COMPOSE_PROJECT_NAME}_work_${CONTAINER_INDEX:-1}` | コンテナ専用 | +| 用途 | ボリューム名パターン | マウント先 | 共有範囲 | +|------|---------------------|-----------|----------| +| AI 設定・共有ファイル | `devbase_home_ubuntu` | `/persistent/ai` | 全コンテナ共有 | +| 作業ディレクトリ | `${COMPOSE_PROJECT_NAME}_work_${CONTAINER_INDEX:-1}` | `/work` | コンテナ専用 | -- ホームディレクトリボリュームはシェル設定やSSH鍵など、コンテナ横断で共有したい設定の永続化に使用 +- `devbase_home_ubuntu`（`/persistent/ai`）は AI CLI 設定・SSH 鍵・共有ファイルなど、コンテナ横断で共有したい設定の永続化に使用（`~/.claude` 等は entrypoint が symlink。旧 `/home/ubuntu` 直接マウントは廃止） - 作業ディレクトリボリュームはプロジェクトごと・コンテナインデックスごとに独立 ### 5.4 コンテナイメージの選択 diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference.md index 4752bf1..9fb90f2 100644 --- a/docs/user/cli-reference.md +++ b/docs/user/cli-reference.md @@ -180,6 +180,12 @@ devbase up [name] （前回 pull 日時は `${DEVBASE_ROOT}/.cache/pulls/` の touch-file mtime で判定） - 閾値は `DEVBASE_IMAGE_MAX_AGE_DAYS` 環境変数で上書き可能（既定 7、不正値は警告して既定値） +> **Note (entrypoint / Dockerfile を変更したとき):** `containers/` 配下の `entrypoint.sh` や +> Dockerfile はビルド時にイメージへ焼き込まれます。これらを変更しても、上記のとおり +> `devbase up` はイメージが 7 日より新しいと再ビルドをスキップするため、変更が反映されない +> ことがあります。確実に反映するには **`devbase build [name] --no-cache`** で再ビルドしてから +> `devbase up` してください（`--no-cache` は `build` のオプションで、`rebuild` にはありません）。 + ### `devbase project down` コンテナを停止・削除します。 diff --git a/docs/user/container-operations.md b/docs/user/container-operations.md index 0a0d5dc..c5b1838 100644 --- a/docs/user/container-operations.md +++ b/docs/user/container-operations.md @@ -117,7 +117,7 @@ graph LR subgraph devbase C[コンテナ 1
/work 専用] D[コンテナ 2
/work 専用] - E[共有ホーム
/home/ubuntu] + E[共有AI設定
/persistent/ai] end A --> C B --> D @@ -126,7 +126,7 @@ graph LR ``` - 各コンテナは独立した `/work` ボリュームを持つ -- `/home/ubuntu` は全コンテナで共有される +- `/persistent/ai`（AI 設定・共有ファイル）は全コンテナで共有される（`/home/ubuntu` 直下のうち永続化されるのは symlink 対象のみ。下記「AI 設定の永続化」参照） - 異なるブランチでの並行作業に便利 ## ボリューム構造 @@ -135,9 +135,11 @@ devbase のコンテナは 2 種類のボリュームを使用します。 | ボリューム名 | マウント先 | 共有範囲 | 用途 | |-------------|-----------|---------|------| -| `devbase_home_ubuntu` | `/home/ubuntu` | 全コンテナで共有 | ユーザー設定、SSH 鍵、シェル履歴等 | +| `devbase_home_ubuntu` | `/persistent/ai` | 全コンテナで共有 | AI CLI 設定（`.claude` / `.codex` / `.gemini` 等）、SSH 鍵、共有ファイル置き場（`share`）。詳細は「AI 設定の永続化」参照 | | `{project}_work_{index}` | `/work` | 各コンテナ専用 | プロジェクトのソースコード、作業ファイル | +> **Note:** `devbase_home_ubuntu` は **`/persistent/ai`** にマウントされます（`/home/ubuntu` への直接マウントは廃止）。`/home/ubuntu` 直下はコンテナ層（揮発）で、永続化されるのは entrypoint が `/persistent/ai` 配下へ symlink する設定ファイルのみです。シェル履歴など symlink 対象外のファイルは再生成で失われます。 + ### ボリュームの永続性 - ボリュームは `devbase down` でもコンテナが削除されても保持されます @@ -154,7 +156,32 @@ docker volume ls | grep devbase docker volume inspect devbase_home_ubuntu ``` -> **Warning:** `devbase_home_ubuntu` ボリュームは全プロジェクトで共有されます。ここにプロジェクト固有のファイルを置くと、他のプロジェクトにも影響します。プロジェクト固有のファイルは `/work` に配置してください。 +> **Warning:** `devbase_home_ubuntu` ボリューム（`/persistent/ai`、および symlink 経由でアクセスする `~/.claude` / `~/share` 等）は全プロジェクトで共有されます。ここにプロジェクト固有のファイルを置くと、他のプロジェクトにも影響します。プロジェクト固有のファイルは `/work` に配置してください。 + +## AI 設定の永続化 + +AI CLI ツールの設定や認証情報は、コンテナを再生成しても保持されるよう +`devbase_home_ubuntu` ボリューム（`/persistent/ai`）に永続化されます。 + +仕組みは **symlink** です。コンテナ起動時、entrypoint（`containers/base/entrypoint.sh`）が +以下の各エントリについて `/home/ubuntu/ -> /persistent/ai/` の symlink を作成します。 + +| エントリ | 内容 | +|---------|------| +| `.claude.json` / `.claude` | Claude Code の設定・認証 | +| `.codex` | Codex CLI の設定 | +| `.gemini` | Gemini CLI の設定 | +| `.serena` | Serena MCP の設定 | +| `.kiro` | Kiro CLI の設定 | +| `.ssh` | SSH 鍵 | +| `share` | 全コンテナ共有のファイル置き場（任意用途） | + +- `/persistent/ai` は全コンテナ共通の `devbase_home_ubuntu` ボリュームなので、**どのコンテナからも同じ実体**を参照します（例: `~/share` は全コンテナで共有）。 +- symlink **対象外**のホーム配下ファイル（シェル履歴など）はコンテナ層に置かれ、再生成で失われます。永続化したいものは `/persistent/ai` 配下（= 上記 symlink 先）か `/work` に置いてください。 +- `share` 配下に置いた VS Code ワークスペースファイルは `DEVBASE_WORKSPACE` で開けます（[環境変数](environment-variables.md) 参照）。 + +> **Note:** symlink 対象は entrypoint にビルド時 `COPY` で焼き込まれます。エントリを増減した場合は +> イメージの再ビルドが必要です（`devbase up` 単体では反映されない場合があります。[CLI リファレンス](cli-reference.md) の `devbase project up` の注記参照）。 ## コンテナイメージ階層 @@ -265,7 +292,7 @@ devbase status ## ベストプラクティス -1. **プロジェクト固有のファイルは `/work` に配置する** -- `/home/ubuntu` は全コンテナで共有されるため +1. **プロジェクト固有のファイルは `/work` に配置する** -- `/persistent/ai`（`~/.claude` 等の symlink 先・`~/share`）は全コンテナで共有されるため 2. **`CONTAINER_SCALE` は必要最小限に設定する** -- リソース消費を抑制 3. **作業終了後は `devbase down` を実行する** -- 自動ローテーションでディスク容量を管理 4. **`devbase ps` で状態を確認してからログインする** -- 異常終了したコンテナへのログイン試行を避ける diff --git a/docs/user/environment-variables.md b/docs/user/environment-variables.md index 100665d..0a968d6 100644 --- a/docs/user/environment-variables.md +++ b/docs/user/environment-variables.md @@ -148,7 +148,7 @@ devbase はホストマシンの認証情報を自動収集し、コンテナ内 |------|------| | `DEVBASE_OPEN_EDITOR` | 真（`1`/`true`/`yes`/`on`）で `up` 後にエディタを開く（既定: OFF） | | `DEVBASE_EDITOR` | 起動コマンド（既定: `code`）。`cursor` / `code-insiders` 等も可 | -| `DEVBASE_WORKSPACE` | 開く `*.code-workspace` ファイルの**コンテナ内絶対パス**（例 `/home/ubuntu/share/work/uttarov2-doc.workspace`）。指定時はフォルダではなくワークスペースを開く。未設定なら従来どおり `/work/$GIT_REPO` フォルダ。共有マウント `/home/ubuntu/share` 配下に置けば全コンテナで共用可 | +| `DEVBASE_WORKSPACE` | 開く `*.code-workspace` ファイルの**コンテナ内絶対パス**（例 `/home/ubuntu/share/work/uttarov2-doc.workspace`）。指定時はフォルダではなくワークスペースを開く。未設定なら従来どおり `/work/$GIT_REPO` フォルダ。`~/share`（= 全コンテナ共有ボリューム `/persistent/ai/share` への symlink）配下に置けば全コンテナで共用可 | | `DEVBASE_OPEN_INDEX` | scale 時に開く dev インスタンス番号（既定: `1`） | | `DEVBASE_EDITOR_SSH_HOST` | Remote-SSH 跨ホスト構成での ssh-remote ホスト名（例 `mac2`）。**通常は `~/.vscode-server` から自動検出**され不要。検出が外れる場合のみ明示。下記「跨ホスト」参照 | | `DEVBASE_EDITOR_DOCKER_CONTEXT` | 跨ホスト時に ssh 先で使う docker context（既定: ホストの `docker context show`） | diff --git a/docs/user/snapshot-guide.md b/docs/user/snapshot-guide.md index 2bf12f5..4d3dfae 100644 --- a/docs/user/snapshot-guide.md +++ b/docs/user/snapshot-guide.md @@ -1,6 +1,6 @@ # スナップショットガイド -devbase のスナップショット機能は、コンテナの `/home/ubuntu` 共通ボリューム (`devbase_home_ubuntu`) を増分バックアップし、世代管理と復元を提供します。`/work` 配下のプロジェクト作業ファイルはバックアップ対象外なので、重要なファイルは Git に push するか別途バックアップを取ってください。 +devbase のスナップショット機能は、共通ボリューム `devbase_home_ubuntu`（コンテナ内では `/persistent/ai` にマウント。AI CLI 設定や共有ファイルを保持）を増分バックアップし、世代管理と復元を提供します。`/work` 配下のプロジェクト作業ファイルはバックアップ対象外なので、重要なファイルは Git に push するか別途バックアップを取ってください。 ## 仕組み @@ -20,7 +20,7 @@ graph LR style D fill:#e8f4e8 ``` -- **フルバックアップ**: `/home/ubuntu` 共通ボリューム全体をアーカイブ +- **フルバックアップ**: 共通ボリューム `devbase_home_ubuntu`（`/persistent/ai`）全体をアーカイブ - **差分バックアップ**: 前回からの変更分のみをアーカイブ - **圧縮**: zstd `-1 -T0`（圧縮レベル 1、全 CPU コア使用）で高速圧縮 @@ -200,7 +200,7 @@ graph LR #### 復元の安全性 -復元を実行する前に、現在の `/home/ubuntu` 共通ボリュームの状態が `pre-restore-` という名前で自動バックアップされます。 +復元を実行する前に、現在の共通ボリューム `devbase_home_ubuntu`（`/persistent/ai`）の状態が `pre-restore-` という名前で自動バックアップされます。 ```bash # 復元前に自動作成されるバックアップ diff --git a/docs/user/troubleshooting.md b/docs/user/troubleshooting.md index f9bfc0f..b5d1a6f 100644 --- a/docs/user/troubleshooting.md +++ b/docs/user/troubleshooting.md @@ -373,10 +373,10 @@ devbase snapshot delete **原因と解決策:** -フルバックアップは `/home/ubuntu` 共通ボリューム全体を圧縮するため、データ量に比例して時間がかかります。 +フルバックアップは共通ボリューム `devbase_home_ubuntu`（コンテナ内 `/persistent/ai`）全体を圧縮するため、データ量に比例して時間がかかります。 - 差分バックアップ（`--full` なし）を使用すると、変更分のみのため高速です -- 大きな一時ファイルや不要なファイルを `/home/ubuntu` から削除してからバックアップしてください +- 大きな一時ファイルや不要なファイルを `/persistent/ai` 配下（`~/.claude` 等の symlink 先・`~/share`）から削除してからバックアップしてください ## 6. ボリューム関連