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

chmod +x install_service.sh uninstall_service.sh

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

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:

sudo systemctl restart litert-lm

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

Chỉnh sửa file service:

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

Sửa dòng ExecStart:

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

Sau đó:

sudo systemctl daemon-reload
sudo systemctl restart litert-lm

Cấu hình Port

Chỉnh sửa file service:

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

Sửa dòng ExecStart:

# 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 đó:

sudo systemctl daemon-reload
sudo systemctl restart litert-lm

🎮 Quản lý Service

Xem trạng thái

sudo systemctl status litert-lm

Dừng service

sudo systemctl stop litert-lm

Khởi động service

sudo systemctl start litert-lm

Khởi động lại service

sudo systemctl restart litert-lm

Xem logs realtime

sudo journalctl -u litert-lm -f

Xem logs từ đầu

sudo journalctl -u litert-lm

Xem logs 100 dòng cuối

sudo journalctl -u litert-lm -n 100

Gỡ cài đặt service

sudo bash uninstall_service.sh

📊 Kiểm tra Service

Kiểm tra service đang chạy

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:

curl http://localhost:8000/info

🔧 Cấu hình nâng cao

Chỉnh sửa service file

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

Sau khi chỉnh sửa:

sudo systemctl daemon-reload
sudo systemctl restart litert-lm

Thay đổi user chạy service

Trong file service, sửa dòng:

User=your_username

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

Thêm vào section [Service]:

Environment="VARIABLE_NAME=value"
Environment="ANOTHER_VAR=value"

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

Thêm vào section [Service]:

# 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:

sudo journalctl -u litert-lm -n 50

2. Kiểm tra file service:

sudo systemctl cat litert-lm

3. Kiểm tra syntax:

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:

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 đó:

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:

Restart=always
RestartSec=10

Thay đổi port

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

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

Sửa dòng ExecStart:

ExecStart=/usr/bin/python3 /path/to/server.py --port 8080

Sau đó:

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:

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:

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:

User=litert-lm
Group=litert-lm

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

Thêm vào section [Service]:

# 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:

sudo ufw allow from 127.0.0.1 to any port 8000

Hoặc cho phép từ mạng nội bộ:

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:

# 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

systemctl status litert-lm

Xem chi tiết hơn

sudo systemd-cgtop

Xem tất cả services

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

# 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:

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