The purpose of this document is to give you an overview of how the Frappe Docker containers are structured.

🐳 Images

There are four predefined Dockerfiles available in the /images directory.

Dockerfile	Ingredients	Purpose & Use Case
bench	Sets up only the Bench CLI.	Used for development or debugging. Provides the command-line tooling but does not include runtime services.
custom	Multi-purpose Python backend built from a plain Python image. Includes everything needed to run a Frappe instance via a Compose setup. Installs apps defined in apps.json.	Suitable for production and testing. Ideal when you need control over dependencies (e.g. trying new Python or Node versions).
layered	Final contents are the same as custom, but it is based on prebuilt images from Docker Hub.	Great for production builds when you’re fine with the dependency versions managed by Frappe. Builds much faster since the base layers are already prepared.
production	Similar to custom (built from a Python base image), but installs only Frappe and ERPNext. Not customizable with apps.json.	Best for quick starts or exploration. For real deployments or CI/CD pipelines, custom or layered are preferred because they offer more flexibility.

---

These images include everything needed to run all processes required by the Frappe framework (see Bench Procfile reference).

• The bench image only sets up the CLI tool.
• The other images (custom, layered, and production) go further — enabling a nearly plug-and-play setup for ERPNext and custom apps.

We use multi-stage builds and Docker Buildx to maximize layer reuse and make our builds more efficient.

🏗️ Compose

Once images are built, containers are orchestrated using a compose file. The main compose.yaml provides core services, networking, and volumes for any Frappe setup.

🛠️ Services

Service	Role	Purpose
configurator	Setup	Updates common_site_config.json so Frappe knows how to access db and redis. It is executed on every docker-compose up (and exited immediately). Other services start after this container exits successfully
backend	Runtime	Werkzeug server
frontend	Proxy	nginx server that serves JS/CSS assets and routes incoming requests
websocket	Real-time	Node server that runs Socket.IO
queue-_	Background Jobs	Python servers that run job queues using rq
scheduler	Task Automation	Python server that runs tasks on schedule using schedule

🧩 Overrides

Additional functionality can be added using overrides. These files modify existing services or add new ones without changing the main compose.yaml.

Example: The main compose file has no database service, but compose.mariadb.yaml adds MariaDB. See overrides.md for the complete list of available overrides and how to use them.

---

Next: Build Setup →

See also: Setup Examples for practical deployment scenarios.