Frappe Manager

Manage Docker-based Frappe development environments using Frappe Manager (FM).

使用Frappe Manager（FM）管理基于Docker的Frappe开发环境。

When to use

使用场景

Setting up a local Frappe development environment
Creating isolated test environments
Agent-driven development (vibe coding) workflows
Quick prototyping without full bench setup
Reproducible environments across machines

搭建本地Frappe开发环境
创建隔离测试环境
Agent驱动的开发（沉浸式编码）工作流
无需完整bench环境即可快速原型开发
跨设备可复现的环境

Inputs required

必要前置条件

Docker installed and running
Python 3.11+ with pipx
Site/bench name
Apps to install (frappe, erpnext, hrms, custom)
Environment type (dev/prod)

已安装并运行Docker
安装Python 3.11及以上版本并配备pipx
站点/bench名称
待安装的应用（frappe、erpnext、hrms、自定义应用）
环境类型（开发/生产）

Procedure

操作步骤

0) Install Frappe Manager

0) 安装Frappe Manager

bash

undefined

bash

undefined

Install via pipx

通过pipx安装

pipx install frappe-manager

Enable shell completion

启用shell自动补全

fm --install-completion

undefined

fm --install-completion

undefined

1) Create a site

1) 创建站点

bash

undefined

bash

undefined

Basic site (frappe only)

基础站点（仅含frappe）

fm create mysite

Site with ERPNext

包含ERPNext的站点

fm create mysite --apps erpnext:version-15

Site with multiple apps

包含多个应用的站点

fm create mysite --apps erpnext --apps hrms --environment dev

Production site with SSL

带SSL的生产站点

fm create example.com --apps erpnext --env prod --ssl letsencrypt

undefined

fm create example.com --apps erpnext --env prod --ssl letsencrypt

undefined

2) Manage sites

2) 管理站点

bash

undefined

bash

undefined

List all sites

列出所有站点

fm list

Start/stop site

启动/停止站点

fm start mysite fm stop mysite

View site info

查看站点信息

fm info mysite

View logs (follow)

查看日志（实时追踪）

fm logs mysite -f

Delete site

删除站点

fm delete mysite

undefined

fm delete mysite

undefined

3) Development workflow

3) 开发工作流

bash

undefined

bash

undefined

Access shell inside container

进入容器内部的shell

fm shell mysite

Inside container - common commands:

容器内常用命令：

bench new-app my_custom_app bench --site mysite install-app my_custom_app bench --site mysite migrate bench build --app my_custom_app bench --site mysite run-tests --app my_custom_app

Exit shell

退出shell

exit

Open in VSCode

在VSCode中打开

fm code mysite

Open with debugger

开启调试模式打开

fm code mysite --debugger

undefined

fm code mysite --debugger

undefined

4) Agent-driven development

4) Agent驱动的开发

Perfect for AI agents developing Frappe apps:

bash

undefined

非常适合AI Agent开发Frappe应用：

bash

undefined

1. Setup: Create fresh environment

1. 环境准备：创建全新环境

fm create testsite --apps erpnext:version-15 --environment dev fm start testsite

2. Develop: Enter shell, create app

2. 开发阶段：进入shell，创建应用

fm shell testsite bench new-app my_app bench --site testsite install-app my_app

... make code changes ...

... 进行代码修改 ...

exit

3. Test: Run tests

3. 测试阶段：运行测试

fm shell testsite bench --site testsite run-tests --app my_app exit

4. Verify: Check logs

4. 验证阶段：查看日志

fm logs testsite -f

5. Reset if needed: Start fresh

5. 重置环境（如需）：重新创建干净环境

fm stop testsite fm delete testsite fm create testsite --apps erpnext:version-15 --environment dev

undefined

fm stop testsite fm delete testsite fm create testsite --apps erpnext:version-15 --environment dev

undefined

5) Internal service management (fmx)

5) 内部服务管理（fmx）

Inside the container, use

fmx

for service control:

bash

fm shell mysite

fmx status      # Check service status
fmx restart     # Restart Frappe services
fmx start       # Start services
fmx stop        # Stop services

在容器内部，可使用

fmx

控制服务：

bash

fm shell mysite

fmx status      # 查看服务状态
fmx restart     # 重启Frappe服务
fmx start       # 启动服务
fmx stop        # 停止服务

Verification

验证项

Site accessible at http://mysite.localhost
Can login with admin credentials (default: admin/admin)
Custom app installed and visible
Tests run successfully inside container
Logs show no critical errors

可通过http://mysite.localhost访问站点
可使用管理员凭据登录（默认账号：admin/admin）
自定义应用已安装并可见
容器内测试运行成功
日志中无严重错误

Failure modes / debugging

故障排查

Docker not running: Start Docker daemon
Port conflict: Use different site name or check port 80/443
Site not accessible: Check
```
fm list
```
for status, try
```
fm start
```
App not installing: Check
```
fm logs
```
for errors
Slow startup: First run downloads images—be patient

