ERPNext 완벽 가이드 2026: 오픈소스 ERP 설치, 설정, 커스텀 개발 실전

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

# 2. Docker Compose 설치(기본 포함되지 않은 경우)
sudo apt install docker-compose-plugin

# 3. 공식 docker-compose 설정 클론
git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker

# 4. 환경 변수 파일 생성
cp example.env .env

# .env 파일 편집 후 주요 파라미터 설정:
# SITE_NAME=erp.yourdomain.com
# DB_ROOT_USER=root
# DB_ROOT_PASSWORD=your_secure_password
# ADMIN_PASSWORD=your_admin_password

# 5. 서비스 시작
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. 새 사이트 생성
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. ERPNext 접속
# 브라우저에서 http://your-server-ip:8080 열기
# 기본 관리자 계정: Administrator
# 비밀번호: .env에서 설정한 ADMIN_PASSWORD

# Let's Encrypt로 무료 SSL 인증서 발급
docker compose -f ~/docker-compose.yml exec backend \
  bench setup nginx

# 또는 Traefik으로 자동 HTTPS 관리
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. 의존성 설치
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. 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. bench 설치(Frappe CLI 도구)
pip3 install frappe-bench

# 4. bench 초기화
bench init --frappe-branch version-15 frappe-bench
cd frappe-bench

# 5. 새 사이트 생성
bench new-site erp.yourdomain.com \
  --db-name erpnext \
  --db-password your_password \
  --admin-password your_admin_password

# 6. ERPNext 애플리케이션 설치
bench get-app --branch version-15 erpnext
bench --site erp.yourdomain.com install-app erpnext

# 7. 개발 서버 시작
bench start
# http://localhost:8000 접속

# Frappe API로 사용자 생성(Python 스크립트)
import frappe

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

# 매출전표 자동 분개
차변: 매출채권         ¥10,000
    대변: 영업수익         ¥8,849.56
        매입세액         ¥1,150.44

# 매입입고 자동 분개
차변: 상품         ¥5,000
    대변: 매입채무         ¥5,000

# Frappe 스크립트로 재고 알림 설정
frappe.db.set_value("Item", "ITEM-001", "re_order_level", 100)
frappe.db.set_value("Item", "ITEM-001", "warehouse", "본사 창고")

# 근태 규칙 설정
attendance_policy = {
    "working_hours": "09:00-18:00",
    "late_entry_threshold": 15,  # 분
    "early_exit_threshold": 15,
    "holiday_list": "2026-공휴일"
}

# 휴가 유형
leave_types = [
    {"name": "연차", "max_leaves": 10},
    {"name": "병가", "max_leaves": 5},
    {"name": "사휴", "max_leaves": 0},  # 승인 필요
    {"name": "혼인휴가", "max_leaves": 3},
]

# 1. 개발용 사이트 생성
bench new-site dev.localhost --force
bench use dev.localhost

# 2. 커스텀 애플리케이션 생성
bench new-app my_custom_app

# 디렉토리 구조:
# my_custom_app/
# ├── my_custom_app/
# │   ├── __init__.py
# │   ├── hooks.py          # 앱 훅 설정
# │   ├── modules.txt        # 모듈 목록
# │   ├── custom_doctype/    # 커스텀 문서 유형
# │   └── api.py             # 커스텀 API
# └── setup.py

# Python 코드로 DocType 정의
import frappe
from frappe.model.document import Document

class ProjectTask(Document):
    pass

# 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):
    """프로젝트 요약 정보 가져오기"""
    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
    }

# 호출 방식:
# GET /api/method/my_custom_app.api.get_project_summary?project_name=PRJ-001

# 구매 승인 워크플로우 정의
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": "고객", "fieldtype": "Link", "options": "Customer", "width": 200},
        {"fieldname": "total_sales", "label": "매출액", "fieldtype": "Currency", "width": 150},
        {"fieldname": "total_qty", "label": "수량", "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

// 커스텀 폼 스크립트
frappe.ui.form.on('Sales Order', {
    refresh: function(frm) {
        // 커스텀 버튼 추가
        frm.add_custom_button('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) {
        // 커스텀 유효성 검사
        if (frm.doc.discount > 20) {
            frappe.throw('할인은 20%를 초과할 수 없습니다');
        }
    }
});

# 사이트 백업
bench --site erp.yourdomain.com backup

# 클라우드 백업
bench --site erp.yourdomain.com backup --with-files

# 백업 복원
bench --site erp.yourdomain.com restore /path/to/database.sql.gz

# 정기 백업(crontab에 추가)
0 2 * * * cd /home/frappe/frappe-bench && bench backup-all-sites

# 1. Redis 캐시 활성화(site_config.json에서)
{
    "cache_redis": "redis://localhost:6379"
}

# 2. 데이터베이스 인덱스 최적화
# 자주 쿼리되는 필드에 인덱스 추가
frappe.db.add_index("Sales Invoice", ["customer", "posting_date"])

# 3. Gunicorn 멀티프로세스 활성화
# bench 설정에서
bench config set-common-config -c gunicorn_workers 4

# bench 로그 확인
bench --site erp.yourdomain.com logs

# MariaDB 슬로우 쿼리 확인
mysql -u root -e "SHOW VARIABLES LIKE 'slow_query_log%';"

# 서버 리소스 모니터링
htop
iotop

# ERPNext REST API 예시
import requests

# 고객 목록 가져오기
response = requests.get(
    "https://erp.yourdomain.com/api/resource/Customer",
    headers={"Authorization": "token api_key:api_secret"}
)
customers = response.json()

# 영업주문 생성
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}]}
)