71cd07173b
Move all files from docs/02-setup/container-setup/ directly into docs/02-setup/ to eliminate unnecessary subfolder. Files are already numbered sequentially, so they work perfectly at the same level. Changes: - Move all files from container-setup/ subfolder to 02-setup/ root - Remove container-setup/ subfolder - Update all cross-references: - Update README.md paths (remove container-setup/ from all links) - Fix references in site-operations.md - Fix references in migration docs - Update internal references in 06-setup-examples.md - Fix relative path references in 01-overview.md, 02-build-setup.md, 03-start-setup.md Result: Cleaner, flatter structure with all numbered setup files at the same level, making navigation more straightforward.
5.7 KiB
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
benchimage only sets up the CLI tool. - The other images (
custom,layered, andproduction) 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.