Frappe Manager

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

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

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)

Procedure

0. Install Frappe Manager

Install via pipx

pipx install frappe-manager

Enable shell completion

fm --install-completion

1. Create a site

Basic site (frappe only)

fm create mysite

Site with 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

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

2. Manage sites

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

3. Development workflow

Access shell inside container

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

exit

Open in VSCode

fm code mysite

Open with debugger

fm code mysite --debugger

4. Agent-driven development

Perfect for AI agents developing Frappe apps:

1. Setup: Create fresh environment

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

2. Develop: Enter shell, create app

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

... make code changes ...

exit

3. Test: Run tests

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

4. Verify: Check logs

fm logs testsite -f

5. Reset if needed: Start fresh

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

5. Internal service management (fmx)

Inside the container, use fmx for service control:

fm shell mysite

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

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

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

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

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

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

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