# frappe_docker: Running ERPNext and Frappe Apps in Containers

> frappe_docker is the official container setup for Frappe applications, with a disposable demo file and a production Compose stack. It is a good fit if you accept the opinionated layout; it is the wrong tool if you want a single container or a non-Docker install.

**frappe/frappe_docker** — Docker environment for developing, deploying, and running Frappe applications (ERPNext and custom apps) in production and development

- Repository: https://github.com/frappe/frappe_docker
- Website: https://frappe.github.io/frappe_docker/
- Stars: 2,576 · Forks: 2,733
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/frappe-frappe-docker

## What frappe_docker solves, and who it is for

Frappe applications are not a single process. A working ERPNext install needs a web backend, a worker queue, a scheduler, Redis for cache and queue, a database, and a socket server for realtime updates. Wiring those by hand on every host is the problem this repository addresses. It is the official container setup for Frappe applications, and the README lists its audience directly: 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.

The repository is explicit about its scope. It contains Docker images, Compose configurations and documentation; the README says it is "only for container related stuff" and points contributors to the Frappe framework, ERPNext and Frappe Bench repositories for the application code itself. That boundary matters when you are deciding where to file a bug. If your site fails during a database migration, the container project is probably not the place to look first.

The maintainers keep the project current: the last push was on 2026-09-08, and releases v3.2.0, v3.2.1 and v3.2.2 landed between 2026-05-03 and 2026-08-05. That cadence tells you the Compose files and images are being revised, not frozen.

## How the Compose stack is put together

The base production file is compose.yaml, and it is worth reading before you run anything, because the shape of the stack explains most of the operational behaviour. It defines YAML anchors for reuse. The customizable_image anchor sets the image to ${CUSTOM_IMAGE:-frappe/erpnext} tagged with ${CUSTOM_TAG:-$ERPNEXT_VERSION}, and the comment above it notes that by default the image contains only the frappe and erpnext apps, with a link to docs/02-setup/02-build-setup.md for custom apps. The pull_policy defaults to always and the restart policy defaults to unless-stopped.

A second anchor, depends_on_configurator, makes services wait for the configurator container to finish successfully. The backend defaults combine both anchors and mount a named volume, sites, at /home/frappe/frappe-bench/sites. That volume is where your site data lives, so it is the thing to back up and the thing to preserve across upgrades.

The configurator service is the interesting part. It runs a bash command that lists the apps directory into sites/apps.txt and then calls bench set-config repeatedly to write global configuration: db_host, db_port, redis_cache, redis_queue, redis_socketio (kept, per the comment, for backward compatibility), socketio_port, and chromium_path pointing at /usr/bin/chromium-headless-shell. It reads DB_HOST, DB_PORT, REDIS_CACHE and REDIS_QUEUE from the environment, sets SOCKETIO_PORT to 9000, and restarts on failure. In other words, the database and Redis connection details are injected at container start rather than baked into an image. The backend service exposes GUNICORN_THREADS, GUNICORN_WORKERS and GUNICORN_TIMEOUT, defaulting to 4, 2 and 120.

Both the configurator and backend declare platform: linux/amd64. On an ARM host this is a constraint you have to plan for, and the repository keeps a dedicated page at docs/01-getting-started/03-arm64.md.

## frappe_docker installation: the disposable demo first

The README's prerequisites are Docker, Docker Compose v2 and git. The fastest path is the single-file demo, which the README describes as a quick disposable demo and warns is for short-lived evaluation only. Clone the repository and bring the stack up:

```bash
git clone https://github.com/frappe/frappe_docker
cd frappe_docker
docker compose -f pwd.yml up -d
```

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 credentials it gives are username Administrator and password admin. If the page does not load, the create-site logs are the first place to look, since site creation is a separate container that has to complete before the web front end is useful.

The README is blunt about the limits of this setup: you will not be able to install custom apps into it, and it is not for production. Treat pwd.yml as a way to see whether ERPNext is something you want to run, not as a starting point you later promote.

For anything beyond evaluation, the README points to the full documentation, in particular docs/getting-started.md and docs/01-getting-started/01-choosing-a-deployment-method.md, which is where the choice between deployment methods is made. The production entry point is compose.yaml, and the overrides/ directory holds Compose overrides for common deployment patterns. The repository also ships example.env, which is the file to copy when you need to set variables such as CUSTOM_IMAGE, CUSTOM_TAG, DB_HOST or REDIS_CACHE rather than relying on the defaults.

## Custom apps and the image you actually deploy

The default image is narrow on purpose. The comment in compose.yaml states that the image used by default contains only the frappe and erpnext apps, and links to docs/02-setup/02-build-setup.md under the heading "Define custom apps". If your deployment includes HRMS, a custom Frappe app, or a patched fork of ERPNext, you are expected to build your own image and point CUSTOM_IMAGE and CUSTOM_TAG at it. The images/ directory holds the Dockerfiles for that, and docker-bake.hcl is present at the repository root for builds driven by Buildx bake.

This is the main architectural decision the project pushes onto you. The Compose file is a template that assumes an image exists; producing that image is your job. The payoff is that the running containers stay immutable and the same image can be promoted between environments, which is the usual reason to containerise an ERP in the first place. The cost is a build pipeline you now own, including the rebuild whenever you add an app or change its dependencies.

The repository also carries development-specific material. The development/ directory holds development environment configurations, and devcontainer-example/ provides a VS Code devcontainer setup, so a contributor can work on Frappe code inside a container rather than installing Bench on the host. install_x11_deps.sh at the root is a hint that some workflows expect a display, which is a different setup from the headless production stack.

