litert-lm-orangepi/SERVICE_README.md

# LiteRT-LM Linux Systemd Service

Hướng dẫn cài đặt và sử dụng LiteRT-LM server như một systemd service trên Linux.

## 📋 Yêu cầu

- Linux với systemd (Ubuntu, Debian, Fedora, CentOS, etc.)
- Python 3 đã cài đặt
- Quyền sudo

## 🚀 Cài đặt Service

### Bước 1: Cho phép thực thi script

```bash
chmod +x install_service.sh uninstall_service.sh
```

### Bước 2: Chạy script cài đặt

```bash
sudo bash install_service.sh
```

Script sẽ hỏi cấu hình:
- **Port**: Port để chạy server (mặc định 8000)
- **Model path**: Đường dẫn model cụ thể (hoặc Enter để chọn từ menu)

Sau đó script sẽ:
1. Tạo file config model mặc định (nếu cần)
2. Tạo systemd service file với cấu hình đã chọn
3. Enable service để tự động khởi động khi boot
4. Khởi động service ngay lập tức

## ⚙️ Cấu hình

### Cấu hình Model

**Cách 1: Chọn từ menu (mặc định)**

Chỉnh sửa file `service_config.txt` để chọn model:

```
1  → Gemma 4 Edge 2B (nhanh hơn)
2  → Gemma 4 Edge 4B (thông minh hơn)
3  → Nhập đường dẫn tùy chỉnh
```

Sau khi thay đổi, restart service:

```bash
sudo systemctl restart litert-lm
```

**Cách 2: Chỉ định model cụ thể**

Chỉnh sửa file service:

```bash
sudo nano /etc/systemd/system/litert-lm.service
```

Sửa dòng `ExecStart`:

```ini
ExecStart=/usr/bin/python3 /path/to/server.py --model /path/to/model.litertlm
```

Sau đó:

```bash
sudo systemctl daemon-reload
sudo systemctl restart litert-lm
```

### Cấu hình Port

Chỉnh sửa file service:

```bash
sudo nano /etc/systemd/system/litert-lm.service
```

Sửa dòng `ExecStart`:

```ini
# Chỉ port
ExecStart=/usr/bin/python3 /path/to/server.py --port 8080

# Hoặc kết hợp với model
ExecStart=/usr/bin/python3 /path/to/server.py --port 8080 --model /path/to/model.litertlm
```

Sau đó:

```bash
sudo systemctl daemon-reload
sudo systemctl restart litert-lm
```

## 🎮 Quản lý Service

### Xem trạng thái
```bash
sudo systemctl status litert-lm
```

### Dừng service
```bash
sudo systemctl stop litert-lm
```

### Khởi động service
```bash
sudo systemctl start litert-lm
```

### Khởi động lại service
```bash
sudo systemctl restart litert-lm
```

### Xem logs realtime
```bash
sudo journalctl -u litert-lm -f
```

### Xem logs từ đầu
```bash
sudo journalctl -u litert-lm
```

### Xem logs 100 dòng cuối
```bash
sudo journalctl -u litert-lm -n 100
```

### Gỡ cài đặt service
```bash
sudo bash uninstall_service.sh
```

## 📊 Kiểm tra Service

### Kiểm tra service đang chạy

```bash
sudo systemctl is-active litert-lm
```

### Kiểm tra server hoạt động

Mở trình duyệt: http://localhost:8000 (hoặc port đã cấu hình)

Hoặc test API:
```bash
curl http://localhost:8000/info
```

## 🔧 Cấu hình nâng cao

### Chỉnh sửa service file

```bash
sudo nano /etc/systemd/system/litert-lm.service
```

Sau khi chỉnh sửa:
```bash
sudo systemctl daemon-reload
sudo systemctl restart litert-lm
```

### Thay đổi user chạy service

Trong file service, sửa dòng:
```ini
User=your_username
```

### Thêm biến môi trường

Thêm vào section `[Service]`:
```ini
Environment="VARIABLE_NAME=value"
Environment="ANOTHER_VAR=value"
```

### Giới hạn tài nguyên

Thêm vào section `[Service]`:
```ini
# Giới hạn memory (ví dụ: 2GB)
MemoryLimit=2G

# Giới hạn CPU (ví dụ: 50%)
CPUQuota=50%
```

## 🔍 Troubleshooting

### Service không khởi động

1. Kiểm tra logs:
```bash
sudo journalctl -u litert-lm -n 50
```

2. Kiểm tra file service:
```bash
sudo systemctl cat litert-lm
```

3. Kiểm tra syntax:
```bash
sudo systemd-analyze verify /etc/systemd/system/litert-lm.service
```

### Thay đổi đường dẫn hoặc cấu hình

Chỉnh sửa file service:

```bash
sudo nano /etc/systemd/system/litert-lm.service
```

