Frappe Docker Installation Guide for Cursor

Safvan_Ph · July 27, 2025, 7:14am

This guide will help you install and set up Frappe Framework with Docker using Cursor IDE.

Prerequisites

System Requirements

Operating System: Linux (Ubuntu 20.04+ recommended), macOS, or Windows with WSL2
Docker: Version 20.10+ with Docker Compose
Cursor IDE: Latest version
Git: For cloning repositories
Python: 3.8+ (for the installer script)
Node.js: 18.x (for frontend development)

Required Software

Docker & Docker Compose

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Python Dependencies

# Install Python 3.8+
sudo apt update
sudo apt install python3 python3-pip python3-venv

# Install bench CLI
sudo pip3 install frappe-bench

Node.js Setup

# Install Node Version Manager (nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Reload shell configuration
source ~/.bashrc

# Install Node.js 18 (recommended for Frappe)
nvm install 18
nvm use 18
nvm alias default 18

# Verify installation
node --version  # Should show v18.x.x
npm --version   # Should show 9.x.x or higher

# Install Yarn (used by Frappe)
npm install -g yarn

Installation Steps

Step 1: Clone the Repository

# Create your development directory
mkdir frappe-development
cd frappe-development

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

Step 2: Configure Apps (Optional)

Create or modify apps.json to specify which Frappe apps to install:

[
  {
    "url": "https://github.com/frappe/erpnext.git",
    "branch": "version-15"
  },
  {
    "url": "https://github.com/frappe/frappe.git",
    "branch": "version-15"
  }
]

Step 3: Run the Installer Script

Use the provided installer script with your preferred options:

# Basic installation
python3 installer.py

# Custom installation with specific options
python3 installer.py \
  --bench-name my-frappe-bench \
  --site-name myapp.localhost \
  --admin-password mypassword \
  --db-type mariadb \
  --frappe-branch version-15 \
  --verbose

Step 4: Start Docker Services

# Start all services
docker-compose up -d

# Check service status
docker-compose ps

Step 5: Initialize the Site

# Navigate to your bench directory
cd frappe-bench

# Create a new site
bench new-site myapp.localhost \
  --db-host mariadb \
  --db-type mariadb \
  --db-root-password 123 \
  --admin-password admin

# Install apps
bench --site myapp.localhost install-app erpnext

VS Code/Cursor Development Setup

Step 6: Configure Cursor for Development

The repository includes pre-configured VS Code/Cursor settings for optimal development experience:

1. Python Interpreter Configuration

Create .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/frappe-bench/env/bin/python"
}

2. Recommended Extensions

Create .vscode/extensions.json:

{
  "recommendations": [
    "ms-python.python",
    "ms-python.vscode-pylance",
    "ms-vscode.vscode-json",
    "redhat.vscode-yaml",
    "ms-azuretools.vscode-docker"
  ]
}

3. Debug Configurations

Create .vscode/launch.json for debugging Frappe applications:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Bench Web",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/frappe-bench/apps/frappe/frappe/utils/bench_helper.py",
      "args": [
        "frappe",
        "serve",
        "--port",
        "8000",
        "--noreload",
        "--nothreading"
      ],
      "pythonPath": "${workspaceFolder}/frappe-bench/env/bin/python",
      "cwd": "${workspaceFolder}/frappe-bench/sites",
      "env": {
        "DEV_SERVER": "1"
      }
    },
    {
      "name": "Bench Short Worker",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/frappe-bench/apps/frappe/frappe/utils/bench_helper.py",
      "args": ["frappe", "worker", "--queue", "short"],
      "pythonPath": "${workspaceFolder}/frappe-bench/env/bin/python",
      "cwd": "${workspaceFolder}/frappe-bench/sites",
      "env": {
        "DEV_SERVER": "1"
      }
    },
    {
      "name": "Bench Long Worker",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/frappe-bench/apps/frappe/frappe/utils/bench_helper.py",
      "args": ["frappe", "worker", "--queue", "long"],
      "pythonPath": "${workspaceFolder}/frappe-bench/env/bin/python",
      "cwd": "${workspaceFolder}/frappe-bench/sites",
      "env": {
        "DEV_SERVER": "1"
      }
    }
  ]
}

Step 7: Install Recommended Extensions in Cursor

Python Extension: For Python language support
Pylance: For advanced Python language features
Docker Extension: For Docker container management
YAML Extension: For docker-compose.yml files
JSON Extension: For configuration files

Step 8: Development Workflow in Cursor

Using Debug Configurations

Open the Debug panel in Cursor (Ctrl+Shift+D)
Select “Bench Web” configuration
Press F5 to start debugging
Set breakpoints in your Python code
Use the debug console for interactive debugging

Running Bench Commands

