プラグイン開発クイックスタート

devbase用のPluginを作成し、公開するまでの手順を解説します。

前提条件

devbase 3.0.0 以上がインストール済み
Git がインストール済み
Docker / Docker Compose が利用可能

1. Pluginリポジトリの作成

1.1 Gitリポジトリの初期化

mkdir my-plugin &&cd my-plugin
git init

1.2 plugin.yml の配置

リポジトリのルート（Plugin ディレクトリのルート）に plugin.yml を作成します。このファイルは Plugin のメタ情報を定義します。

name: my-pluginversion: "1.0.0"description: "サンプルプラグイン"requires:
devbase: ">=3.0.0"priority: 0

ポイント:

プロジェクトは projects/ 配下のディレクトリから自動的に検出されます。plugin.yml に一覧を書く必要はありません。
requires.devbase には この Plugin が動作する devbase 本体の最低バージョンを書きます。project.yml 形式のプロジェクト定義は devbase 3.0.0 以降でしか読めないため、project.yml を持つ Plugin（= 本手順で作るもの）は必ず ">=3.0.0" を指定してください。

補足:plugin.yml のフォーマット詳細は plugin.yml リファレンスを参照してください。

2. 最小構成のプロジェクト作成

2.1 ディレクトリ構造

最小限のPluginは以下の構造で構成されます。

my-plugin/
├── plugin.yml
└── projects/
└── my-project/
├── compose.yml
├── project.yml
└── env # 中身は任意だが、ファイルは必須

2.2 compose.yml の作成

projects/my-project/compose.yml を作成します。

services:
dev:
image: my-project:latestbuild:
context: ${DEVBASE_ROOT}/containers/general/dockerfile: Dockerfilevolumes:
- /var/run/docker.sock:/var/run/docker.sockenv_file:
- ${DEVBASE_ROOT}/.env
- env
- .envgroup_add: ["${DOCKER_GID}"]command: tail -f /dev/nullworking_dir: /worknetworks:
- devbase_netnetworks:
devbase_net:
external: true

ポイント:

標準コンテナを使う場合は、build.context には ${DEVBASE_ROOT} ベースのパスを指定する（相対パス禁止）。Docker Hub などの公開イメージを利用する場合は image: のみを指定し build: を省略できる。独自の Dockerfile を使う場合は ${DEVBASE_ROOT}/plugins/<plugin>/... 配下に配置する（projects/ 直下はシンボリックリンクのため context: . は不可。詳細は compose.yml ガイドライン §4.3）
env_file は3段階の環境変数ファイルを読み込む
devbase_net はdevbaseが管理する共有ネットワーク

補足: compose.yml の記述ルール詳細は compose.yml ガイドラインを参照してください。

2.3 project.yml の作成

projects/my-project/project.yml を作成します。このファイルはGit管理対象で、プロジェクト設定の正です。

version: 1scale: 1repos:
- owner: your-github-userrepo: my-repo

複数のリポジトリを 1 つのコンテナへチェックアウトできます。

version: 1scale: 1defaults:
owner: your-github-userrepos:
- repo: my-app # 先頭が primary（ログイン直後の作業ディレクトリ）
- repo: my-app-docs
- repo: my-app-infrahost: gitlab.com # リポジトリごとに Git ホストを変えられるowner: another-orgdir: infra # /work 配下の clone 先名（既定: repo 名）branch: develop # clone 後にチェックアウトするブランチinit: false # 起動のたびの ./init.sh 実行を無効化する

主なキーは以下のとおりです。全項目は project.yml リファレンスを参照してください。

キー	説明
`version`	スキーマ版。現在は `1`
`repos[].owner` / `repos[].repo`	Git ホストのユーザー名（Organization 名）とリポジトリ名
`repos[].host`	Git ホスト名（既定: `github.com`）。GitLab なら `gitlab.com`
`repos[].dir` / `branch` / `init` / `primary`	clone 先ディレクトリ名 / チェックアウトするブランチ（clone 直後のみ） / `init.sh` の実行有無（起動のたびに実行。冪等に書くこと） / 既定の作業リポジトリ
`scale`	起動するコンテナ数（既定: 2）
`open_editor`	`devbase up` 後に VS Code を自動で開くか

2.3.1 env ファイル（ファイルは必須・中身は任意）

projects/my-project/env には、コンテナへ渡す環境変数だけを書きます（ENABLE_SSH など）。devbase 自身の設定は project.yml にあります。

ENABLE_SSH=true

2.2 の compose.yml が env_file: - env で参照するため、ファイルは必ず作成してください（実在しないと devbase up が compose の起動時に失敗します）。渡したい環境変数が無ければ空ファイルで構いません。

touch projects/my-project/env

2.4 .env ファイル（任意）

プロジェクト固有の機密情報は projects/my-project/.env に配置します。このファイルは .gitignore に含まれるため、Git管理対象外です。

