Skip to main content
Version: 1.0.2

Hướng Dẫn Sử Dụng sPhoton ERP CLI (erp)

Công cụ dòng lệnh sPhoton ERP CLI (erp) giúp tự động hóa hoàn toàn việc khởi tạo, cấu hình, quản lý và vận hành các môi trường phát triển (development) cũng như kiểm thử/vận hành (staging/production) cho hệ thống ERPNext/Frappe sử dụng Docker Compose.

1. Các lệnh CLI và Cờ (Flags)​

Dưới đây là tổng hợp đầy đủ các lệnh, cờ tương ứng, cách dùng và ngữ cảnh sử dụng thực tế.

1.1. Xem thông tin phiên bản (version)​

  • Cú pháp: 
    go run cli/main.go version
    # Hoặc qua tệp nhị phân đã build
    erp version
    erp -v
    erp --version
  • Khi nào dùng: Cần kiểm tra thông tin liên hệ của maintainer, slogan thương hiệu, website chính thức hoặc kiểm tra phiên bản CLI hiện tại.

1.2. Khởi tạo dự án mới (new)​

  • Cú pháp: 
    erp new <project_dir> [flags]
  • Các cờ (Flags):
    • --run: Tự động khởi chạy provisioning dựng môi trường ngay sau khi tạo cấu hình thành công.
    • --local: Chỉ định môi trường phát triển cục bộ (local).
    • --staging: Chỉ định môi trường kiểm thử (staging).
    • --production: Chỉ định môi trường vận hành thực tế (production).
    • --name <company_name>: Thiết lập tên công ty / dự án (Mặc định: ERPNext).
    • --port <host_port>: Thiết lập cổng dịch vụ trên máy host (Mặc định: 8123).
    • --domain <domain>: Thiết lập tên miền site (Mặc định: localhost:<port>).
    • --admin-password <password>: Thiết lập mật khẩu cho tài khoản Administrator.
    • --apps <apps>: Danh sách các ứng dụng cài đặt kèm, phân cách bằng dấu phẩy (ví dụ: hrms,payments).
  • Chế độ tự động hoàn toàn (Non-interactive / Agent-friendly): Nếu bạn truyền đủ 3 thông số bắt buộc: Môi trường (một trong các cờ --local/--staging/--production), Tên công ty (--name), và Cổng (--port), CLI sẽ bỏ qua giao diện tương tác TUI hoàn toàn và trực tiếp tạo cấu hình. Ví dụ lệnh chạy nhanh: 
    go run cli/main.go new dev_project --run --local --name ERPNext --port 2345 --domain localhost:2345 --admin-password admin
  • Giao diện Wizard tương tác (TUI): Nếu thiếu bất kỳ tham số bắt buộc nào, CLI sẽ tự động kích hoạt TUI Wizard tương ứng để hỏi thông tin còn thiếu. Bạn có thể dùng phím Tab/Enter để chuyển bước, Shift+Tab để quay lại và Space để chọn app.

1.3. Khởi dựng và chạy môi trường (run)​

  • Cú pháp: 
    erp run [flags]
  • Các cờ (Flags):
    • --dry-run: Chỉ in ra màn hình các lệnh docker và bench sẽ được chạy mà không thực sự thực thi chúng.
  • Cách thức hoạt động:
    1. Tự động viết tệp compose.yml và ghi các tài nguyên Docker (Dockerfile, scripts entrypoint) vào thư mục dự án.
    2. Khởi động các Docker container ở chế độ chạy ngầm (docker compose up -d).
    3. Tự động vá lỗi setup_wizard.js của Frappe core trên host để Setup Wizard nhận diện tiếng Việt mặc định.
    4. Chờ MariaDB container sẵn sàng, sau đó chạy bench new-site để tạo site mới.
    5. Cài đặt erpnext và các ứng dụng bổ sung được định nghĩa trong cấu hình.
    6. Đặt các thông số hệ thống tiếng Việt mặc định (vi, Vietnam, Asia/Ho_Chi_Minh, VND, định dạng ngày dd-mm-yyyy, ngày đầu tuần thứ Hai Monday).
    7. Khởi động lại các container ứng dụng để tải mã nguồn mới nhất.
  • Khi nào dùng: Chạy lệnh này ngay tại thư mục dự án khi bắt đầu khởi động hoặc dựng mới môi trường dự án.

1.4. Dừng dự án (stop)​

  • Cú pháp: 
    erp stop
  • Mô tả: Tắt tất cả các containers đang chạy ngầm của dự án hiện tại bằng lệnh docker compose down.
  • Khi nào dùng: Khi kết thúc ngày làm việc hoặc muốn tạm dừng dự án để giải phóng tài nguyên CPU/RAM trên máy tính.

