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 |