frappe-ops-bench

Bench CLI 完全リファレンス

サイト管理、アプリのライフサイクル、設定、マルチテナンシーに関する Bench CLI の完全リファレンスです。

バージョン：v14/v15/v16

---

クイックリファレンス：基本コマンド

タスク	コマンド
bench を作成	bench init myproject --frappe-branch version-15
サイトを作成	bench new-site mysite.localhost --admin-password admin
デフォルトサイトを設定	bench use mysite.localhost
アプリを取得	bench get-app erpnext --branch version-15
アプリをインストール	bench --site mysite install-app erpnext
開発サーバーを起動	bench start
マイグレーションを実行	bench --site mysite migrate
アセットをビルド	bench build --app myapp
サイトをバックアップ	bench --site mysite backup
バックアップを復元	bench --site mysite restore /path/to/backup.sql.gz
コンソールを開く	bench --site mysite console
DB シェルを開く	bench --site mysite mariadb
スケジューラーを確認	bench doctor
保留中のジョブを表示	bench show-pending-jobs
すべてを更新	bench update
サイトを削除	bench drop-site mysite --force

---

ワークフロー 1：新しい bench の作成

# Initialize bench with specific Frappe version
bench init myproject --frappe-branch version-15

# With Python version
bench init myproject --frappe-branch version-15 --python python3.11

# Enter bench directory (REQUIRED for all subsequent commands)
cd myproject

bench init が作成するもの：

myproject/
├── apps/           # Installed Frappe apps (frappe is default)
├── sites/          # All sites and shared config
│   └── common_site_config.json
├── config/         # Redis, Procfile, supervisor configs
├── env/            # Python virtual environment
├── logs/           # Log files
└── Procfile        # Process definitions for bench start

重要なルール

• 必ず --frappe-branch を指定して、Frappe のバージョンを固定します
• 必ず bench ディレクトリ内からコマンドを実行します
• 絶対に root として bench コマンドを実行しないでください。専用の frappe ユーザーを使用します

---

ワークフロー 2：サイト管理

サイトの作成

# Basic site creation
bench new-site mysite.localhost --admin-password admin

# With specific database
bench new-site mysite.localhost --db-name mysite_db --admin-password admin

# With MariaDB root password
bench new-site mysite.localhost --mariadb-root-password rootpass --admin-password admin

# Install apps during creation
bench new-site mysite.localhost --admin-password admin --install-app erpnext

デフォルトサイトの設定

bench use mysite.localhost
# OR set environment variable for current session:
export FRAPPE_SITE=mysite.localhost

サイトの削除

bench drop-site mysite.localhost --force
# Deletes database and archives site directory

サイトのディレクトリ構造

sites/mysite.localhost/
├── site_config.json     # Site-specific config (db credentials)
├── private/             # Auth-required files, backups
├── public/              # Publicly accessible files
├── locks/               # Scheduler lock files
└── task-logs/           # Scheduler task logs

---

ワークフロー 3：アプリ管理

# Download app from GitHub
bench get-app erpnext --branch version-15
bench get-app https://github.com/org/custom-app.git --branch main

# Install app on a site
bench --site mysite install-app erpnext

# List installed apps
bench --site mysite list-apps

# Remove app from site (creates backup first)
bench --site mysite uninstall-app custom_app

# Remove app from bench entirely
bench remove-app custom_app

# Switch app branch
bench switch-to-branch version-15 erpnext frappe

# Exclude app from updates
bench exclude-app custom_app

# Re-include app in updates
bench include-app custom_app

重要なルール

• install-app の前に必ず get-app を実行します。get はダウンロード、install は有効化を行います
• uninstall-app の前に必ずバックアップします。アプリ関連データが削除されます
• アプリのフォルダーを絶対に手動で削除しないでください。bench remove-app を使用します

---

ワークフロー 4：bench update の動作

# Full update (pull + migrate + build + restart)
bench update

# Update specific app only
bench update --pull --app erpnext

# Skip build step
bench update --no-build

# Skip backup
bench update --no-backup

# Reset to upstream (DESTROYS local changes)
bench update --reset

bench update は次の手順を順番に実行します：

