README.md

metadata

title: Nexus Chat
emoji: 💬
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
app_port: 7860

Nexus Chat — Standalone Node.js Server

Server chat (Express 5 + WebSocket + PostgreSQL + Redis), chạy trực tiếp bằng Node, không cần bước build. Dữ liệu lưu trong PostgreSQL; Redis dùng cho trạng thái online và pub/sub realtime (hỗ trợ chạy nhiều instance).

Cài đặt

npm install
cp .env.example .env   # rồi sửa các giá trị cho phù hợp

Chạy

npm start
# hoặc khi phát triển (tự restart khi sửa file):
npm run dev

Hoặc chạy toàn bộ (app + Postgres + Redis) bằng Docker Compose:

docker compose up --build

Mặc định lắng nghe ở PORT=7860 (đặt biến môi trường PORT để đổi; Hugging Face Spaces yêu cầu 7860).

Biến môi trường (.env)

Xem file .env.example để biết toàn bộ danh sách. Các nhóm chính:

Nhóm	Biến	Ý nghĩa
Server	PORT, NODE_ENV, LOG_LEVEL	Cổng, môi trường, mức log
Auth	JWT_SECRET, SEED_ADMIN_PASSWORD	Khóa ký JWT, mật khẩu admin seed lần đầu
PostgreSQL	DATABASE_URL hoặc PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE/PGSSL	Kết nối database
Redis	REDIS_URL	Kết nối Redis (presence + pub/sub)
Web Push	VAPID_PUBLIC, VAPID_PRIVATE, VAPID_EMAIL	Web Push notifications

DATABASE_URL nếu được đặt sẽ ưu tiên hơn các biến PG* riêng lẻ. Với các nhà cung cấp Postgres managed (Neon, Supabase, RDS...) thường cần PGSSL=true.

Cấu trúc

src/
  index.js        # entrypoint: init Postgres + Redis, tạo HTTP server, WS, seed admin
  app.js          # Express app: middleware + static + routes
  db/index.js     # lớp dữ liệu PostgreSQL (pg)
  lib/
    logger.js     # pino logger
    redis.js      # Redis client, presence helpers, pub/sub
  chat/
    routes.js     # toàn bộ REST API (auth, friends, rooms, messages, admin)
    ws.js         # WebSocket server (chat realtime, gọi điện WebRTC)
    push.js       # Web Push notifications
public/
  index.html      # UI gốc
  patch.js        # script vá lỗi phía client (được tự động chèn vào index.html)
  sw.js           # service worker cho push

Tài khoản admin mặc định

Khi server khởi động lần đầu, hai tài khoản admin sẽ được tạo tự động:

• admin@nexus.vn
• quantri@nexus.vn

Mật khẩu mặc định lấy từ SEED_ADMIN_PASSWORD (mặc định 11082012) — nên đặt biến môi trường này thành một mật khẩu mạnh, hoặc đổi ngay sau khi đăng nhập lần đầu (qua PUT /me/password).

Database

Schema PostgreSQL được tự động tạo (nếu chưa có) khi server khởi động (initDb() trong src/db/index.js). Cần một database PostgreSQL đang chạy và truy cập được qua DATABASE_URL.

Redis

Redis được dùng để:

• Theo dõi danh sách user đang online (set nexus:online), hoạt động đúng khi chạy nhiều instance của server.
• Pub/Sub kênh nexus:events để chuyển tiếp tin nhắn realtime (chat, typing, thu hồi tin nhắn, gọi điện WebRTC...) giữa các instance.

Deploy lên Hugging Face Spaces (Docker)

1. Tạo Space mới, chọn SDK Docker.
2. Cấu hình các biến môi trường (Settings → Variables and secrets) tương ứng với .env.example — đặc biệt DATABASE_URL, REDIS_URL, JWT_SECRET, SEED_ADMIN_PASSWORD.
3. Push code (kèm Dockerfile) lên Space.

Lưu ý: PostgreSQL và Redis cần chạy ở dịch vụ ngoài (managed Postgres/Redis), vì Hugging Face Spaces không cung cấp các dịch vụ này.