ERPNext Complete Guide 2026: Install, Configure, and Customize the Open-Source ERP

┌─────────────────────────────────────┐
│         ERPNext (Application Layer)   │
│  Finance | CRM | Sales | Purchasing | Inventory | HR  │
├─────────────────────────────────────┤
│       Frappe Framework (Framework)    │
│  DocType | REST API | Permissions | Workflow    │
├─────────────────────────────────────┤
│  Python (Backend) | MariaDB (Database)     │
│  JavaScript/Vue (Frontend) | Redis (Cache) │
└─────────────────────────────────────┘

# 1. Install Docker and Docker Compose
curl -fsSL https://get.docker.com | sh
sudo systemctl enable --now docker

# 2. Install Docker Compose (if not already included)
sudo apt install docker-compose-plugin

# 3. Clone the official docker-compose configuration
git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker

# 4. Create the environment file
cp example.env .env

# Edit .env and set these key parameters:
# SITE_NAME=erp.yourdomain.com
# DB_ROOT_USER=root
# DB_ROOT_PASSWORD=your_secure_password
# ADMIN_PASSWORD=your_admin_password

# 5. Start the services
docker compose -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.noproxy.yaml \
  config > ~/docker-compose.yml

docker compose -f ~/docker-compose.yml up -d

# 6. Create a new site
docker compose -f ~/docker-compose.yml exec backend \
  bench new-site erp.yourdomain.com \
  --mariadb-root-password your_secure_password \
  --admin-password your_admin_password \
  --install-app erpnext

# 7. Access ERPNext
# Open http://your-server-ip:8080 in your browser
# Default admin account: Administrator
# Password: the ADMIN_PASSWORD you set in .env

# Get a free SSL certificate with Let's Encrypt
docker compose -f ~/docker-compose.yml exec backend \
  bench setup nginx

# Or use Traefik for automatic HTTPS management
docker compose -f compose.yaml \
  -f overrides/compose.traefik.yaml \
  config > ~/docker-compose-traefik.yml

docker compose -f ~/docker-compose-traefik.yml up -d

# 1. Install dependencies
sudo apt update
sudo apt install python3-dev python3-setuptools python3-pip \
  python3-distutils python3.10-venv software-properties-common \
  mariadb-server mariadb-client redis-server nodejs npm \
  yarn cron xvfb libfontconfig wkhtmltopdf

# 2. Configure MariaDB
sudo mysql -u root -e "
  CREATE DATABASE erpnext;
  CREATE USER 'erpnext'@'localhost' IDENTIFIED BY 'your_password';
  GRANT ALL PRIVILEGES ON erpnext.* TO 'erpnext'@'localhost';
  FLUSH PRIVILEGES;
"

# 3. Install bench (Frappe's CLI tool)
pip3 install frappe-bench

# 4. Initialize bench
bench init --frappe-branch version-15 frappe-bench
cd frappe-bench

# 5. Create a new site
bench new-site erp.yourdomain.com \
  --db-name erpnext \
  --db-password your_password \
  --admin-password your_admin_password

# 6. Install the ERPNext app
bench get-app --branch version-15 erpnext
bench --site erp.yourdomain.com install-app erpnext

# 7. Start the development server
bench start
# Access http://localhost:8000

# Multi-company structure
If your group has multiple subsidiaries, you can add multiple companies.
ERPNext supports inter-company transactions and consolidated reporting.

Administrator (System Manager) → Full access
Accounting (Accounts Manager) → Finance module
Sales (Sales Manager) → Sales module
Warehouse (Stock Manager) → Inventory module
HR (HR Manager) → Human Resources module

# Create a user via the Frappe API (Python script)
import frappe

user = frappe.get_doc({
    "doctype": "User",
    "email": "zhangsan@company.com",
    "first_name": "Zhang",
    "last_name": "San",
    "roles": [{"role": "Sales Manager"}]
})
user.insert()

