724d761eb6
Move container-setup directory from 08-reference/ to 02-setup/ to follow PR feedback. The container-setup documentation provides a more linear and coherent flow compared to the previous unstructured setup files. Changes: - Move container-setup/ from docs/08-reference/ to docs/02-setup/ - Integrate content from setup-options.md into structured flow: - Create new 06-setup-examples.md with practical deployment scenarios - Enhance 03-start-setup.md with site creation details from setup-options - Remove redundant 01-setup-options.md (content now integrated) - Rename 02-single-server-example.md to 07-single-server-example.md - Update all cross-references throughout documentation: - Update README.md with new structure under Setup section - Fix links in site-operations.md and migration docs - Add navigation links between container-setup files and examples - Maintain container-setup's linear flow: overview → build → start → env → overrides - Add practical examples document (06-setup-examples.md) that follows the container-setup guide Result: Documentation now follows a clear progression from conceptual overview through practical examples, with all setup information properly organized under 02-setup/.
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.