## Where frappe_docker is the wrong tool

The demo file is the clearest case. The README's warning block says the setup is intended for short-lived evaluation only and that custom apps cannot be installed to it. Anyone who runs pwd.yml, builds a site, and then tries to add an app has chosen the wrong file, and the failure is by design rather than a bug.

The second case is architecture. Both the configurator and backend services in compose.yaml pin platform: linux/amd64. The repository acknowledges ARM64 with a dedicated document, but the base production file does not present itself as architecture-neutral. If you are targeting an ARM server or an Apple Silicon machine for production, read docs/01-getting-started/03-arm64.md before you plan the deployment, and expect to make decisions the amd64 path does not require.

The third case is scale and orchestration. What the repository provides is Docker Compose: a single-host model with a named sites volume and a configurator that runs once per start. Compose has no scheduler that reschedules a failed worker onto another machine, and the sites volume ties the stack to one host. If your requirement is multi-node failover, this repository is a starting point for images and configuration, not the orchestrator you need.

Finally, the documentation is spread across docs/, the published site, and a GitHub wiki FAQ. The README links the FAQ to the wiki rather than to a file in docs/, so a search of the repository alone will not surface every answer.

## How this differs from running Frappe Bench directly

Frappe Bench is the conventional way to run Frappe applications, and it is the alternative most people weigh against containers. Bench installs and manages the apps, sites, Python environment, Node dependencies, process manager and reverse proxy on the host itself. The repository's own Resources section links to Frappe Bench alongside the framework and ERPNext, which is a fair signal that the two are complementary rather than competing: frappe_docker packages the runtime that Bench would otherwise install.

The practical difference shows up in what you maintain. With Bench, the host accumulates the Python and Node toolchain, and an upgrade means updating that toolchain in place. With frappe_docker, you build an image, the Compose file references it, and the configurator service writes the database and Redis settings into the bench configuration at startup. Upgrades become image swaps, and the sites volume is the only stateful piece to preserve. The trade is that you now need image builds and a registry or a local build step, plus an understanding of the anchors and environment variables in compose.yaml.

A second alternative, for the demo-only case, is not to use containers at all and to follow the upstream Bench install instructions, since the disposable Compose file is explicitly not a production path. Choosing between them comes down to whether you want the host to be disposable. If you do, the container route is the one this repository implements.

## Licence, maintenance and upgrade cost

The repository is licensed under the MIT License, with the LICENSE file at the root. MIT is permissive, so it permits reuse and modification with few conditions, but it is a licence for this repository's own contents: the Dockerfiles, Compose files, scripts and documentation. It says nothing about the licences of the Frappe framework, ERPNext or any other application you build into an image. If you are shipping a product on top of ERPNext, the licence that governs your obligations is the application's, not frappe_docker's. That is a question for your own legal review, not something this repository answers.

On maintenance, the observable facts are the release history and the last push on 2026-09-08. Three releases landed between May and August 2026, which is a steady cadence rather than a burst. There is no archived flag on the repository.

The upgrade cost you should budget for is not the Compose file, which changes rarely, but the image. Because the default image carries only frappe and erpnext, every added app is a rebuild, and every rebuild is a chance for a dependency change to surface. The sites volume survives upgrades, but the configurator rewrites the global bench configuration on each start, so any setting you changed by hand inside the container is not preserved. Put your settings in the environment and the override files rather than inside a running container.

## Conclusion

Adopt frappe_docker if you are deploying ERPNext, CRM or Helpdesk on a host you control and you are comfortable with Docker Compose, the sites volume and the configurator service. Do not adopt it if you need a single-container deployment, if you cannot run linux/amd64 images, or if you want to install custom apps into the disposable demo, which the README explicitly rules out. Before committing, verify that your host satisfies the Docker and Docker Compose v2 prerequisites, check the ARM64 notes if you are not on amd64, and read docs/02-setup/02-build-setup.md to decide how custom apps will enter your image.

## FAQ

### What is frappe_docker?

It is the official container setup for Frappe applications, providing Docker images, Compose configurations and documentation for running ERPNext, CRM, Helpdesk and other Frappe apps in containers. The repository states that it covers container-related work only, with the framework and applications living in their own repositories.

### How can I use Frappe on Docker?

The README's fastest path is the single-file demo: clone the repository, then run docker compose -f pwd.yml up -d, wait for the ERPNext site to be created or check the create-site container logs, and open port 8080 with username Administrator and password admin. The README describes this as short-lived evaluation only and says custom apps cannot be installed to it; production setups use compose.yaml and the overrides directory.

### how to install frappe docker

Install Docker, Docker Compose v2 and git as the README's prerequisites require, clone https://github.com/frappe/frappe_docker, then run docker compose -f pwd.yml up -d for the demo. For anything beyond evaluation, the README directs you to the documentation under docs/, starting with the getting started guide and the page on choosing a deployment method.

### What is the difference between ERPNext and Frappe?

The repository treats them as separate projects. Its Resources section links to the Frappe framework and ERPNext as distinct repositories, and the default image comment in compose.yaml says the image contains both the frappe and erpnext apps, which is why the image is named frappe/erpnext. frappe_docker packages and runs them; it does not define either.

## Sources

- [frappe/frappe_docker on GitHub](https://github.com/frappe/frappe_docker)
- [License: MIT](https://github.com/frappe/frappe_docker/blob/main/LICENSE)
- [Project website](https://frappe.github.io/frappe_docker/)
- [README](https://github.com/frappe/frappe_docker/blob/main/README.md)
- [Releases](https://github.com/frappe/frappe_docker/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/frappe-frappe-docker