frappe_docker

For developers transitioning from Django, Frappe uses different terminology and architectural patterns. While Django is often used for consumer web apps, Frappe is optimized for business applications (ERP, CRM) with built-in multi-tenancy, background jobs, and real-time capabilities.

Conceptual Mapping

Key Architectural Differences

• Multi-tenancy: Django typically uses one app per database. Frappe allows one installation to host many sites, each with its own database.
• Background Jobs: Django requires Celery, Redis, and worker setup. Frappe has a built-in queue system using enqueue().
• Real-time: Django requires Channels, Redis, and ASGI. Frappe has Socket.IO built-in for automatic DocType updates.
• API: Django requires manual DRF setup. Frappe provides automatic REST and RPC from DocType definitions.

The interaction flow between services follows this pattern:

User Request Flow:

1. frontend (Nginx): Serves static files directly or routes requests to the backend.
2. backend (Werkzeug): Processes dynamic content and interacts with the database and cache.
3. db (MariaDB/Postgres) & redis-cache: Provide data persistence and caching.

Background Task Flow:

1. scheduler triggers tasks.
2. Tasks are placed in redis-queue.
3. queue-short/long workers consume and execute the tasks.

Real-time Flow:

1. websocket (Socket.IO) communicates with the client and interacts with redis-cache.

User Request
    ↓
[frontend (Nginx)] → Static files served directly
    ↓
[backend (Werkzeug)] → Dynamic content processing
    ↓                    ↓
[db (MariaDB)]      [redis-cache]

Background Tasks:
[scheduler] → [redis-queue] → [queue-short/long workers]

Real-time:
[websocket (Socket.IO)] ←→ [redis-cache]

Frappe Docker uses different volume types to manage data persistence and development workflows:

1. Bind Mounts (./host/path:/container/path): Connects a host directory to a container directory. Best for development (editing code on host) and configuration (overriding files with :ro for read-only).
2. Named Volumes (volume_name:/container/path): Managed by Docker. Best for production data (e.g., MariaDB/MySQL databases) to ensure persistence across container deletions.
3. Anonymous Volumes (/container/path): Managed by Docker. Best for temporary/cache data.

Performance Tip (macOS/Windows): Since Docker runs in a VM on these platforms, use mount flags to optimize speed:

• :cached: Host writes are buffered. Recommended for most development.
• :delegated: Container writes are buffered. Best for heavy container writes.
• :consistent: Full synchronization. Slowest but safest.

services:
  backend:
    volumes:
      # Development: Edit code on host
      - ./my_custom_app:/home/frappe/frappe-bench/apps/my_custom_app
      # Configuration: Read-only override
      - ./custom-config.json:/home/frappe/frappe-bench/sites/common_site_config.json:ro
      # Performance optimized for macOS/Windows
      - ./development:/home/frappe/frappe-bench:cached

  db:
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

A Frappe custom app follows a specific directory structure to organize business logic, data models, and assets. Key components include:

• hooks.py: Configures the app and defines hooks into the Frappe lifecycle.
• modules.txt: Lists the business modules contained within the app.
• my_custom_app/config/desktop.py: Defines workspace icons and shortcuts.
• my_custom_app/my_module/doctype/: Contains the data models (DocTypes), including Python controllers (.py), JSON schema definitions (.json), and frontend logic (.js).
• my_custom_app/public/: Stores static assets like CSS, JS, and images.
• my_custom_app/templates/: Contains Jinja2 templates for web pages.
• my_custom_app/www/: Contains web pages accessible via specific routes.
• requirements.txt: Lists Python package dependencies.

my_custom_app/
├── hooks.py                          # App configuration and hooks into Frappe lifecycle
├── modules.txt                       # List of business modules in this app
├── my_custom_app/
│   ├── __init__.py
│   ├── config/
│   │   └── desktop.py                # Desktop workspace icons and shortcuts
│   ├── my_module/
│   │   ├── doctype/
│   │   │   ├── customer/
│   │   │   │   ├── customer.py       # Python controller (business logic)
│   │   │   │   ├── customer.json     # Model definition (schema, validation)
│   │   │   │   └── customer.js       # Frontend logic (UI interactions)
│   │   └── page/
│   ├── public/
│   ├── templates/
│   └── www/
└── requirements.txt                  # Python package dependencies

In Frappe Docker, assets are managed using a symlink strategy to decouple build-time artifacts from persistent site data. This prevents stale assets from surviving image updates and ensures that assets always match the version of the container image being run.

The Architecture

During the image build, assets are moved from the sites/assets directory to a top-level assets/ directory. The sites/assets path is then replaced with a symlink pointing to the top-level directory.

At runtime, the directory structure looks like this:

/home/frappe/frappe-bench/
├── assets/          ← image layer (ephemeral, always matches the image)
├── sites/
│   ├── assets -> /home/frappe/frappe-bench/assets    ← symlink
│   ├── common_site_config.json                       ← persisted in volume
│   └── <site>/                                       ← persisted in volume
└── logs/            ← persisted in volume

Volume Persistence Mapping

Because the symlink is recreated in the container ENTRYPOINT, it automatically repairs older or pre-existing sites volumes that might not contain the symlink.

If you are coming from a Django background, use this mapping to understand Frappe's core abstractions:

Key Architectural Differences

• Multi-tenancy: While Django typically maps one app to one database, a single Frappe installation supports many sites, each with its own database.
• Background Jobs: Unlike Django which requires Celery, Redis, and worker setup, Frappe has a built-in queue system accessible via enqueue().
• Real-time: Frappe includes Socket.IO built-in for automatic DocType updates, whereas Django requires Channels, Redis, and ASGI setup.
• API: Frappe provides automatic REST and RPC endpoints derived directly from DocType definitions, avoiding the manual setup of serializers and views required in Django REST Framework (DRF).