Metadata-Version: 2.4
Name: benchboard-panel
Version: 0.3.2
Summary: A professional web-based management panel for Frappe/ERPNext bench
License: MIT
Project-URL: Homepage, https://github.com/brian-vo/benchboard-panel
Project-URL: Repository, https://github.com/brian-vo/benchboard-panel
Project-URL: Bug Tracker, https://github.com/brian-vo/benchboard-panel/issues
Keywords: frappe,erpnext,bench,management,panel,dashboard
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn[standard]>=0.20
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: paramiko>=3.0
Requires-Dist: cryptography>=41.0
Requires-Dist: pydantic>=2.0
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.1
Requires-Dist: python-multipart>=0.0.6
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# 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 từ PyPI vào môi trường ảo (virtual environment) của Frappe để có sẵn mọi dependencies:

```bash
cd /home/<username>/frappe-bench
./env/bin/pip install benchboard-panel --no-cache-dir
```
*(Hãy thay `/home/<username>/frappe-bench` bằng đường dẫn thực tế đến thư mục frappe-bench trên máy của bạn).*

**Bước 2:** Liên kết (link) lệnh `bb` ra toàn cầu (global) để dễ dàng gọi lệnh từ bất cứ thư mục nào:
```bash
mkdir -p ~/.local/bin
ln -sf /home/<username>/frappe-bench/env/bin/bb ~/.local/bin/bb
```
*(Đảm bảo thư mục `~/.local/bin` đã có trong biến môi trường `$PATH` của bạn, thông thường Ubuntu đã cấu hình sẵn điều này).*

**Bước 3:** Cài đặt dịch vụ chạy ngầm (`systemd`):
Lệnh này cần quyền admin (`sudo`) để tạo cấu hình khởi chạy ngầm trong hệ thống:
```bash
sudo ~/.local/bin/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:
```env
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.
   ```bash
   bb start --dev
   ```

2. **Khởi động Frontend (Dev mode):**
   Để làm việc với giao diện Vite:
   ```bash
   cd frontend
   npm install
   npm run dev
   ```
   (Lúc này giao diện dev sẽ chạy ở port `5173`)