1.5. Kiểm tra đồng bộ (verify)​

  • Cú pháp: 
    erp verify [project_dir]
  • Mô tả: Quét cấu hình erp-config.yaml và đối chiếu với file chạy thực tế compose.yml để kiểm tra sự trùng khớp về cổng ánh xạ Nginx, các biến môi trường cài đặt app của backend.
  • Khi nào dùng: Sử dụng trước khi deploy hoặc khi cần kiểm tra xem tệp compose chạy thực tế có đồng bộ với file cấu hình cấu hình dự án hay không.

1.6. Trình quản lý HUD Dashboard (dashboard)​

  • Cú pháp: 
    erp dashboard
  • Mô tả: Giao diện HUD quản trị tập trung (TUI Bubbletea) hiển thị danh sách các dự án đang tồn tại trên hệ thống. Ở phiên bản v1.0.2, giao diện được nâng cấp thành cấu trúc hai cột ngang:
    • Cột bên trái: Danh sách các dự án hiện có và trạng thái chạy/dừng thời gian thực.
    • Cột bên phải: Sidebar hiển thị logo nghệ thuật ASCII sPhoton, siêu dữ liệu dự án (Maintainer, Copyright, Slogan, Phiên bản) và hộp "Quick Help" trợ giúp phím tắt thông minh.
  • Các phím điều khiển nhanh:
    • s: Bật dự án được chọn (docker compose up -d ngầm).
    • x: Tắt dự án được chọn (docker compose down).
    • r: Khởi động lại dự án (docker compose restart).
    • d: Gỡ bỏ đăng ký (Unregister) dự án khỏi Dashboard (không xóa file trên đĩa cứng).
    • q hoặc Ctrl+C: Thoát dashboard.
  • Khi nào dùng: Khi có nhiều dự án chạy song song và muốn có một giao diện chung trực quan để bật, tắt và giám sát nhanh trạng thái của chúng.

1.7. Quản lý ứng dụng (app)​

Quản lý các ứng dụng Frappe động cho site của dự án hiện tại:

  • Cài đặt ứng dụng: 
    erp app install <app_name_or_url> [repo_url] [--force]
    Ví dụ: erp app install hrms hoặc erp app install wiki https://github.com/frappe/wiki.git
  • Gỡ cài đặt ứng dụng: 
    erp app uninstall <app_name> [--force]
  • Cập nhật ứng dụng: 
    erp app update <app_name>

1.8. Sao lưu và Khôi phục (backup & restore)​

  • Sao lưu cơ sở dữ liệu và files: 
    erp backup
    Mô tả: Tạo bản sao lưu nén .sql.gz lưu bên trong thư mục sites/ của dự án.
  • Khôi phục cơ sở dữ liệu: 
    erp restore <backup_file_path>
    Mô tả: Khôi phục cơ sở dữ liệu của site từ tệp sao lưu. CLI tự động xử lý việc sao chép tệp tạm vào volume container nếu tệp nằm ngoài vùng mount của docker.

1.9. Quản lý dịch thuật đa ngôn ngữ (export:lang & import:lang)​

  • Xuất dịch thuật ra file CSV: 
    erp export:lang <language_code> -f <csv_path>
    Ví dụ: erp export:lang vi -f translation_vi.csv
  • Nhập dịch thuật từ file CSV: 
    erp import:lang <language_code> -f <csv_path>
    Mô tả: Cập nhật bản dịch từ tệp CSV vào các tệp .po của các ứng dụng, tự động chạy biên dịch .mo và xoá cache Desk để cập nhật ngay từ dịch mới lên giao diện.

1.10. Đổi mật khẩu Administrator (reset-password)​

  • Cú pháp: 
    erp reset-password [new_password]
  • Mô tả: Thay đổi mật khẩu tài khoản Administrator của site và ghi nhận lại mật khẩu mới này vào tệp cấu hình dự án. Nếu không truyền mật khẩu mới, CLI sẽ tự động sinh mật khẩu ngẫu nhiên an toàn dài 16 ký tự.

