Skip to main content
Version: 1.1.0

Hướng Dẫn Phát Triển Custom App với Frappe & erp CLI

Tài liệu này hướng dẫn chi tiết cách tạo, phát triển, quản lý mã nguồn qua Git và triển khai (deploy) custom app cho hệ thống ERPNext sử dụng công cụ hỗ trợ erp CLI.

1. Hướng Dẫn Tạo Custom App​

Khi phát triển các tính năng tùy biến trên nền tảng Frappe/ERPNext, bạn không nên sửa đổi trực tiếp vào core app (frappe hoặc erpnext). Thay vào đó, hãy tạo một Custom App riêng biệt.

Cách tạo bằng erp CLI​

Trong thư mục dự án phát triển local của bạn, chạy lệnh sau:

erp dev create-app <app_name>

Các thông số cần lưu ý khi tạo:​

Khi lệnh khởi chạy, hệ thống sẽ yêu cầu bạn nhập các thông tin cấu trúc cho app qua terminal:

  • App Name (Tên App):
    • Quy chuẩn: Phải sử dụng chữ viết thường (lowercase) và dấu gạch dưới (_) làm dấu phân cách. Ví dụ: custom_hrms, inventory_addon.
    • Tránh: Không viết hoa, không sử dụng dấu gạch ngang (-) hoặc dấu cách vì Python không thể import tên package chứa ký tự đặc biệt này.
  • Branch Name (Tên Nhánh Git):
    • ⚠️ Bắt buộc: Phải điền tên nhánh rõ ràng (Ví dụ: main hoặc develop).
    • Lưu ý: Với Frappe v16 mới, nếu bạn bỏ trống giá trị này và nhấn Enter, lệnh khởi tạo git của Python sẽ chạy git init --initial-branch=, dẫn đến lỗi cú pháp Git (Exit code 128) khiến quá trình tạo app thất bại.
  • App Publisher & Email: Điền thông tin nhà phát triển để định danh ứng dụng.
  • App License: Giấy phép mã nguồn mở (mặc định là mit).
  • Create GitHub Workflow: Chọn N nếu bạn chưa cần cấu hình tự động test (CI) qua GitHub Actions.

2. Cấu Trúc Thư Mục Custom App Chuẩn​

Sau khi tạo thành công, mã nguồn của app sẽ nằm tại thư mục ./apps/<app_name>/ trên máy host. Cấu trúc chuẩn bao gồm:

apps/<app_name>/
├── pyproject.toml         # Khai báo metadata và thư viện phụ thuộc Python (V15+)
├── setup.py               # Script cài đặt package Python (Backward compatibility)
├── README.md              # Tài liệu giới thiệu app
├── license.txt            # Thông tin bản quyền
└── <app_name>/            # Package nguồn chính của Python
    ├── __init__.py
    ├── hooks.py           # File QUAN TRỌNG: Nơi đăng ký các sự kiện, ghi đè DocType
    ├── patches.txt        # Danh sách các bản cập nhật database dạng script
    ├── public/            # Chứa các file tĩnh frontend (CSS, JS, hình ảnh)
    ├── templates/         # Chứa các file HTML templates (cho Web view)
    ├── www/               # Chứa các trang web tĩnh/động định tuyến trực tiếp
    └── config/            # Chứa cấu hình menu, phân quyền của app

Các file cần lưu ý khi phát triển:​

  1. hooks.py: Nơi bạn cấu hình hook sự kiện (Ví dụ: chạy hàm Python khi Lưu/Hủy một hóa đơn), ghi đè lớp Python (override_doctype_class), hoặc nhúng các file JS/CSS tùy biến vào giao diệnDesk.
  2. pyproject.toml: Nếu custom app của bạn cần cài thêm thư viện Python ngoài (ví dụ: requests, numpy), hãy khai báo trong file này dưới mục dependencies.

3. Tích Hợp Git & Quản Lý Mã Nguồn​

Lệnh erp dev create-app đã tự động khởi tạo một Git repository riêng độc lập cho custom app của bạn tại thư mục apps/<app_name>.

Quy trình quản lý mã nguồn qua Git:​

  1. Di chuyển vào thư mục custom app: 
    cd apps/<app_name>
  2. Liên kết với Repository từ xa (GitHub/GitLab/Bitbucket): Tạo một kho chứa trống trên GitHub, sau đó chạy lệnh: 
    git remote add origin https://github.com/username/your-custom-app-repo.git
    git branch -M main
  3. Tạo commit đầu tiên và push lên: 
    git add .
    git commit -m "feat: initial boilerplate by erp cli"
    git push -u origin main
  4. Lập trình và Commit: Mỗi khi phát triển xong một tính năng, bạn tiến hành commit bình thường tại thư mục của custom app đó. Thư mục cha (dự án ERP local chính) đã được cấu hình .gitignore để bỏ qua thư mục apps/ nhằm tránh xung đột Git lồng nhau.