Use Cursor’s integrated terminal:

# Execute bench commands in container
docker-compose exec frappe-python bench --site myapp.localhost migrate

# Access container shell
docker-compose exec frappe-python bash

# View logs
docker-compose logs -f frappe-python

Code Navigation and IntelliSense

Go to Definition: Ctrl+Click on any function/class
Find All References: Shift+F12
Auto-completion: Available for Python, JavaScript, and HTML
Error Detection: Real-time syntax and type checking

Configuration Options

Installer Script Parameters

Parameter	Description	Default	Recommended
`--bench-name`	Bench directory name	`frappe-bench`	`frappe-bench`
`--site-name`	Site name (must end with .localhost)	`development.localhost`	`development.localhost`
`--admin-password`	Admin password for the site	`admin`	`admin`
`--db-type`	Database type (mariadb/postgres)	`mariadb`	`mariadb`
`--frappe-branch`	Frappe branch to use	`version-15`	`version-15`
`--apps-json`	Path to apps configuration	`apps-example.json`	`apps-example.json`
`--py-version`	Python version	Not set	`3.10`
`--node-version`	Node.js version	Not set	`18`
`--verbose`	Enable verbose output	False	`True`

Environment Variables

# Set Python version
export PYENV_VERSION=3.10

# Set Node version
export NVM_VERSION=18

Docker Services

The installation sets up the following Docker services:

frappe-python: Frappe application server
frappe-nginx: Web server
mariadb: Database server
redis-cache: Redis cache
redis-queue: Redis queue
redis-socketio: Redis for Socket.IO

Development Workflow

Starting Development

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f frappe-python

Making Code Changes

Edit files in Cursor: All Frappe files are mounted as volumes
Auto-reload: Frappe automatically reloads on file changes
Bench commands: Run bench commands inside the container
Debugging: Use Cursor’s debug configurations for step-by-step debugging

# Execute bench commands
docker-compose exec frappe-python bench --site myapp.localhost migrate

Stopping Services

# Stop all services
docker-compose down

# Stop and remove volumes (WARNING: This will delete data)
docker-compose down -v

Troubleshooting

Common Issues

Port Conflicts

# Check if ports are in use
sudo netstat -tulpn | grep :80
sudo netstat -tulpn | grep :8000

Permission Issues

# Fix Docker permissions
sudo chown -R $USER:$USER .

Database Connection Issues

# Check database status
docker-compose logs mariadb

# Reset database
docker-compose down -v
docker-compose up -d

Memory Issues

# Increase Docker memory limit
# Edit Docker Desktop settings or increase system memory

Cursor/VS Code Issues

# Reload Cursor window
Ctrl+Shift+P -> "Developer: Reload Window"

# Reset Python interpreter
Ctrl+Shift+P -> "Python: Select Interpreter"

Logs and Debugging

# View all logs
docker-compose logs

# View specific service logs
docker-compose logs frappe-python

# Follow logs in real-time
docker-compose logs -f

Accessing Your Application

Frappe/ERPNext: http://localhost:8000
Site: http://myapp.localhost:8000
Admin: http://myapp.localhost:8000/app

Default Credentials

Username: Administrator
Password: admin (or your custom password)

Advanced Configuration

Custom Docker Compose

Create docker-compose.override.yml for custom configurations:

version: "3.7"
services:
  frappe-python:
    environment:
      - PYTHONPATH=/workspace/development/frappe-bench/apps
    volumes:
      - ./custom-apps:/workspace/development/frappe-bench/apps/custom-apps

Multiple Sites

# Create additional sites
bench new-site site2.localhost --db-host mariadb --db-type mariadb --db-root-password 123 --admin-password admin
bench --site site2.localhost install-app erpnext

Best Practices

Backup Regularly

# Backup database
bench --site myapp.localhost backup

Use Version Control

# Initialize git repository
git init
git add .
git commit -m "Initial Frappe setup"

Environment Management

# Create environment-specific configurations
cp .env.example .env.production

Cursor-Specific Tips
- Use the integrated terminal for all Docker commands
- Leverage debug configurations for step-by-step debugging
- Use the file explorer to navigate between apps
- Enable auto-save for seamless development

Support and Resources

Official Documentation: Introduction
GitHub Repository: GitHub - frappe/frappe_docker: Docker images for production and development setups of the Frappe framework and ERPNext
Community Forum: https://discuss.frappe.io
VS Code/Cursor Development: https://github.com/frappe/frappe_docker/blob/main/docs/development.md

Quick Start Commands

# Complete setup in one go
git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker
python3 installer.py --verbose --node-version 18 --py-version 3.10
docker-compose up -d

# Open in Cursor
cursor .

Your Frappe Docker environment is now ready for development in Cursor with full debugging capabilities!