Thiết lập

Cài đặt

Hướng dẫn dựng môi trường phát triển trên máy của bạn: ứng dụng chạy bằng npm run dev, PostgreSQL và MinIO chạy trong Docker, LLM chạy bằng Ollama cài trên máy.

Yêu cầu

Cài sẵn các thành phần sau trên máy.

Node.js 20 trở lênMôi trường chạy JavaScript

Bắt buộc

Docker Desktop hoặc Docker Engine + Compose v2Chạy PostgreSQL 16 và MinIO

Bắt buộc

GitQuản lý mã nguồn

Bắt buộc

OllamaChạy LLM trên máy cho trợ lý AI; không cần nếu bạn dùng OpenAI

Không bắt buộc

GPU NVIDIA từ 8 GB VRAMKhuyến nghị cho model 7–8B; không có GPU vẫn chạy được nhưng chậm

Không bắt buộc

Cài đặt trên máy

1. Cài dependency

npm ci

Cài đúng các phiên bản ghi trong package-lock.json.

2. Cấu hình môi trường

cp .env.example .env
# rồi đặt AUTH_SECRET bằng giá trị từ: npx auth secret

Đặt AUTH_SECRET bằng giá trị sinh từ npx auth secret. Các giá trị còn lại trong .env.example đã khớp với Docker Compose và Ollama.

3. Khởi động PostgreSQL và MinIO

docker compose up -d
docker compose ps -a   # chờ postgres, minio = healthy; minio-init = Exited (0)

Chờ tới khi postgres và minio ở trạng thái healthy, còn minio-init kết thúc với Exited (0), nghĩa là đã tạo bucket lưu file.

4. Tạo schema và dữ liệu mẫu

npm run db:deploy   # áp dụng migration
npm run db:seed     # tạo dữ liệu mẫu

db:deploy áp dụng các migration trong prisma/migrations. db:seed tạo khoa, khóa học, lớp học và tài khoản dùng thử; chạy lại nhiều lần không bị trùng dữ liệu.

5. Tải model AI

ollama pull qwen2.5:7b-instruct
ollama list   # kiểm tra model đã có

Bỏ qua bước này nếu bạn dùng OpenAI (xem trang Tính năng AI).

6. Chạy ứng dụng

npm run dev

Mở http://localhost:3000 và đăng nhập bằng một tài khoản dùng thử.

Biến môi trường

Khai báo trong file .env. Giá trị mặc định cho dev có sẵn trong .env.example.

Biến	Mô tả	Bắt buộc
DATABASE_URL	Chuỗi kết nối PostgreSQL	Bắt buộc
AUTH_SECRET	Khóa ký JWT của phiên đăng nhập	Bắt buộc
S3_ENDPOINT S3_BUCKET S3_ACCESS_KEY_ID S3_SECRET_ACCESS_KEY	Kết nối kho lưu file S3 (dev dùng MinIO trong Docker)	Bắt buộc
AUTH_URL	URL công khai của ứng dụng; cần khi chạy sau proxy hoặc khác cổng 3000	Không bắt buộc
OPENAI_BASE_URL OPENAI_API_KEY OPENAI_MODEL	Endpoint, khóa và model của LLM tương thích OpenAI; mặc định trỏ tới Ollama trên máy. Thiếu khóa thì trợ lý AI báo lỗi	Không bắt buộc
DEMO_MODE	true: hiện thẻ đăng nhập nhanh bằng tài khoản dùng thử; production phải tắt	Không bắt buộc
ALLOW_SELF_REGISTER	Mặc định false: tắt tự đăng ký, /register trả 404	Không bắt buộc
AUTH_GOOGLE_ID AUTH_GOOGLE_SECRET AUTH_GITHUB_ID AUTH_GITHUB_SECRET	Đăng nhập bằng Google hoặc GitHub (xem trang Xác thực)	Không bắt buộc

Lưu ý bảo mật

Không commit file .env. File này đã có trong .gitignore; chỉ .env.example được commit.

Các lệnh npm

Lệnh	Mô tả
npm run dev	Chạy máy chủ phát triển
npm run build	Build bản production
npm run start	Chạy bản đã build
npm run typecheck	Kiểm tra kiểu TypeScript
npm run lint	Chạy ESLint
npm test	Chạy unit test (Vitest)
npm run test:e2e	Chạy e2e test (Playwright)
npm run i18n:check	Tìm chuỗi tiếng Anh chưa Việt hóa
npm run db:migrate	Tạo và áp dụng migration mới (dev)
npm run db:deploy	Áp dụng migration có sẵn (máy mới, UAT, production)
npm run db:seed	Tạo dữ liệu mẫu
npm run db:studio	Mở Prisma Studio