UIT iMap Server

Backend Express.js server cho ứng dụng UIT iMap. Server cung cấp các RESTful API quản lý dữ liệu bản đồ (hotspots, rooms, tourScenes, tiles,...), tích hợp xác thực JWT, phục vụ ứng dụng web tĩnh và quy trình đóng gói đa tầng với Docker.

Cài đặt

Yêu cầu hệ thống

• Node.js: phiên bản >= 18
• npm (hoặc yarn / pnpm)
• Docker & Docker Compose (nếu triển khai dạng container)

Các bước cài đặt

1. Di chuyển vào thư mục dự án server:

   cd uit-imap-server

2. Cài đặt các gói phụ thuộc (dependencies):

   npm install

3. Cấu hình biến môi trường: Tạo hoặc chỉnh sửa file .env tại thư mục gốc của server.

---

Khởi chạy

Development environment

npm run dev

Production environment

npm start

Chạy và Build qua Docker Compose

Lệnh khởi chạy nhanh

cd uit-imap-server
docker compose build --no-cache
docker compose up -d

Cơ chế đồng bộ biến môi trường & Giá trị mặc định

• docker-compose.yml đã được đồng bộ các thuộc tính cấu hình từ file .env.
• Cơ chế fallback mặc định: Nếu khi build hoặc khởi chạy không truyền thuộc tính (hoặc file .env bị thiếu/không tồn tại), docker-compose.yml sẽ tự động lấy giá trị mặc định được đồng bộ từ .env dạng ${VARIABLE:-default_value}.
• Các thuộc tính cấu hình chính bao gồm:

Biến môi trường	Giá trị mặc định trong build	Mô tả
PORT	4000	Cổng dịch vụ backend và port mapping của container
SITE_URL	https://localhost	URL gốc của ứng dụng (dùng tạo SEO metadata)
STUDENT_REPO_URL	https://github.com/helitoo/uit-imap.git	Git repository của app Student
STUDENT_REPO_BRANCH	main	Nhánh Git ứng dụng Student
STUDENT_VITE_BASE_PATH	/	Base path ứng dụng Student
MANAGER_REPO_URL	https://github.com/helitoo/uit-imap-manager.git	Git repository của app Manager
MANAGER_REPO_BRANCH	main	Nhánh Git ứng dụng Manager
MANAGER_VITE_BASE_PATH	/manager/	Base path ứng dụng Manager
API_URL	/api	Tiền tố API URL cho frontend
DATA_PATH	./data	Đường dẫn thư mục dữ liệu (Mount volume)
JWT_SECRET		Khóa bí mật JWT token (Runtime)
JWT_EXPIRES_IN	24h	Thời gian hết hạn JWT token (Runtime)
CORS_ORIGINS	(trống)	Danh sách domain CORS cho phép (Runtime)

Cấu hình tham số khi build

Bạn có thể thay đổi các giá trị cấu hình theo các cách sau:

1. Chỉnh sửa file .env: Thay đổi giá trị mong muốn trong file .env tại thư mục gốc server, sau đó chạy:

   docker compose up -d --build

2. Ghi đè trực tiếp qua dòng lệnh:

   STUDENT_REPO_BRANCH=dev PORT=5000 docker compose up -d --build