Assets
├── Current Assets
│   ├── Cash and Bank Deposits
│   ├── Accounts Receivable
│   └── Inventory
├── Fixed Assets
│   ├── Buildings
│   └── Equipment
Liabilities
├── Current Liabilities
│   ├── Accounts Payable
│   └── Short-term Borrowings
Equity
├── Paid-in Capital
└── Retained Earnings
Income
├── Operating Revenue
└── Other Income
Expenses
├── Cost of Goods Sold
├── Selling Expenses
├── Administrative Expenses
└── Financial Expenses

# Auto-generated entries for a sales invoice
Debit: Accounts Receivable         ¥10,000
    Credit: Operating Revenue         ¥8,849.56
            Output VAT Payable        ¥1,150.44

# Auto-generated entries for purchase receipt
Debit: Inventory               ¥5,000
    Credit: Accounts Payable         ¥5,000

Headquarters Warehouse
├── Zone A - Raw Materials
│   ├── A-01 Electronic Components
│   └── A-02 Structural Parts
├── Zone B - Finished Goods
│   ├── B-01 Pending Shipment
│   └── B-02 Quality Inspected
└── Zone C - Returns

# Set stock alert via Frappe script
frappe.db.set_value("Item", "ITEM-001", "re_order_level", 100)
frappe.db.set_value("Item", "ITEM-001", "warehouse", "Headquarters Warehouse")

Lead
  ↓
Opportunity
  ↓
Quotation
  ↓
Sales Order
  ↓
Delivery Note
  ↓
Sales Invoice
  ↓
Payment Entry

# Attendance policy configuration
attendance_policy = {
    "working_hours": "09:00-18:00",
    "late_entry_threshold": 15,  # minutes
    "early_exit_threshold": 15,
    "holiday_list": "2026-Statutory Holidays"
}

# Leave types
leave_types = [
    {"name": "Annual Leave", "max_leaves": 10},
    {"name": "Sick Leave", "max_leaves": 5},
    {"name": "Personal Leave", "max_leaves": 0},  # requires approval
    {"name": "Marriage Leave", "max_leaves": 3},
]

Product: Smart Speaker V2.0
├── Mainboard Assembly (x1)
│   ├── SoC (x1)
│   ├── Memory Module (x2)
│   └── WiFi Module (x1)
├── Audio Assembly (x1)
│   ├── Speaker Driver (x2)
│   └── Amplifier Board (x1)
├── Enclosure (x1)
└── Power Adapter (x1)

Production Plan
  ↓
Work Order
  ↓
Material Transfer
  ↓
Manufacture
  ↓
Quality Inspection
  ↓
Stock Entry

# 1. Create a development site
bench new-site dev.localhost --force
bench use dev.localhost

# 2. Create a custom app
bench new-app my_custom_app

# Directory structure:
# my_custom_app/
# ├── my_custom_app/
# │   ├── __init__.py
# │   ├── hooks.py          # App hook configuration
# │   ├── modules.txt        # Module list
# │   ├── custom_doctype/    # Custom DocTypes
# │   └── api.py             # Custom APIs
# └── setup.py

# Define a DocType via Python code
import frappe
from frappe.model.document import Document

class ProjectTask(Document):
    pass

# Register in hooks.py
# doc_events = {
#     "Project Task": {
#         "on_update": "my_custom_app.tasks.notify_assignee"
#     }
# }

# my_custom_app/api.py
import frappe
from frappe import _

@frappe.whitelist()
def get_project_summary(project_name):
    """Get project summary information"""
    project = frappe.get_doc("Project", project_name)

    tasks = frappe.get_all("Project Task",
        filters={"project": project_name},
        fields=["task_name", "status", "assigned_to", "deadline"]
    )

    return {
        "project_name": project.project_name,
        "status": project.status,
        "budget": project.budget,
        "tasks": tasks,
        "completion": project.percentage_complete
    }

