Setup Frappe development environment in a few minutes (frappe_docker)

mohamed-ameer · September 12, 2025, 5:12pm

Frappe Docker Development Environment Setup Guide

Overview

This setup gives you everything you need to start building apps with Frappe immediately —
without the pain of installing and configuring Python, Node, Redis, and MariaDB on your computer.

Using Docker, you get:

Start fast – just clone, open, and code. No messy dependencies.
Safe & clean – your computer stays untouched.
Same setup for everyone – no more “works on my machine” problems.
Easy reset – if something breaks, reset in one command.
Team-friendly – your teammates use the exact same environment.

Think of this as a fast road for developers:
you skip the boring setup and jump straight into building apps, testing ideas, and shipping features.

Quick Start Summary

Prerequisites

Docker Desktop installed and running
Visual Studio Code with Remote Containers extension
Git installed

Setup Steps

Step 1: Clone and Setup

git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker
cp -R devcontainer-example .devcontainer
cp -R development/vscode-example development/.vscode
code .

Step 2: Install VS Code Extension

Press Ctrl+Shift+X
Install: ms-vscode-remote.remote-containers

Step 3: Open in Container

Press Ctrl+Shift+P
Select: Dev Containers: Reopen in Container
Wait for container to build (5-10 minutes first time)

Step 4: Initialize Frappe Bench

bench init --skip-redis-config-generation frappe-bench
cd frappe-bench

Step 5: Configure Database & Redis

bench set-config -g db_host mariadb
bench set-config -g redis_cache redis://redis-cache:6379
bench set-config -g redis_queue redis://redis-queue:6379
bench set-config -g redis_socketio redis://redis-queue:6379

Step 6: Create Your Site

bench new-site --db-root-password 123 --admin-password admin --mariadb-user-host-login-scope=% your_site_name.localhost

Step 7: Start Development Server

bench start

Step 8: Access Your Site

Open browser: http://development.localhost:8000
Login with admin/admin

Daily Workflow

Starting Development Session:

Open VS Code
Navigate to frappe_docker folder
Press Ctrl+Shift+P → Dev Containers: Reopen in Container
Wait for container to start
Open terminal and run bench start

Stopping Development Session:

Press Ctrl+Shift+P → Dev Containers: Reopen Folder Locally
This closes the container and returns you to your local system

Detailed Setup Process

Prerequisites

Before starting, ensure you have:

Docker Desktop installed and running
Visual Studio Code with Remote Containers extension
Git for cloning repositories
Basic knowledge of Frappe framework

Step 1: Clone and Setup Frappe Docker

# Clone the frappe_docker repository
git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker

# Copy development container configuration
cp -R devcontainer-example .devcontainer
cp -R development/vscode-example development/.vscode

# Open in Visual Studio Code
code .

Step 2: Install Required Extensions

Press Ctrl+Shift+X to open Extensions
Search for and install: ms-vscode-remote.remote-containers
Wait for installation to complete

Step 3: Open in Container

Press Ctrl+Shift+P to open Command Palette
Type and select: Dev Containers: Reopen in Container
Wait for container to build and start (first time may take 5-10 minutes)

Step 1,2,3 (as a one step): Container Environment Setup

Why This Step?

The development container provides a pre-configured environment with all necessary tools and dependencies for Frappe development.

What Happens?

Docker builds a container with Python, Node.js, MariaDB, Redis, and other dependencies
VS Code connects to the container, giving you a full development environment
All your code runs inside the container, isolated from your host system

Step 4: Initialize Frappe Bench

Once inside the container, open the terminal and run:

# Initialize a new Frappe bench (skip Redis config as it's handled by Docker)
bench init --skip-redis-config-generation frappe-bench

# Navigate to the bench directory
cd frappe-bench

Why `--skip-redis-config-generation`?

Docker handles Redis configuration automatically, so we skip the default Redis setup to avoid conflicts.

Step 5: Configure Database and Redis Connections

# Configure database connection to use Docker MariaDB
bench set-config -g db_host mariadb

# Configure Redis connections for different purposes
bench set-config -g redis_cache redis://redis-cache:6379
bench set-config -g redis_queue redis://redis-queue:6379
bench set-config -g redis_socketio redis://redis-queue:6379

What Each Configuration Does:

db_host mariadb: Points to the MariaDB container
redis_cache: Used for caching data
redis_queue: Used for background job processing
redis_socketio: Used for real-time communication

Verify Configuration:

# Check if configuration is correct
cat frappe-bench/sites/common_site_config.json

Expected output should show:

{
    "db_host": "mariadb",
    "redis_cache": "redis://redis-cache:6379",
    "redis_queue": "redis://redis-queue:6379",
    "redis_socketio": "redis://redis-queue:6379"
}

Step 6: Create Your First Site

# Create a new site (replace 'your_site_name' with your preferred name)
bench new-site --db-root-password 123 --admin-password admin --mariadb-user-host-login-scope=% your_site_name.localhost

Parameters Explained:

--db-root-password 123: MariaDB root password (Docker default)
--admin-password admin: Frappe admin user password
--mariadb-user-host-login-scope=%: Allows connections from any host
your_site_name.localhost: Your site name (use .localhost for local development)

Step 7: Start Development Server

# Start the Frappe development server
bench start

What Happens:

Frappe starts the web server
All services (MariaDB, Redis) are automatically started
Your site becomes accessible at http://development.localhost:8000

