benchboard-panel 0.3.0

A professional web-based management panel for Frappe/ERPNext bench

BenchBoard Panel

BenchBoard Panel là công cụ quản lý giao diện web chuyên nghiệp dành cho hệ thống Frappe / ERPNext, giúp bạn dễ dàng quản lý Sites, Apps, Logs, và truy cập Terminal ngay trên trình duyệt mà không cần sử dụng command line.

BenchBoard được thiết kế linh hoạt với kiến trúc Python Package giúp cho việc cài đặt và cập nhật trở nên cực kỳ dễ dàng.

---

⚡️ Các tính năng nổi bật

• Quản lý Site: Xem danh sách các site hiện có trên bench, thông tin chi tiết (tên miền, database, port).
• Quản lý App: Liệt kê các ứng dụng (Apps) đã được cài đặt trên từng site cùng với phiên bản.
• Terminal Web: Tích hợp terminal (xterm.js) ngay trên trình duyệt, có khả năng chạy lệnh hệ thống hoặc SSH vào máy chủ nội bộ.
• Quản lý Node (Local/SSH): Có thể quản lý các cụm bench từ xa qua SSH thay vì chỉ máy local.
• Quản lý Backup: Tạo và phục hồi bản sao lưu (database, files) cho các site chỉ bằng 1 click.
• Responsive Design: Thiết kế giao diện hiện đại, tối ưu cho cả máy tính và thiết bị di động.

---

🚀 Hướng dẫn cài đặt

Vì BenchBoard Panel đã được đóng gói thành một Python Package chuẩn, việc cài đặt giờ đây chỉ tốn của bạn vài giây.

Yêu cầu hệ thống

• Hệ điều hành: Linux (Ubuntu, Debian, CentOS, WSL2...)
• Python: 3.10 trở lên.
• Đã cài đặt Frappe Bench (có thư mục frappe-bench).

Cài đặt nhanh

Bước 1: Cài đặt package vào môi trường ảo (virtual environment) của Frappe để có sẵn mọi dependencies:

cd /home/brian/frappe-bench
./env/bin/pip install -e "/home/brian/frappe-bench/bench_board_panel"

(Lưu ý: Lệnh này đang dùng đường dẫn local để test. Sau khi publish lên PyPI, lệnh sẽ đơn giản là pip install benchboard-panel)

Bước 2: Link lệnh bb ra toàn cầu (global) để dễ dàng gõ từ bất cứ đâu:

mkdir -p ~/.local/bin
ln -sf /home/brian/frappe-bench/env/bin/bb ~/.local/bin/bb

Bước 3: Cài đặt dịch vụ chạy ngầm (systemd): Lệnh này sẽ tự động sinh file cấu hình và cài đặt systemd.

bb install

---

🛠 Hướng dẫn sử dụng CLI (bb)

BenchBoard đi kèm với một công cụ CLI chuyên nghiệp viết bằng Python.

Dưới đây là các lệnh cơ bản:

Lệnh	Chức năng
bb start	Khởi động (hoặc khởi động lại) BenchBoard Panel.
bb stop	Dừng BenchBoard Panel.
bb restart	Khởi động lại dịch vụ.
bb status	Xem trạng thái hiện tại (đang chạy/đã dừng) và các URLs để truy cập.
bb logs	Xem logs hệ thống theo thời gian thực (giống tail -f). Bấm Ctrl+C để thoát.
bb enable	Bật tính năng tự động khởi chạy cùng hệ thống (khi máy chủ khởi động).
bb disable	Tắt tính năng khởi chạy cùng hệ thống.
bb --version	Xem phiên bản BenchBoard hiện tại.
bb --help	Hiển thị tất cả các câu lệnh hỗ trợ.

---

🌐 Truy cập Panel

Sau khi chạy lệnh bb start, bạn mở trình duyệt và truy cập:

• Giao diện quản lý (Frontend): http://localhost:8300
• Tài liệu API Backend (Swagger UI): http://localhost:8300/api/docs

Lưu ý về đăng nhập: BenchBoard xác thực bằng chính tài khoản của hệ thống Frappe. Sử dụng tài khoản Administrator hoặc bất kỳ tài khoản nào có quyền System Manager trên Frappe để đăng nhập.

---

🔧 Kiến trúc & Cấu hình nâng cao

BenchBoard Panel bao gồm:

1. Frontend: Xây dựng bằng React, Vite, và TailwindCSS. Khi đóng gói, frontend được build thành file tĩnh (index.html, js, css).
2. Backend: API viết bằng FastAPI, phục vụ cả API endpoints lẫn Frontend tĩnh trên cùng một port (8300).

Tùy chỉnh cấu hình

Nếu bạn muốn đổi port chạy BenchBoard hoặc bench_path, hãy dùng file .env ẩn của hệ thống: File cấu hình được đặt tại: ~/.config/benchboard/config.env

Ví dụ nội dung file:

BENCHBOARD_PORT=9000
BENCHBOARD_BENCH_PATH=/var/www/frappe-bench

Sau khi sửa file, chạy bb restart để áp dụng cấu hình.

---

👨‍💻 Hướng dẫn dành cho Lập trình viên (Developer)

Nếu bạn muốn đóng góp code hoặc tuỳ biến giao diện:

1. Khởi động Backend (Dev mode): Chế độ dev sẽ theo dõi và hot-reload khi bạn sửa code python.

   bb start --dev
   

2. Khởi động Frontend (Dev mode): Để làm việc với giao diện Vite:

   cd frontend
   npm install
   npm run dev
   

   (Lúc này giao diện dev sẽ chạy ở port 5173)