1. すべてのサイトをバックアップします
2. すべてのアプリの最新コードを取得します（git pull）
3. Python/Node の要件をインストールします
4. 静的アセットをビルドします（bench build）
5. すべてのサイトでマイグレーションを実行します（bench migrate）
6. bench のプロセスを再起動します

重要なルール

• 実行に時間がかかるため、必ず screen/tmux セッション内で bench update を実行します
• git reset --hard が実行されることを理解していない場合、本番環境で --reset を絶対に使用しないでください
• 必ず最初にステージング環境で更新をテストします

---

ワークフロー 5：bench migrate

# Migrate specific site
bench --site mysite migrate

# Migrate all sites
bench --site all migrate

# Check if safe to migrate (no pending jobs)
bench --site mysite ready-for-migration

bench migrate の実行内容：

1. スキーマを同期します（DocType の変更 → データベース）
2. パッチを実行します（データのマイグレーション）
3. 検索インデックスを再構築します
4. 翻訳を同期します
5. Dashboard キャッシュを再構築します

マイグレーションを実行するタイミング

• bench update の後（自動的に実行されます）
• hooks.py を変更した後
• DocType を追加または変更した後
• コードの変更をプルした後
• コード変更後にマイグレーションを絶対に省略しないでください。スキーマの不整合につながります

---

ワークフロー 6：bench build

# Build all apps
bench build

# Build specific app
bench build --app myapp

# Build with bundle analyzer
bench build --app myapp --production

# Watch mode (auto-rebuild on file changes)
bench watch

ビルドするタイミング

• JS/CSS ファイルを変更した後
• bench get-app の後（自動的に実行されます）
• package.json を変更した後
• クライアント側のアセットを変更した後は、必ずビルドします

---

ワークフロー 7：コンソールとデータベースへのアクセス

# IPython console (with Frappe loaded)
bench --site mysite console
# In console:
# >>> frappe.get_doc("Sales Invoice", "INV-001")
# >>> frappe.db.sql("SELECT name FROM `tabUser` LIMIT 5")

# Auto-reload on code changes
bench --site mysite console --autoreload

# MariaDB shell
bench --site mysite mariadb
# >>> SELECT name, email FROM tabUser LIMIT 5;

# PostgreSQL shell
bench --site mysite postgres

# Execute a method directly
bench --site mysite execute myapp.tasks.daily_cleanup
bench --site mysite execute myapp.api.process --kwargs '{"name": "INV-001"}'

# Make authenticated request as Administrator
bench --site mysite request GET /api/resource/User

---

ワークフロー 8：バックアップと復元

# Backup (database + files)
bench --site mysite backup
# Creates: sites/mysite/private/backups/
#   YYYY-MM-DD_HHMMSS-mysite-database.sql.gz
#   YYYY-MM-DD_HHMMSS-mysite-files.tar
#   YYYY-MM-DD_HHMMSS-mysite-private-files.tar

# Backup all sites
bench backup-all-sites

# Backup with encryption
bench --site mysite backup --backup-encryption-key mykey

# Restore from backup
bench --site mysite restore /path/to/database.sql.gz

# Restore with files
bench --site mysite restore /path/to/database.sql.gz \
  --with-public-files /path/to/files.tar \
  --with-private-files /path/to/private-files.tar

# Partial restore
bench --site mysite partial-restore /path/to/database.sql.gz

重要なルール

• bench update、uninstall-app、drop-site の前に必ずバックアップします
• 24 時間より古いバックアップはデフォルトで自動削除されます。keep_backups_for_hours を設定してください
• バックアップを頼りにする前に、ステージングサイトで復元を必ずテストします

---

ワークフロー 9：スケジューラーとバックグラウンドジョブ

# Enable/disable scheduler
bench --site mysite scheduler enable
bench --site mysite scheduler disable
bench --site mysite scheduler pause
bench --site mysite scheduler resume

# Check scheduler health
bench doctor

# View queued jobs
bench show-pending-jobs

# Purge pending jobs
bench --site mysite purge-jobs

# Manually trigger scheduler event
bench --site mysite trigger-scheduler-event hourly

# Start worker manually (for debugging)
bench worker --queue short

---

ワークフロー 10：マルチテナンシー

DNS ベースのルーティング（推奨）