1.11. Cấu hình GitHub Token (github login)​

  • Cú pháp: 
    erp github login --token <token>
  • Các cờ (Flags):
    • --token: Mã Personal Access Token (PAT) của GitHub có quyền đọc/pull các repository private của tổ chức.
  • Khi nào dùng: Khi cấu hình các ứng dụng tùy chỉnh (custom apps) trong tệp erp-config.yaml sử dụng địa chỉ SSH (git@github.com:workdone-vn/...) hoặc HTTPS (https://github.com/workdone-vn/...), CLI sẽ tự động chèn Token đã cấu hình này để chuyển URL thành định dạng truy cập qua HTTPS OAuth2 (https://oauth2:<token>@github.com/...) lúc clone app.
  • Cơ chế hoạt động:
    1. Xác thực token: CLI sẽ tự động dùng lệnh git ls-remote để kiểm tra trực tiếp xem token được cung cấp có hợp lệ và có quyền truy cập (đọc/pull) repository của tổ chức (workdone-vn/erpmanager.git) hay không. Nếu không, CLI sẽ trả về lỗi và không lưu token.
    2. Mã hóa bảo mật: Token sau khi xác thực thành công sẽ được mã hóa đối xứng (sử dụng khóa được tạo từ định danh thiết bị và người dùng hệ điều hành để đảm bảo token không bị lưu dưới dạng văn bản thuần - clear text) và lưu tại tệp cấu hình an toàn trên máy người dùng (~/.erp_github_token).

1.12. Cấu hình SSH Key (ssh-key import)​

  • Cú pháp: 
    erp ssh-key import [flags]
  • Các cờ (Flags):
    • --path <path>: Đường dẫn tới tệp SSH Key riêng tư (ví dụ: ~/.ssh/id_rsa) hoặc thư mục chứa các SSH key (ví dụ: ~/.ssh). Mặc định là thư mục .ssh của người dùng (~/.ssh).
  • Khi nào dùng: Khi bạn muốn sử dụng khóa SSH có sẵn trên máy host để clone/triển khai các custom app qua giao thức SSH (ví dụ: git@github.com:...) thay vì cấu hình GitHub Personal Access Token (PAT).
  • Cơ chế hoạt động:
    1. Lưu cấu hình: CLI kiểm tra sự tồn tại của tệp/thư mục SSH Key trên máy host và lưu đường dẫn tuyệt đối vào tệp cấu hình toàn cục ~/.erp_ssh_key_path.
    2. Copy vào container: Khi khởi chạy erp run hoặc erp app install, CLI tự động copy thư mục hoặc tệp SSH Key từ máy host vào thư mục home của user trong container backend (/home/frappe/.ssh) thông qua lệnh docker compose cp.
    3. Cấu hình quyền bảo mật: CLI tự động chạy script cấu hình quyền sở hữu (chown -R frappe:frappe) và quyền truy cập (chmod 700 cho thư mục .ssh, chmod 600 cho các file bên trong) ở container backend.
    4. Tác dụng: Giúp container backend tự động sử dụng SSH Credentials và danh sách known_hosts được copy từ máy host để clone code trực tiếp qua Git SSH mà không cần phải can thiệp thủ công, đồng thời giữ cho tệp compose.yml hoàn toàn độc lập và di động (không phụ thuộc vào đường dẫn tuyệt đối của host).

1.13. Chạy lệnh trực tiếp trong Container (exec)​

  • Cú pháp: 
    erp exec <command>
  • Mô tả: Chạy các câu lệnh tùy ý trực tiếp bên trong Docker container của dịch vụ backend đang hoạt động. Lệnh này sẽ tự động xác thực sự tồn tại của tệp cấu hình erp-config.yaml và kiểm tra sự sẵn sàng của lệnh docker trong môi trường hệ thống.
  • Ví dụ: 
    # Truy cập bash shell bên trong container backend
    erp exec bash
    # Chạy bench console trực tiếp
    erp exec "bench --site erp.localhost console"
    # Kiểm tra phiên bản Python trong container
    erp exec "python --version"
  • Khi nào dùng: Khi nhà phát triển hoặc quản trị viên cần thực thi nhanh một lệnh tùy biến bên trong container của dự án hiện hành mà không muốn gõ dòng lệnh docker dài dòng.

2. Hướng dẫn phát triển Custom App (Local Development)​

Khi làm việc ở môi trường phát triển cục bộ (local), thư mục ./apps trên máy host sẽ được mount trực tiếp vào container. Bạn có thể áp dụng quy trình phát triển và kiểm thử sau:

2.1. Khởi tạo Custom App mới​

Chạy lệnh tại thư mục dự án:

erp dev create-app <app_name>

2.2. Cơ chế tự động nạp lại (Auto-reload)​

  • Frontend (JS/CSS/Assets): Chạy watcher để tự động phát hiện và biên dịch lại assets frontend khi bạn lưu file thay đổi ở host: 
    erp dev watch
  • Backend (Python API & Controllers): Ở chế độ ENVIRONMENT=development, Gunicorn chạy trong container backend được bật cờ --reload. Mỗi khi bạn chỉnh sửa và lưu file .py ở host, Gunicorn tự động tải lại code Python mới ngay lập tức, bạn không cần chạy lệnh restart thủ công.

2.3. Khi nào cần chạy lệnh Reload thủ công (erp dev reload)?​

Các tiến trình chạy nền như Background Workers (bench worker) và Scheduler (bench schedule) không sử dụng Gunicorn nên không có tính năng tự động reload. Bạn cần chạy lệnh reload thủ công khi:

  1. Thay đổi logic của các tác vụ chạy nền (background tasks / jobs).
  2. Thay đổi cấu hình hệ thống trong file hooks.py (chỉ được load lại khi khởi động hoặc clear cache cụ thể). Lệnh chạy:
erp dev reload

Lệnh này sẽ xoá cache và khởi động lại nhanh các container backend và workers để load code mới.

2.4. Mở Interactive Console​

Truy cập nhanh Python interactive console của Frappe trực tiếp trong container để test code, chạy thử lệnh ORM hoặc kiểm tra database:

erp dev console