frappe-ops-deployment

本番環境へのデプロイ

従来方式（bench + Nginx + Supervisor）または Docker（frappe_docker + Compose）を使用して、Frappe/ERPNext を本番環境にデプロイします。Frappe は、新規デプロイには Docker を公式に推奨しています。

クイックリファレンス

# Traditional production setup (one command)
sudo bench setup production [frappe-user]

# What it configures:
# 1. Supervisor — process management (gunicorn, workers, Redis, socketio)
# 2. Nginx — reverse proxy, static files, websocket proxy
# 3. Sudoers — allows frappe-user to restart services

# Individual setup commands
bench setup supervisor          # Generate supervisor config
bench setup nginx               # Generate nginx config
bench setup sudoers $(whoami)   # Allow service restarts without password

# Symlink configs into system directories
sudo ln -s $(pwd)/config/supervisor.conf /etc/supervisor/conf.d/frappe-bench.conf
sudo ln -s $(pwd)/config/nginx.conf /etc/nginx/conf.d/frappe-bench.conf

# SSL setup
sudo -H bench setup lets-encrypt [site-name]
sudo -H bench setup lets-encrypt [site-name] --custom-domain [domain]

# DNS multitenancy (multiple sites on port 80/443)
bench config dns_multitenant on
bench setup nginx
sudo service nginx reload

---

デプロイ方法の判断ツリー

Which deployment method?
|
+-- New server, minimal ops experience?
|   +-- Docker (frappe_docker) — recommended by Frappe
|
+-- Existing server with bench already installed?
|   +-- Traditional (bench setup production)
|
+-- Need custom Frappe apps or complex build?
|   +-- Docker with custom image build
|
+-- Cloud hosting (AWS/GCP/Azure)?
|   +-- Docker on VM or Kubernetes
|   +-- OR Frappe Cloud (managed)
|
+-- Single site or multi-site?
|   +-- Single site: standard setup
|   +-- Multi-site: DNS multitenancy required

---

従来方式でのデプロイ

プロセスアーキテクチャ

Internet → Nginx (port 80/443)
               |
               +-- Static files served directly
               +-- /api, /app → Gunicorn (port 8000)
               +-- /socket.io → Node.js socketio (port 9000)

Supervisor manages:
  - frappe-bench-web (gunicorn)
  - frappe-bench-socketio (node)
  - frappe-bench-worker-short
  - frappe-bench-worker-default
  - frappe-bench-worker-long
  - frappe-bench-redis-cache
  - frappe-bench-redis-queue
  - frappe-bench-schedule (scheduler)

セットアップ手順

# 1. Install bench (as non-root user)
sudo pip3 install frappe-bench
bench init frappe-bench --frappe-branch version-15
cd frappe-bench

# 2. Create site
bench new-site mysite.example.com
bench --site mysite.example.com install-app erpnext

# 3. Production setup (configures nginx + supervisor + sudoers)
sudo bench setup production $(whoami)

# 4. Verify processes are running
sudo supervisorctl status

# 5. Verify nginx config
sudo nginx -t && sudo systemctl reload nginx

Nginx の設定

bench setup nginx は、以下を含む config/nginx.conf を生成します。

• サイトごとのサーバーブロック（DNS マルチテナンシー）
• ポート 8000 の gunicorn へのプロキシ
• ポート 9000 の socketio への WebSocket プロキシ
• sites/ ディレクトリからの静的ファイル配信
• クライアントの最大本文サイズ（デフォルト値はバージョンによって異なります）

ポート 80 の競合を避けるため、必ずデフォルトの nginx サイトを無効にしてください。

sudo rm /etc/nginx/sites-enabled/default
# OR disable: sudo mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf.bak

Supervisor の設定

bench setup supervisor は、以下を含む config/supervisor.conf を生成します。

• Redis を外部で管理している場合にスキップする --skip-redis フラグ

CentOS/RHEL の場合は、Supervisor の設定に .conf ではなく .ini 拡張子を使用してください。

---

SSL / HTTPS

Let's Encrypt（推奨）

# Automated setup with cron renewal
sudo -H bench setup lets-encrypt mysite.example.com

# For custom domain (site name differs from domain)
sudo -H bench setup lets-encrypt mysite.example.com --custom-domain www.example.com

# Manual renewal
sudo bench renew-lets-encrypt

前提条件：

• DNS マルチテナンシーが有効であること（bench config dns_multitenant on）
• ドメインがサーバーの IP アドレスを指していること
• ACME チャレンジ用にポート 80 が開放されていること
• root/sudo アクセス権があること

証明書の保存場所：/etc/letsencrypt/live/example.com/

• fullchain.pem — 証明書と中間証明書チェーン
• privkey.pem — 秘密鍵

証明書は 90 日ごとに期限切れになります。セットアップコマンドによって、更新用の月次 cron が追加されます。