# Enable DNS multi-tenancy
bench config dns_multitenant on

# Create sites with proper hostnames
bench new-site site1.example.com --admin-password admin
bench new-site site2.example.com --admin-password admin

# Regenerate nginx config
bench setup nginx

# Reload nginx
sudo service nginx reload

リクエストは、Host ヘッダーとサイト名を照合してルーティングされます。

ポートベースのルーティング（代替方式）

bench config dns_multitenant off
bench new-site site2.localhost --admin-password admin
bench set-nginx-port site2.localhost 8082
bench setup nginx
sudo service nginx reload

カスタムドメインのマッピング

# Add domain to site
bench setup add-domain site1.example.com --site mysite
bench setup nginx
sudo service nginx reload

---

設定：common_site_config.json

sites/common_site_config.json にあり、すべてのサイトに適用されます。

必須キー

キー	デフォルト	用途
background_workers	1	バックグラウンドジョブのワーカー数
developer_mode	false	DocType の変更をファイルに自動同期
dns_multitenant	false	DNS ベースのマルチテナンシーを有効化
gunicorn_workers	2	Web サーバーのワーカー数（最小：2）
maintenance_mode	0	すべてのサイトをオフラインにする
pause_scheduler	0	ジョブスケジューラーを一時停止
serve_default_site	—	ホストが一致しない場合のデフォルトサイト
server_script_enabled	false	Server Scripts を有効化
scheduler_tick_interval	60	スケジューラーのチェック間隔（秒）
webserver_port	8000	開発サーバーのポート
socketio_port	9000	Socket.IO のポート
live_reload	false	アセット再ビルド時に自動リロード

Redis の設定

キー	デフォルト
redis_cache	redis://localhost:13000
redis_queue	redis://localhost:11000
redis_socketio	redis://localhost:13000

設定値の指定

# Set common config (all sites)
bench config set-common-config -c background_workers 4
bench config set-common-config -c developer_mode 1

# Set site-specific config
bench --site mysite set-config developer_mode 1
bench --site mysite set-config maintenance_mode 1

# View current config
bench --site mysite show-config

---

設定：site_config.json

サイトごとの設定ファイルは sites/<sitename>/site_config.json です。

必須キー

キー	用途
db_type	mariadb または postgres
db_name	データベース名
db_password	データベースのパスワード

重要なオプションキー

キー	用途
admin_password	管理者の初期パスワード
host_name	サイトの完全な URL（プロトコルを含む）
install_apps	復元／再インストール時にインストールするアプリ
allow_cors	CORS オリジン（"*"、URL、または配列）
max_file_size	アップロード上限（デフォルト：10MB）
mute_emails	すべての送信メールを無効化
logging	デバッグレベル（0～2、レベル 2 では SQL クエリを表示）

環境変数による上書き

環境変数は設定ファイルより優先されます。キーの対応関係：FRAPPE_REDIS_QUEUE、FRAPPE_REDIS_CACHE、FRAPPE_DB_HOST、FRAPPE_DB_PORT、FRAPPE_DB_NAME、FRAPPE_DB_PASSWORD。

優先順位：環境変数 > site_config.json > common_site_config.json > デフォルト

---

本番環境のセットアップ

sudo bench setup production frappe-user   # nginx + supervisor + fail2ban
bench setup lets-encrypt mysite.example.com  # SSL
sudo bench restart                          # Restart services
bench disable-production                    # Back to development

---

バージョンの違い

機能	V14	V15	V16
bench init	はい	はい	はい
スケジューラーのチェック間隔	約240秒	約240秒	60秒
db_user 設定（個別）	いいえ	いいえ	はい
console --autoreload	いいえ	はい	はい
trim-tables コマンド	いいえ	はい	はい
trim-database コマンド	いいえ	はい	はい
request コマンド	いいえ	はい	はい
Gettext 翻訳	いいえ	いいえ	はい

---

参照ファイル

ファイル	内容
commands.md	すべてのオプションを含むコマンドの完全なリファレンス
examples.md	一般的なワークフローの例
custom-commands.md	Click を使ったカスタム bench CLI コマンドの作成
anti-patterns.md	よくある bench の誤りと修正方法