Development Workflow

Daily Development Routine

Starting Your Development Session:

Open VS Code
Navigate to your frappe_docker folder
Press Ctrl+Shift+P → Dev Containers: Reopen in Container
Wait for container to start
Open terminal and run bench start

Stopping Your Development Session:

Press Ctrl+Shift+P → Dev Containers: Reopen Folder Locally
This closes the container and returns you to your local system

Working with Multiple Sites

# Create additional sites
bench new-site --db-root-password 123 --admin-password admin --mariadb-user-host-login-scope=% site2.localhost

# List all sites
bench list-sites

# Switch between sites
bench use site1.localhost
bench use site2.localhost

Installing Apps

# Install ERPNext
bench get-app erpnext
bench --site your_site_name.localhost install-app erpnext

# Install custom apps
bench get-app https://github.com/your-username/your-app.git
bench --site your_site_name.localhost install-app your_app

Errors may happen if you switch from frappe v16 to v15

❌ NameError: name 'null' is not defined

Cause:
This usually happens due to cached assets or browser issues after switching branches.

Solutions:

Run: bench clear-cache
Or try accessing with a different browser

Reference

❌ bench stop / bench start fails: Missing module (e.g., "Cannot find module 'superagent'")

Cause:
Node.js dependencies are missing after switching branches.

Solution:
Re-install required packages:

bench setup requirements

Reference

❌ ValueError: id must not contain ":"

Cause:
Older Frappe version had a bug in job ID generation (create_job_id in frappe/utils/backgroundjobs.py).

Solution:

Best fix: Update to the latest Frappe version.

Manual fix: Update the function to replace : with |:

def create_job_id(job_id: str | None = None) -> str:
	"""
	Generate unique job id for deduplication
	"""
	if not job_id:
		job_id = str(uuid4())
	else:
		job_id = job_id.replace(":", "|")
	return f"{frappe.local.site}||{job_id}"

Reference

For More Details => Read the Official Documentaion

Happy coding!

revant_one · September 13, 2025, 2:11am

Check this script frappe_docker/docs/development.md at main · frappe/frappe_docker · GitHub

Once inside devcontainer, execute it.

samy4sam · September 15, 2025, 3:14pm

We created a PR today that will significantly improve the performance of the development environment on computers with ARM-based CPUs:

yourGuy · October 21, 2025, 6:57am

How do I work with local code and not code from a git repo ?

Peer · October 21, 2025, 7:54am

Then you need to know what you are doing, lest you loose your local code!

yourGuy · October 22, 2025, 2:59am

I’m here to learn, can you explain what I “need to know“ ?

Peer · October 22, 2025, 6:02am

You can build your app in the apps directory of your bench, but this could be overwritten under certain circumstances which you should be aware of and able to know/recognize beforehand. If not, you might lose your work.

You can also have a local (e.g. on your dev computer; better: on another computer in the LAN, better because if the dev station dies, you still have the repo; you can also use another self-owned git repo even “more elsewhere”, but short of having it at an organizational entity you have no control over) git repo, but it should reside elsewhere than in said above apps directory of your bench, simply in order to use it for one layer of fast and immediate backup just in case. (Note that “local” can have several meanings, depending on your awareness of the dangers coming from updates and errors by yourself, other devs, hardware failure, changes made by external organizations.)

You need to know enough about git to not shoot yourself in the foot, e.g. with “git hard –reset” command or other git commands that help you destroy parts of or whole projects if used inadvertently or when tired or so.

Some bench commands, or also frappe script constructs, can be destructive. Sometimes they warn by saying so with terminology “only do this if you know what you are doing” in the documentation or CLI messages. So know what you are doing, and be wary that there might be no such warning if using the framework, because for some reason it’s not there albeit it should be or would be better to be there.

Happy developing! It’s a lot of fun, but there are risks of many different kinds.

Setup Frappe development environment in a few minutes (frappe_docker)

Frappe Docker Development Environment Setup Guide

Overview

Quick Start Summary

Prerequisites

Setup Steps

Step 1: Clone and Setup

Step 2: Install VS Code Extension

Step 3: Open in Container

Step 4: Initialize Frappe Bench

Step 5: Configure Database & Redis

Step 6: Create Your Site

Step 7: Start Development Server

Step 8: Access Your Site

Daily Workflow

Starting Development Session:

Stopping Development Session:

Detailed Setup Process

Prerequisites

Step 1: Clone and Setup Frappe Docker

Step 2: Install Required Extensions

Step 3: Open in Container

Step 1,2,3 (as a one step): Container Environment Setup

Why This Step?

What Happens?

Step 4: Initialize Frappe Bench

Why --skip-redis-config-generation?

Step 5: Configure Database and Redis Connections

What Each Configuration Does:

Verify Configuration:

Step 6: Create Your First Site

Parameters Explained:

Step 7: Start Development Server

What Happens:

Development Workflow

Daily Development Routine

Starting Your Development Session:

Stopping Your Development Session:

Working with Multiple Sites

Installing Apps

Errors may happen if you switch from frappe v16 to v15

❌ NameError: name 'null' is not defined

❌ bench stop / bench start fails: Missing module (e.g., "Cannot find module 'superagent'")

❌ ValueError: id must not contain ":"

For More Details => Read the Official Documentaion

Why `--skip-redis-config-generation`?