MY_SECRET_API_KEY=sk-xxxxxxxxxxxx

2.5 ライフサイクルフック（任意）

プロジェクトディレクトリ直下に以下の実行可能ファイルを置くと、devbase up のライフサイクルに合わせて自動的に呼び出されます。どちらも実行できなくても問題ない場合は配置不要です。

ファイル	実行タイミング	主な用途
`pre-up`	`devbase up` 開始直後（`docker compose up` の前）	`build.context` 用ソースリポジトリの clone、設定ファイルの生成など、イメージビルド前に完了させたい準備
`deploy`	コンテナ起動完了後、各スケールインスタンスごとに実行	S3 からの `.env` 取得、コンテナ起動後に必要な外部リソースの初期化など

フックへ渡る環境変数

フックはホスト側で動くため、コンテナへ渡る env / .env は読み込まれません。フックが必要とする project.yml の値は、devbase が環境変数として明示的に渡します。

変数	内容	`pre-up`	`deploy`
`DEVBASE_PRIMARY_DIR`	primary リポジトリの `/work` 配下ディレクトリ名（`repos[].dir`。未指定ならリポジトリ名）	✓	✓
`DEVBASE_PRIMARY_URL`	primary リポジトリの clone URL（`https://<host>/<owner>/<repo>.git`）	✓	✓
`DEVBASE_WORK_DIR`	コンテナ内の既定の作業ディレクトリ（`work_dir`。未指定なら `/work/$DEVBASE_PRIMARY_DIR`）	✓	✓
`DEVBASE_REPO_DIRS`	全リポジトリのディレクトリ名を `project.yml` の宣言順に空白区切りで並べたもの	✓	✓
`DEVBASE_INSTANCE_INDEX`	実行対象のインスタンス番号（1 始まり）。`pre-up` はインスタンスごとに実行されないため渡りません	--	✓

primary は repos の先頭（または primary: true を付けた 1 件）で、常にちょうど 1 件です。primary 以外も含めて全リポジトリを回したい場合は DEVBASE_REPO_DIRS を使います。

fordirin$DEVBASE_REPO_DIRS;doecho"populate /work/$dir"done

Note: これらは子プロセスにだけ渡ります。フック内で export しても、後続の docker compose up や別プロジェクトの実行へは伝播しません。

`pre-up` の例

#!/bin/bash# projects/my-project/pre-upset -e
# build context に使うリポジトリが無ければ clone# (clone 先も URL も devbase が project.yml から渡してくれる)if [ !-d"./repo" ];then
git clone "$DEVBASE_PRIMARY_URL" repo
fiecho"コンテナ内の作業ディレクトリ: $DEVBASE_WORK_DIR"# 例: /work/my-repo

Note: どちらのフックも bash で実行されます。chmod +x で実行可能ビットを立てておいてください。pre-up が非ゼロ終了すると devbase up は中断します。deploy は失敗してもデプロイは続行されます。

応用: 外部リポジトリを共有 work ボリュームへ取り込み、app / nginx / db など複数コンテナで動かすプロジェクトでは、pre-up で clone/pull と work ボリュームへの populate を行い、2 回目以降はコンテナ側を上書きしないよう冪等にスキップするのが定石です。詳細は repo 連携プロジェクトと pre-up populate パターンを参照してください。

3. ローカルでの開発・テスト

3.1 リンクインストール

開発中のPluginは --link オプションでシンボリックリンクとしてインストールできます。ローカルでの変更が即座に反映されるため、開発サイクルが高速化します。

devbase plugin install /path/to/my-plugin:my-plugin --link

3.2 環境の初期化と起動

cd projects/my-project
devbase env init
devbase up

3.3 動作確認

# コンテナにログイン
devbase login
# コンテナの状態確認
devbase ps

3.4 開発中のトラブルシューティング

症状	確認事項
compose.yml のパスが解決できない	`${DEVBASE_ROOT}` ベースになっているか確認
環境変数が読み込まれない	`env_file` の指定順序と `.env` ファイルの存在を確認
ネットワーク接続エラー	`devbase_net` が作成済みか確認（`docker network ls`）
ボリュームが見つからない	外部ボリュームの場合は事前に作成が必要

4. 公開

4.1 GitHubリポジトリへのpush

cd /path/to/my-plugin
git add .
git commit -m "Initial plugin release"
git remote add origin https://github.com/your-user/my-plugin.git
git push -u origin main

4.2 レジストリへの登録

他のユーザーがインストールできるよう、レジストリに登録します。

devbase plugin repo add your-user/my-plugin

4.3 インストール確認

正しく公開されたか確認するため、名前指定でインストールします。

devbase plugin install my-plugin

5. ベストプラクティス

5.1 パスの記述