カスタム SSL 証明書

# 1. Place certificate files
sudo mkdir -p /etc/nginx/conf.d/ssl
sudo cp certificate.crt /etc/nginx/conf.d/ssl/
sudo cp private.key /etc/nginx/conf.d/ssl/
sudo chmod 600 /etc/nginx/conf.d/ssl/private.key

# 2. Configure site
bench set-config ssl_certificate "/etc/nginx/conf.d/ssl/certificate.crt"
bench set-config ssl_certificate_key "/etc/nginx/conf.d/ssl/private.key"

# 3. Regenerate and reload
bench setup nginx
sudo systemctl reload nginx

SSL の設定後、すべての HTTP トラフィックは自動的に HTTPS にリダイレクトされます。

---

DNS マルチテナンシー（マルチサイト）

# Enable DNS-based site routing
bench config dns_multitenant on

# Create sites with domain names
bench new-site site1.example.com
bench new-site site2.example.com

# Regenerate nginx (creates server blocks per site)
bench setup nginx
sudo systemctl reload nginx

サイト名には、必ず実際のドメインを使用してください。Nginx は Host ヘッダーに基づいて、リクエストを適切なサイトに振り分けます。

---

Docker でのデプロイ

アーキテクチャ（frappe_docker）

Docker Compose Services:
  - configurator  — initializes DB/Redis config (runs once)
  - backend       — Frappe/ERPNext application server (gunicorn)
  - frontend      — Nginx reverse proxy
  - websocket     — Node.js Socket.IO server
  - queue-short   — RQ worker for short jobs
  - queue-long    — RQ worker for long jobs
  - (external)    — MariaDB/PostgreSQL + Redis (separate containers or managed)

Shared Volume:
  - sites:/home/frappe/frappe-bench/sites (persistent data)

本番環境向け Docker Compose

# Clone frappe_docker
git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker

# Use compose.yaml for production
# Key environment variables:
#   DB_HOST, DB_PORT — database connection
#   REDIS_CACHE, REDIS_QUEUE — Redis endpoints
#   FRAPPE_SITE_NAME_HEADER — for multi-site routing
#   PROXY_READ_TIMEOUT — upstream timeout
#   CLIENT_MAX_BODY_SIZE — upload limit (default 50m)

docker compose -f compose.yaml up -d

カスタムイメージのビルド

# Build custom image with your apps
export APPS_JSON='[
  {"url":"https://github.com/frappe/erpnext","branch":"version-15"},
  {"url":"https://github.com/your-org/custom-app","branch":"main"}
]'

docker build \
  --build-arg APPS_JSON_BASE64=$(echo $APPS_JSON | base64 -w 0) \
  --tag your-registry/custom-erpnext:latest \
  images/custom/

---

セキュリティ強化

ファイアウォール（UFW）

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
# NEVER expose ports 8000, 9000, 6379, 3306 to the internet

Fail2Ban

sudo apt install fail2ban
sudo systemctl enable fail2ban

# /etc/fail2ban/jail.local
# [sshd]
# enabled = true
# maxretry = 5
# bantime = 3600

Redis 認証

# Secure Redis for multi-bench environments
bench create-rq-users --set-admin-password
# Generates unique passwords per bench for Redis auth

その他のセキュリティ強化

• root の SSH ログインを必ず無効にしてください（/etc/ssh/sshd_config の PermitRootLogin no）
• SSH キー認証を必ず使用し、パスワード認証を無効にしてください
• bench を root で実行しないでください。専用の frappe ユーザーを作成してください
• システムパッケージを必ず最新の状態に保ってください（sudo apt update && sudo apt upgrade）
• site_config.json の ALLOW_CORS は、信頼できるドメインのみに必ず設定してください

---

ゼロダウンタイム更新

# Traditional deployment
bench update --pull --patch --build --requirements
# Supervisor auto-restarts workers after update

# Docker deployment
# 1. Pull new image
docker compose pull
# 2. Recreate containers (rolling)
docker compose up -d --no-deps backend websocket queue-short queue-long
# 3. Run migrations
docker compose exec backend bench --site mysite.example.com migrate

---

バージョンごとの差異

機能	v14	v15	v16
Docker の推奨	いいえ	公式に推奨	はい
create-rq-users	いいえ	はい	はい
ARM64 Docker イメージ	いいえ	はい	はい
サイトレベルのログ	v13+	はい	はい
extend_doctype_class	いいえ	いいえ	はい

---

参考ファイル

ファイル	内容
examples.md	デプロイスクリプトと設定の完全な例
anti-patterns.md	よくあるデプロイの失敗
workflows.md	デプロイの手順

関連スキル

• frappe-ops-backup — バックアップと災害復旧
• frappe-ops-performance — パフォーマンスの調整
• frappe-ops-bench — Bench CLI リファレンス
• frappe-ops-upgrades — バージョンアップグレードの手順