Issue: The onboarding & deployment experience of Frappe/ERPNext is unnecessarily confusing for new users
Hi Frappe team,
I’m filing this issue not as a complaint for the sake of complaining, but because I genuinely believe Frappe and ERPNext are powerful products that deserve a smoother, more intuitive onboarding experience. As a new user trying to deploy ERPNext, I encountered several conceptual and UX hurdles that significantly increased the cognitive load.
Below are the key pain points.
1. Naming confusion: “Frappe” the company vs “Frappe” the framework
When someone first encounters ERPNext, the natural mental model is:
Frappe = the company behind ERPNext.
Only later do we discover:
Frappe = also the name of the underlying web framework.
This dual meaning creates unnecessary ambiguity for beginners.
It’s unclear whether documentation is referring to:
-
the company
-
the framework
-
the ecosystem
-
or all of the above
This slows down understanding and makes the learning curve steeper than it needs to be.
2. To deploy ERPNext, users are forced to understand the entire Frappe ecosystem
My goal was simple:
Deploy ERPNext.
But the actual prerequisite knowledge chain looks like this:
To deploy ERPNext,
you must understand Frappe_docker,
because to understand Frappe_docker,
you must understand Frappe,
because to understand Frappe,
you must understand Bench.
This is a very deep dependency chain for someone who just wants to run an ERP system.
It feels like the product assumes users are already experts in:
-
the Frappe framework
-
the Bench CLI
-
the Site/App architecture
-
Docker networking
-
internal naming conventions
Most users deploying ERPNext are not framework developers.
They are business owners, sysadmins, or engineers who simply want to get an ERP running.
3. Core concepts (Site, App, Bench, Frappe) lack a clear topology or mental model
The documentation introduces concepts like:
-
Frappe Framework
-
Bench
-
Site
-
App
-
Workspace
-
Containers (backend, scheduler, websocket, etc.)
…but never provides a topology diagram or a conceptual map showing how these pieces relate.
As a result, beginners struggle to form a mental model such as:
-
What is a Site?
-
Why is ERPNext an App?
-
Why does a Site need to be created manually?
-
Why does Bench exist if Docker is the recommended deployment method?
-
Why does Frappe_docker wrap Bench instead of replacing it?
Without a conceptual overview, users are left piecing together fragments across multiple docs.
4. The onboarding experience assumes users are “abstraction experts”
The entire ecosystem seems designed with the assumption that users:
-
understand the Frappe framework
-
understand Bench
-
understand Docker
-
understand multi-container orchestration
-
understand database host scopes
-
understand internal networking
-
understand the difference between framework concepts and deployment concepts
But most users are not framework contributors.
They are simply trying to deploy ERPNext for real-world business use.
The current onboarding path feels like this:
“Before you deploy ERPNext, please learn our entire internal architecture.”
This is a high barrier to entry and discourages new adopters.
Suggestions for improvement
Here are some constructive ideas that could dramatically improve the user journey:
1. Provide a single-page conceptual map
A diagram showing:
-
Frappe Framework
-
Bench
-
Site
-
App
-
ERPNext
-
Docker services
…and how they relate.
2. Provide a “Deploy ERPNext without learning Frappe” guide
A beginner-friendly path that focuses on:
-
What to run
-
Why it matters
-
What the minimal concepts are
3. Clarify naming conventions
Explain early:
-
Frappe (company)
-
Frappe Framework
-
Frappe Cloud
-
Frappe_docker
4. Reduce the dependency chain
If possible, simplify the deployment flow so users don’t need to understand Bench internals just to create a site.
Closing thoughts
ERPNext is an amazing product with huge potential.
This issue is written because I want more people to be able to adopt it without hitting the same conceptual roadblocks.
Thank you for your work, and I hope this feedback helps improve the onboarding experience for future users.