# Call it via:
# GET /api/method/my_custom_app.api.get_project_summary?project_name=PRJ-001

# Define a purchase approval workflow
workflow = {
    "workflow_name": "Purchase Approval",
    "document_type": "Purchase Order",
    "states": [
        {"state": "Draft", "allow_edit": "Purchase Manager"},
        {"state": "Pending Approval", "allow_edit": "Purchase Manager"},
        {"state": "Approved", "allow_edit": "Director"},
        {"state": "Rejected", "allow_edit": "Director"},
    ],
    "transitions": [
        {"from": "Draft", "to": "Pending Approval", "action": "Submit", "allowed": "Purchase Manager"},
        {"from": "Pending Approval", "to": "Approved", "action": "Approve", "allowed": "Director"},
        {"from": "Pending Approval", "to": "Rejected", "action": "Reject", "allowed": "Director"},
    ]
}

# my_custom_app/reports/sales_summary.py
import frappe

def execute(filters=None):
    columns = [
        {"fieldname": "customer", "label": "Customer", "fieldtype": "Link", "options": "Customer", "width": 200},
        {"fieldname": "total_sales", "label": "Sales Amount", "fieldtype": "Currency", "width": 150},
        {"fieldname": "total_qty", "label": "Quantity", "fieldtype": "Int", "width": 100},
    ]

    conditions = ""
    if filters.get("from_date"):
        conditions += f" AND si.posting_date >= '{filters.from_date}'"
    if filters.get("to_date"):
        conditions += f" AND si.posting_date <= '{filters.to_date}'"

    data = frappe.db.sql(f"""
        SELECT
            si.customer,
            SUM(si.grand_total) as total_sales,
            SUM(si.total_qty) as total_qty
        FROM `tabSales Invoice` si
        WHERE si.docstatus = 1 {conditions}
        GROUP BY si.customer
        ORDER BY total_sales DESC
    """, as_dict=True)

    return columns, data

// Custom form script
frappe.ui.form.on('Sales Order', {
    refresh: function(frm) {
        // Add a custom button
        frm.add_custom_button('Export PDF', function() {
            frappe.call({
                method: 'my_custom_app.api.export_pdf',
                args: { docname: frm.doc.name },
                callback: function(r) {
                    window.open(r.message.url);
                }
            });
        });
    },

    validate: function(frm) {
        // Custom validation
        if (frm.doc.discount > 20) {
            frappe.throw('Discount cannot exceed 20%');
        }
    }
});

# Backup a site
bench --site erp.yourdomain.com backup

# Backup to cloud (includes files)
bench --site erp.yourdomain.com backup --with-files

# Restore from backup
bench --site erp.yourdomain.com restore /path/to/database.sql.gz

# Scheduled backup (add to crontab)
0 2 * * * cd /home/frappe/frappe-bench && bench backup-all-sites

# 1. Enable Redis caching (in site_config.json)
{
    "cache_redis": "redis://localhost:6379"
}

# 2. Database index optimization
# Add indexes for frequently queried fields
frappe.db.add_index("Sales Invoice", ["customer", "posting_date"])

# 3. Enable Gunicorn multi-process
# Set in bench config
bench config set-common-config -c gunicorn_workers 4

# View bench logs
bench --site erp.yourdomain.com logs

# Check MariaDB slow query log
mysql -u root -e "SHOW VARIABLES LIKE 'slow_query_log%';"

# Monitor server resources
htop
iotop

# ERPNext REST API example
import requests

# Get customer list
response = requests.get(
    "https://erp.yourdomain.com/api/resource/Customer",
    headers={"Authorization": "token api_key:api_secret"}
)
customers = response.json()

# Create a sales order
response = requests.post(
    "https://erp.yourdomain.com/api/resource/Sales Order",
    headers={"Authorization": "token api_key:api_secret", "Content-Type": "application/json"},
    json={"customer": "CUST-001", "items": [{"item_code": "ITEM-001", "qty": 10}]}
)