compose.yml 内のすべてのパスは ${DEVBASE_ROOT} ベースで記述してください。プロジェクトディレクトリは projects/ 配下にシンボリックリンクとして配置されるため、相対パスを使うとリンク元とリンク先でパス解決が異なり、予期しないエラーが発生します。

# OKcontext: ${DEVBASE_ROOT}/containers/general/# NG（シンボリックリンク経由で解決できない場合がある）context: ../../containers/general/

5.2 env_file の読み込み順序

env_file は上から順に読み込まれ、後の指定が前の指定を上書きします。この順序を活用して、環境変数を適切に階層化してください。

flowchart LR
A["${DEVBASE_ROOT}/.env<br/>グローバル共通"] --> B["env<br/>プロジェクト設定"]
B --> C[".env<br/>プロジェクト機密"]
style A fill:#e8f4fd
style B fill:#d4edda
style C fill:#fff3cd

5.3 ボリューム設計

用途	ボリューム名パターン	マウント先	共有範囲
AI 設定・共有ファイル	`devbase_home_ubuntu`	`/persistent/ai`	全コンテナ共有
作業ディレクトリ	`${COMPOSE_PROJECT_NAME}_work_${CONTAINER_INDEX:-1}`	`/work`	コンテナ専用

devbase_home_ubuntu（/persistent/ai）は AI CLI 設定・SSH 鍵・共有ファイルなど、コンテナ横断で共有したい設定の永続化に使用（~/.claude 等は entrypoint が symlink。旧 /home/ubuntu 直接マウントは廃止）
作業ディレクトリボリュームはプロジェクトごと・コンテナインデックスごとに独立

5.4 コンテナイメージの選択

プロジェクトの要件に応じて適切なベースイメージを選択してください。

イメージ	ベース	主要ツール	推奨用途
`base`	Ubuntu Noble	Docker CLI、Python 3	軽量な開発環境
`general`	base	AWS CLI、gcloud、Terraform、Node.js 20、AI CLI	汎用開発
`go`	base	Go開発環境	Go言語プロジェクト
`php`	general	PHP 8.3、Composer	PHP 8.3 系プロジェクト
`php85`	general	PHP 8.5、Composer	PHP 8.5 系プロジェクト
`latex`	general	LaTeX	文書・論文作成
`lfm`	general	Rust、gfortran、MeCab	数値計算・自然言語処理
`snapshot`	Ubuntu Noble	zstd	スナップショット専用

5.5 Git管理のガイドライン

# Git管理対象
plugin.yml
projects/*/compose.yml
projects/*/env
# Git管理対象外（.gitignoreに追加）
projects/*/.env
projects/*/.docker-compose.scale.yml

次のステップ

plugin.yml リファレンス -- 全フィールドの詳細仕様
compose.yml ガイドライン -- compose.yml の記述ルールとテンプレート

Navigation Menu

Uh oh!

プラグイン開発クイックスタート

前提条件

1. Pluginリポジトリの作成

1.1 Gitリポジトリの初期化

1.2 plugin.yml の配置

2. 最小構成のプロジェクト作成

2.1 ディレクトリ構造

2.2 compose.yml の作成

2.3 project.yml の作成

2.3.1 env ファイル（ファイルは必須・中身は任意）

2.4 .env ファイル（任意）

2.5 ライフサイクルフック（任意）

フックへ渡る環境変数

`pre-up` の例

3. ローカルでの開発・テスト

3.1 リンクインストール

3.2 環境の初期化と起動

3.3 動作確認

3.4 開発中のトラブルシューティング

4. 公開

4.1 GitHubリポジトリへのpush

4.2 レジストリへの登録

4.3 インストール確認

5. ベストプラクティス

5.1 パスの記述

5.2 env_file の読み込み順序

5.3 ボリューム設計

5.4 コンテナイメージの選択

5.5 Git管理のガイドライン

次のステップ

Uh oh!

FilesExpand file tree

quickstart.md

Latest commit

History

quickstart.md

File metadata and controls

プラグイン開発クイックスタート

前提条件

1. Pluginリポジトリの作成

1.1 Gitリポジトリの初期化

1.2 plugin.yml の配置

2. 最小構成のプロジェクト作成

2.1 ディレクトリ構造

2.2 compose.yml の作成

2.3 project.yml の作成

2.3.1 env ファイル（ファイルは必須・中身は任意）

2.4 .env ファイル（任意）

2.5 ライフサイクルフック（任意）

フックへ渡る環境変数

pre-up の例

3. ローカルでの開発・テスト

3.1 リンクインストール

3.2 環境の初期化と起動

3.3 動作確認

3.4 開発中のトラブルシューティング

4. 公開

4.1 GitHubリポジトリへのpush

4.2 レジストリへの登録

4.3 インストール確認

5. ベストプラクティス

5.1 パスの記述

5.2 env_file の読み込み順序

5.3 ボリューム設計

5.4 コンテナイメージの選択

5.5 Git管理のガイドライン

次のステップ

`pre-up` の例