frappe_docker: The Official Container Setup for Frappe, ERPNext and Custom Apps
Docker environment for developing, deploying, and running Frappe applications (ERPNext and custom apps) in production and development
At a glance
- What is it?
- frappe_docker is the official Docker image and Compose repository for Frappe applications, covering a disposable demo, production Compose files, and image builds for custom apps. It is a deployment layer, not the Frappe framework, and its value depends on whether you want to operate the stack yourself.
- Who is it for?
- Adopt frappe_docker if you already know Frappe or are willing to learn it, and you want the container topology under your own control: start with pwd.yml to confirm the images run on your host, then move to compose.yaml plus the overrides directory for anything you intend to keep. Do not adopt it if you want a managed ERP, because this repository assumes you will handle backups, upgrades, TLS and database operations yourself.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap frappe_docker fills between Frappe source and a running deployment
Frappe applications are Python and JavaScript projects that expect a bench, a database, a cache, a scheduler and a web server to be arranged around them. The README frames this repository as "the official container setup for Frappe applications," which is a narrower claim than it might appear. The repository does not contain the Frappe framework, ERPNext, or CRM source. It contains the packaging and orchestration that turn those projects into running services.
The audience is defined by a short list in the README: people who want to run ERPNext, CRM, Helpdesk or other Frappe apps with Docker, start from a quick demo, use production-ready images and Compose setups, build custom app images, or deploy and operate Frappe in production. Every item on that list assumes the reader is willing to own the runtime. There is no hosted control plane here and no upgrade service. If your requirement is an ERP you never have to think about, this repository is upstream of the wrong decision.
What is actually in the repository and how the pieces relate
The README prints the directory layout, and it is worth reading as a map rather than a feature list. The docs directory is described as "canonical documentation for all deployment and operational workflows." The overrides directory holds "opinionated Compose overrides for common deployment patterns." compose.yaml is the base file for production setups. pwd.yml is a single-file disposable demo. images contains Dockerfiles for building Frappe images. development and devcontainer-example cover local work, and resources holds helper scripts and configuration templates.
That structure encodes a deliberate split. The base Compose file is not meant to be used alone in every situation; the overrides directory exists because common deployment patterns differ, and the documentation points to a page on choosing a deployment method. The demo file is deliberately separate and deliberately incomplete. The README states plainly that the pwd.yml setup is "intended for short-lived evaluation only" and that you "will not be able to install custom apps to this setup." That is a real constraint, not a warning label. Anyone who starts with the demo and later tries to add a custom app has to move to the image build path.
The demo path: three commands and a two-minute wait
The README gives the shortest route verbatim. Clone the repository, then run the demo Compose file:
git clone https://github.com/frappe/frappe_docker cd frappe_docker docker compose -f pwd.yml up -d
After that, the README says to wait a couple of minutes for the ERPNext site to be created, or to check the create-site container logs, before opening a browser on port 8080. The default credentials listed are Administrator with the password admin. The prerequisites are Docker, Docker Compose v2, and git, which is a low bar and the reason this path exists at all.
The create-site container is the detail worth noticing. Site creation is a job that runs inside the Compose project rather than something you do by hand, which is why the README tells you to watch its logs instead of polling the web port. If the site never appears, the logs of that specific container are the first place to look, not the web container.
Building images for custom apps, and the production Compose file
The README lists "build custom app images" as a supported use case and points at the images directory, which holds the Dockerfiles for building Frappe images. The demo warning about custom apps is the counterpart to this: custom apps are an image concern, so they belong to the build path rather than to pwd.yml.
For production, the README names compose.yaml as the base Compose file and the overrides directory as the place where deployment patterns diverge. It also links a documentation page on choosing a deployment method and a separate production docs section. The README does not enumerate the services in compose.yaml, the volume layout, or the environment variables, so those details have to come from the docs and the Compose files themselves. I cannot confirm from the supplied material which services the base file defines or how state is persisted, and I would not guess. The honest position is that the production path starts with reading compose.yaml and the overrides directory, not with copying a command from the README, because the README only gives the demo command.
Where the container setup stops and your operational work begins
The clearest limitation is stated by the project itself: pwd.yml is disposable, and custom apps cannot be installed into it. That is a hard boundary. A team that validates an ERPNext configuration in the demo and then expects to promote it will have to rebuild that configuration through the image and Compose path.
The second limitation is structural. This repository packages Frappe; it does not operate it. Backups, database migrations between Frappe versions, TLS termination, and the decision of when to upgrade are not solved by a Compose file. The README's own entry points confirm the shape of the work: there is an operations docs section and a production docs section, which exist because running this is an ongoing activity. If you do not want that activity, the correct choice is a managed Frappe host, not a better Compose file.
A third constraint is architecture. The README links an ARM64 notes page under getting started, which is a signal that ARM64 is a documented case rather than an assumed one. If you are deploying onto ARM hardware, read that page before you build anything.
How this differs from running Frappe Bench directly
The alternative most Frappe operators already know is Frappe Bench, the tool the README lists under Resources alongside the framework and ERPNext. Bench installs and manages sites on a host, typically a VM, using the host's own Python, Node and database services. frappe_docker takes the opposite approach: the application runtime is baked into images, and the services around it are described in Compose files. The difference in practice is where configuration lives. With Bench, site and app state sit in a bench directory on the machine. With frappe_docker, the image is the unit of application code, which is why installing a custom app means building an image instead of running a bench command.
That distinction decides the migration story too. Moving a Bench deployment to containers is not a copy of a directory; it is a rebuild of the environment plus a data migration. Neither approach is universally better. Bench is closer to the framework's own tooling and to most community instructions. frappe_docker gives you a repeatable image and a declarative service topology, at the cost of learning the image build path whenever your app set changes.
Licence, maintenance and what to verify before adopting
The repository is MIT licensed, and the README states that it covers container-related work only, directing framework contributions to the Frappe, ERPNext and Bench repositories. MIT is permissive, but it applies to this repository's Dockerfiles, Compose files and scripts. The Frappe applications you run inside those images carry their own licences, and the README does not address them. Check the licence of each app you deploy separately; this is a factual boundary of the repository, not legal advice.
The release cadence visible in the supplied material is roughly monthly across v3.2.0, v3.2.1 and v3.2.2, with the most recent push after the latest release. That tells you the container layer moves, and it also tells you that pinning a version is a real decision rather than a formality. Because images are built from the images directory and the base Compose file is versioned alongside them, an upgrade is a change to both the image tag and the Compose configuration.
Before adopting, verify three things directly from the repository: the services and volumes defined in compose.yaml, the ARM64 notes if your hardware is not x86, and the deployment-method page in the getting started docs, since the README explicitly defers the choice to that page. Then run pwd.yml once on the target host to confirm the images pull and the create-site container completes. If that succeeds, the production path is a reading exercise in compose.yaml and overrides, not a leap of faith.
Editorial conclusion
Adopt frappe_docker if you already know Frappe or are willing to learn it, and you want the container topology under your own control: start with pwd.yml to confirm the images run on your host, then move to compose.yaml plus the overrides directory for anything you intend to keep. Do not adopt it if you want a managed ERP, because this repository assumes you will handle backups, upgrades, TLS and database operations yourself. Before committing, verify two things from the docs and the Compose files: which services the base file defines and where state is mounted, and whether your target architecture is covered by the images you plan to build or pull.
Community notes