Kairso — Nền tảng vận hành cho đội nhóm hiệu suất cao

Trong trang này

1. Yêu cầu
2. Chạy nhanh
3. Cấu hình
4. Firebase (đăng nhập)
5. Dùng DB / lưu trữ riêng
6. Kiến trúc
7. Nâng cấp & HTTPS

Kairso được đóng gói thành một image duy nhất alexcao194/kairso trên Docker Hub (đa kiến trúc amd64 + arm64): web, máy chủ và realtime chạy chung một container. Bạn chỉ cần tạo hai file cấu hình bên dưới, không phải tải mã nguồn hay build gì cả.

1. Yêu cầu

Docker + Docker Compose plugin.
Một Firebase project của riêng bạn để đăng nhập (xem phần Firebase).

2. Chạy nhanh

Tạo một thư mục (vd kairso/) chứa ba file:

1. docker-compose.yml

# Kairso self-host: the all-in-one Kairso image plus PostgreSQL, Redis and MinIO.
# Put this file next to .env and firebase-credentials.json, then: docker compose up -d
# Using your own PostgreSQL / S3 / Redis? Delete those services (and depends_on) and
# set DB_* / MINIO_* / REDIS_* in .env.
name: kairso

services:
  kairso:
    image: alexcao194/kairso:${KAIRSO_TAG:-latest}
    restart: unless-stopped
    ports:
      - "${PUBLIC_PORT:-8080}:80"
    env_file: .env
    volumes:
      - kairso-data:/data
      - ./firebase-credentials.json:/etc/kairso/firebase-credentials.json:ro
    depends_on:
      postgres: { condition: service_healthy }
      redis: { condition: service_healthy }
      minio: { condition: service_started }

  postgres:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: kairso
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: kairso
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kairso"]
      interval: 5s
      timeout: 5s
      retries: 10

  redis:
    image: redis:alpine
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  minio:
    image: bitnamilegacy/minio:latest
    restart: unless-stopped
    environment:
      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY}
      MINIO_DEFAULT_BUCKETS: kairso:download
      MINIO_API_CORS_ALLOW_ORIGIN: "*"
    volumes:
      - minio-data:/bitnami/minio/data

volumes:
  kairso-data:
  postgres-data:
  minio-data:

2. .env — điền mật khẩu và cấu hình Firebase (xem phần Firebase).

# Kairso self-host settings. Fill in the passwords and the Firebase web config.
PUBLIC_URL=http://localhost:8080
PUBLIC_PORT=8080

DB_PASSWORD=change-me
MINIO_ACCESS_KEY=kairso
MINIO_SECRET_KEY=change-me-please

# Firebase > Project settings > Your apps > SDK config
FIREBASE_API_KEY=
FIREBASE_AUTH_DOMAIN=
FIREBASE_PROJECT_ID=
FIREBASE_STORAGE_BUCKET=
FIREBASE_MESSAGING_SENDER_ID=
FIREBASE_APP_ID=

# Optional
# KAIRSO_TAG=v0.2.0
# MAX_UPLOAD_SIZE=200m
# FIREBASE_VAPID_KEY=

3. firebase-credentials.json — service account Firebase của bạn.

Rồi khởi động:

docker compose up -d

Mở http://localhost:8080 (hoặc PUBLIC_URL bạn đặt). Khi khởi động, container tự chạy migration CSDL và tự sinh JWT_SECRET, APP_TOKEN_SECRET. Dữ liệu nằm trong Docker volume và được giữ khi nâng cấp.

3. Cấu hình (`.env`)

Chỉ cần điền mật khẩu và Firebase; mọi thứ khác đã có giá trị mặc định.

DB_PASSWORD, MINIO_ACCESS_KEY, MINIO_SECRET_KEY — mật khẩu cho PostgreSQL và MinIO gói sẵn.
FIREBASE_* — cấu hình Firebase (bên dưới).
PUBLIC_URL / PUBLIC_PORT — URL và cổng người dùng truy cập (mặc định http://localhost:8080).
Tuỳ chọn: KAIRSO_TAG (ghim phiên bản, vd v0.2.0), MAX_UPLOAD_SIZE (mặc định 200m), JWT_SECRET / APP_TOKEN_SECRET nếu muốn tự đặt.

4. Firebase (bắt buộc để đăng nhập)

Tạo project tại Firebase Console, bật Authentication → Google (và/hoặc Email).
Lấy client config (Project settings → Your apps → SDK config) → điền các biến FIREBASE_* trong .env.
Tạo service account (Project settings → Service accounts → Generate new private key) → lưu thành firebase-credentials.json, hoặc dán nội dung JSON vào biến FIREBASE_CREDENTIALS_JSON.
Thêm domain của bạn vào Authentication → Settings → Authorized domains.

5. Dùng database / lưu trữ của riêng bạn

Database phải tương thích PostgreSQL 15+ (tự host, AWS RDS, Supabase, Neon…). Lưu trữ tệp dùng bất kỳ dịch vụ tương thích S3 nào (AWS S3, Cloudflare R2, Backblaze B2, Wasabi, MinIO…).

Xoá service postgres, redis và/hoặc minio (cùng dòng tương ứng trong depends_on) khỏi docker-compose.yml, rồi thêm vào .env:

DB_HOST=your-db-host
DB_PORT=5432
DB_USER=kairso
DB_NAME=kairso
DB_SSLMODE=require

MINIO_ENDPOINT=s3.amazonaws.com      # host:port, không kèm https://
MINIO_USE_SSL=true
MINIO_BUCKET=your-bucket
MINIO_PUBLIC_URL=https://your-bucket.s3.amazonaws.com

REDIS_HOST=your-redis

Rồi docker compose up -d như bình thường.

6. Kiến trúc

Trình duyệt chỉ nói chuyện với một cổng duy nhất của container Kairso:

/ → web (Next.js). Web gọi máy chủ nội bộ qua /api/proxy (ký HMAC, secret không lộ).
/ws → máy chủ (realtime WebSocket, same-origin).
/cdn/ → MinIO (file/ảnh) khi dùng bản gói sẵn.

Cấu hình Firebase nạp lúc chạy, nên cùng một image chạy được ở mọi domain mà không phải build lại.

7. Nâng cấp & HTTPS

Nâng cấp:

docker compose pull && docker compose up -d

Chạy sau HTTPS: đặt một reverse proxy (Caddy/Traefik/nginx) phía trước trỏ về PUBLIC_PORT, rồi đặt PUBLIC_URL=https://your-domain. Không cần sửa gì khác.

Muốn phát triển hoặc đóng góp cho Kairso? Mã nguồn mở trên GitHub.

Cài đặt & tự host