4. Triển Khai (Deploy) Custom App lên Production/Staging​

Có 3 cách để deploy custom app của bạn lên các server chạy Docker thông qua hỗ trợ của erp CLI:

Cách 1: Cài đặt động tại runtime (Khuyên Dùng - Tiện Lợi Nhất)​

Nếu môi trường Production/Staging đang chạy bình thường, bạn có thể cài đặt trực tiếp custom app từ Git repository lên server bằng lệnh:

erp app install <app_name> https://github.com/username/your-custom-app-repo.git

Cơ chế hoạt động của CLI:

  1. Tự động kết nối vào container backend.
  2. Chạy bench get-app --resolve-deps <app_name> <git_url> để tải mã nguồn về volume.
  3. Cài đặt app vào database của site bằng bench install-app <app_name>.
  4. Biên dịch các asset frontend qua bench build --app <app_name>.
  5. Cập nhật cấu hình dự án erp-config.yaml và tự động khởi động lại (restart) các container backend/websocket/worker để áp dụng mã nguồn mới.

Cách 2: Khai báo qua tệp cấu hình erp-config.yaml​

Bạn có thể cấu hình danh sách app cần cài đặt trực tiếp trong file cấu hình dự án trước khi chạy lệnh khởi dựng:

# erp-config.yaml
apps:
  - name: erpnext
  - name: custom_app
    repo: https://github.com/workdone-vn/erpmanager.git # hoặc dạng SSH: git@github.com:workdone-vn/erpmanager.git

Khi bạn chạy lệnh erp run, CLI sẽ tự động tải và cài đặt toàn bộ các app được liệt kê trong danh sách này vào site.

[!TIP] Quản lý Quyền Truy Cập Repository Riêng Tư (Private Repo): Nếu các custom app của bạn nằm trong các repository riêng tư (ví dụ như các repo thuộc tổ chức workdone-vn), bạn có thể sử dụng 1 trong 2 cơ chế sau để CLI hỗ trợ clone tự động:

  1. Sử dụng GitHub Personal Access Token (PAT): Chạy lệnh cấu hình token trên máy host:

    erp github login --token <token>

    CLI sẽ tự động mã hóa và lưu trữ token cục bộ. Khi chạy erp run hoặc erp app install, CLI sẽ tự động chèn token động dưới dạng HTTPS OAuth2 (https://oauth2:<token>@github.com/...) cho các URL clone.

  2. Sử dụng Khóa SSH của máy host (Khuyên dùng khi sử dụng giao thức SSH): Nếu máy của bạn đã thiết lập khóa SSH để làm việc với Git, bạn hãy import đường dẫn khóa SSH trên máy host (mặc định là thư mục .ssh):

    erp ssh-key import --path ~/.ssh

    CLI sẽ lưu đường dẫn này và tự động copy thư mục/tệp SSH của host vào container backend bằng lệnh docker compose cp đồng thời thiết lập phân quyền an toàn (chmod 700/600 và chown) khi khởi dựng container stack hoặc cài app. Nhờ đó, container backend có thể clone trực tiếp qua giao thức Git SSH (git@github.com:...) sử dụng SSH key và known_hosts của bạn mà không cần cấu hình thêm token, đồng thời tệp compose.yml vẫn độc lập và di động.

Cách 3: Đóng gói sẵn vào Production Docker Image (Bake-in Image)​

Với các hệ thống yêu cầu bảo mật cao hoặc chạy trên Kubernetes/Docker Swarm cần khởi động nhanh (auto-scaling):

  1. Mở file Dockerfile được sinh ra trong dự án của bạn.
  2. Tìm tới khu vực builder stage (sau phần bench get-app ... erpnext), thêm dòng lệnh tải app của bạn: 
    RUN bench get-app --branch main --resolve-deps custom_app https://github.com/username/your-custom-app-repo.git
  3. Build lại Docker image của riêng bạn và đẩy lên Docker Registry: 
    docker build -t your-registry.com/erp-custom:latest .
    docker push your-registry.com/erp-custom:latest
  4. Cập nhật tên image trong file erp-config.yaml và chạy erp run.