Docker未运行：启动Docker守护进程
端口冲突：使用其他站点名称或检查80/443端口
站点无法访问：执行
```
fm list
```
查看状态，尝试运行
```
fm start
```
应用安装失败：查看
```
fm logs
```
获取错误信息
启动缓慢：首次运行会下载镜像，请耐心等待

Escalation

进阶指引

For advanced Docker config, see references/docker-config.md
For SSL issues, see references/ssl-setup.md
For bench commands, see references/bench-commands.md

如需高级Docker配置，请查看references/docker-config.md
如需解决SSL问题，请查看references/ssl-setup.md
如需了解bench命令，请查看references/bench-commands.md

References

参考资料

references/fm-commands.md - Full FM command reference
references/agent-workflow.md - Agent development patterns
references/bench-commands.md - Bench CLI inside container
https://github.com/rtCamp/Frappe-Manager

references/fm-commands.md - FM命令完整参考
references/agent-workflow.md - Agent开发模式
references/bench-commands.md - 容器内的Bench CLI
https://github.com/rtCamp/Frappe-Manager

Guardrails

注意事项

Always backup before operations: Run
```
fm backup <site>
```
before major changes or updates
Use named sites: Avoid generic names; use descriptive site names for project identification
Check SSH access: Ensure SSH keys are configured for private repos before app installation
Verify Docker status: Run
```
fm doctor
```
to check Docker and FM health before operations
Use
fm shell
for commands: Always enter container shell before running bench commands

操作前务必备份：在进行重大变更或更新前，执行
```
fm backup <site>
```
使用命名站点：避免使用通用名称，采用具有描述性的站点名称以便项目识别
检查SSH访问权限：安装应用前，确保已为私有仓库配置SSH密钥
验证Docker状态：操作前执行
```
fm doctor
```
检查Docker和FM的健康状态
使用
fm shell
执行命令：运行bench命令前务必进入容器shell

Common Mistakes

常见错误

Mistake	Why It Fails	Fix
Running bench commands outside `fm shell`	"Command not found" or wrong site	Always `fm shell <site>` first
Wrong site context	Operations affect wrong site	Check prompt shows correct site; use `bench --site <site>`
Missing volumes on recreate	Data loss	Use `fm recreate --keep-volumes` or backup first
Not checking `fm doctor`	Silent configuration issues	Run `fm doctor` to diagnose problems
Using `localhost` in site URL	DNS resolution issues	Use `<site>.localhost` format for local access
Forgetting to `fm start` after reboot	Site not accessible	Run `fm start <site>` or `fm start --all`

错误操作	失败原因	修复方案
在 `fm shell` 外运行bench命令	出现"命令未找到"或操作对象为错误站点	始终先执行 `fm shell <站点名>`
站点上下文错误	操作影响了错误的站点	检查命令行提示符显示的站点是否正确；使用 `bench --site <站点名>` 指定站点
重建时未保留卷	数据丢失	使用 `fm recreate --keep-volumes` 或提前备份
未检查 `fm doctor` 结果	存在隐性配置问题	执行 `fm doctor` 诊断问题
站点URL使用 `localhost`	DNS解析问题	本地访问时采用 `<站点名>.localhost` 格式
重启后忘记执行 `fm start`	站点无法访问	执行 `fm start <站点名>` 或 `fm start --all`

frappe-manager

Original

Translation

Frappe Manager

Frappe Manager

When to use

使用场景

Inputs required

必要前置条件

Procedure

操作步骤

0) Install Frappe Manager

0) 安装Frappe Manager

Install via pipx

通过pipx安装

Enable shell completion

启用shell自动补全

1) Create a site

1) 创建站点

Basic site (frappe only)

基础站点（仅含frappe）

Site with ERPNext

包含ERPNext的站点

Site with multiple apps

包含多个应用的站点

Production site with SSL

带SSL的生产站点

2) Manage sites

2) 管理站点

List all sites

列出所有站点

Start/stop site

启动/停止站点

View site info

查看站点信息

View logs (follow)

查看日志（实时追踪）

Delete site

删除站点

3) Development workflow

3) 开发工作流

Access shell inside container

进入容器内部的shell

Inside container - common commands:

容器内常用命令：

Exit shell

退出shell

Open in VSCode

在VSCode中打开

Open with debugger

开启调试模式打开

4) Agent-driven development

4) Agent驱动的开发

1. Setup: Create fresh environment

1. 环境准备：创建全新环境

2. Develop: Enter shell, create app

2. 开发阶段：进入shell，创建应用

... make code changes ...

... 进行代码修改 ...

3. Test: Run tests

3. 测试阶段：运行测试

4. Verify: Check logs

4. 验证阶段：查看日志

5. Reset if needed: Start fresh

5. 重置环境（如需）：重新创建干净环境

5) Internal service management (fmx)

5) 内部服务管理（fmx）

Verification

验证项

Failure modes / debugging

故障排查

Escalation

进阶指引

References

参考资料

Guardrails

注意事项

Common Mistakes

常见错误