frappe-manager

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