Sửa các dòng:
- `WorkingDirectory=` - Đường dẫn thư mục project
- `ExecStart=` - Lệnh khởi động với tham số
- `StandardInput=` - Đường dẫn file config

Sau đó:
```bash
sudo systemctl daemon-reload
sudo systemctl restart litert-lm
```

### Service bị crash

Service sẽ tự động restart sau 10 giây nhờ cấu hình:
```ini
Restart=always
RestartSec=10
```

### Thay đổi port

Sử dụng tham số `--port`:

```bash
sudo nano /etc/systemd/system/litert-lm.service
```

Sửa dòng `ExecStart`:
```ini
ExecStart=/usr/bin/python3 /path/to/server.py --port 8080
```

Sau đó:
```bash
sudo systemctl daemon-reload
sudo systemctl restart litert-lm
```

### Permission denied

Đảm bảo user trong service file có quyền đọc/ghi thư mục:
```bash
sudo chown -R your_username:your_username /path/to/litert-lm-orangepi
```

## 🔐 Bảo mật

### Chạy service với user riêng

Tạo user chuyên dụng:
```bash
sudo useradd -r -s /bin/false litert-lm
sudo chown -R litert-lm:litert-lm /path/to/litert-lm-orangepi
```

Sửa trong service file:
```ini
User=litert-lm
Group=litert-lm
```

### Giới hạn quyền truy cập

Thêm vào section `[Service]`:
```ini
# Chỉ đọc /usr, /boot, /etc
ProtectSystem=full

# Không cho ghi vào /home
ProtectHome=true

# Không cho truy cập /dev
PrivateDevices=true
```

### Firewall

Chỉ cho phép truy cập local:
```bash
sudo ufw allow from 127.0.0.1 to any port 8000
```

Hoặc cho phép từ mạng nội bộ:
```bash
sudo ufw allow from 192.168.1.0/24 to any port 8000
```

## 📦 Cấu trúc Files

```
litert-lm-orangepi/
├── server.py                    # Server chính (hỗ trợ --port và --model)
├── install_service.sh          # Script cài đặt service
├── uninstall_service.sh        # Script gỡ cài đặt service
├── litert-lm.service           # Template systemd service
├── service_config.txt          # Config model (1/2/3) - dùng khi không chỉ định --model
├── SERVICE_README.md           # File này
└── models/                     # Thư mục chứa models
    ├── gemma-4-E2B-it.litertlm
    └── gemma-4-E4B-it.litertlm
```

## 🎯 Auto-start khi khởi động

Service đã được cấu hình để tự động khởi động:

```bash
# Kiểm tra
sudo systemctl is-enabled litert-lm

# Tắt auto-start
sudo systemctl disable litert-lm

# Bật auto-start
sudo systemctl enable litert-lm
```

## 📊 Monitoring

### Xem resource usage

```bash
systemctl status litert-lm
```

### Xem chi tiết hơn

```bash
sudo systemd-cgtop
```

### Xem tất cả services

```bash
systemctl list-units --type=service
```

## ✅ Checklist sau khi cài đặt

- [ ] Service đã được cài đặt: `systemctl list-units | grep litert-lm`
- [ ] Service đang chạy: `systemctl is-active litert-lm`
- [ ] Có thể truy cập http://localhost:8000 (hoặc port đã cấu hình)
- [ ] API `/info` trả về thông tin model
- [ ] Service tự động khởi động: `systemctl is-enabled litert-lm`
- [ ] Logs hiển thị bình thường: `journalctl -u litert-lm -n 20`

## 🆘 Các lệnh hữu ích

```bash
# Xem toàn bộ config của service
sudo systemctl show litert-lm

# Xem dependencies
systemctl list-dependencies litert-lm

# Xem thời gian khởi động
systemd-analyze blame

# Test service file syntax
sudo systemd-analyze verify /etc/systemd/system/litert-lm.service

# Xem logs từ boot cuối cùng
sudo journalctl -u litert-lm -b

# Xem logs trong khoảng thời gian
sudo journalctl -u litert-lm --since "1 hour ago"
sudo journalctl -u litert-lm --since "2024-01-01" --until "2024-01-02"

# Export logs ra file
sudo journalctl -u litert-lm > litert-lm.log
```

## 🔄 Update service

Khi có thay đổi code trong `server.py`:

```bash
sudo systemctl restart litert-lm
```

Không cần cài đặt lại service.

## 📝 Ghi chú

- Service sử dụng `StandardInput=file:` để tự động truyền model choice từ `service_config.txt` (nếu không dùng `--model`)
- Logs được quản lý bởi systemd journal (journalctl)
- Service tự động restart nếu bị crash
- Có thể chạy nhiều instance với port khác nhau bằng cách tạo nhiều service file
- Tham số `--port` và `--model` cho phép linh hoạt cấu hình mà không cần chỉnh sửa code