Triển khai BQL Server

Trang này hướng dẫn triển khai BQL Server (bql-server) — gRPC server thực thi truy vấn BQL trên OpenSearch. BQL Server là một binary Rust đơn giản, không cần database riêng, không lưu trạng thái — bạn có thể triển khai bằng một trong các cách sau:

• Docker image từ GHCR (khuyến nghị)
• Docker Compose (dev hoặc production)
• systemd service (Linux)
• Build từ source (Rust)

ℹ️

Giả định: bạn đã có một cụm **OpenSearch 3.x** truy cập được từ máy chạy BQL Server. BQL Server không chứa dữ liệu — nó chỉ truy vấn OpenSearch.

Yêu cầu

Yêu cầu	Ghi chú
OpenSearch 3.x	Nguồn dữ liệu truy vấn, truy cập được qua mạng từ BQL Server
Cổng 9090	Port gRPC mặc định (có thể đổi qua port mapping Docker)
Rust 1.88+	Chỉ cần nếu build từ source
grpcurl	Khuyến nghị, để kiểm tra server sau khi triển khai

Triển khai bằng Docker (khuyến nghị)

Image GHCR

Image chính thức được build và đẩy lên GHCR tự động qua CI/CD (docker-publish.yml) khi có push lên main hoặc tag v*:

ghcr.io/gcsclabs/bql-server

Các tag có sẵn:

Tag	Nguồn	Ví dụ
<semver>	Tag v*	v0.1.0
main	Branch main	main
<sha>	Commit SHA	a1b2c3d

📝

BQL Server dùng **workspace version chung** của repo BQL (`0.1.0` tại thời điểm viết tài liệu này). Tag semver khớp với tag git dạng `v` + số phiên bản (ví dụ `v0.1.0`).

Chạy bằng docker run

docker pull ghcr.io/gcsclabs/bql-server:latest

docker run -d \
  --name bql-server \
  -p 9090:9090 \
  --restart unless-stopped \
  ghcr.io/gcsclabs/bql-server:latest

Image chạy binary bql-server trực tiếp (entrypoint), expose port 9090 (gRPC). Không cần volume — server không lưu dữ liệu.

Cấu hình log level

docker run -d \
  --name bql-server \
  -p 9090:9090 \
  -e RUST_LOG=debug \
  ghcr.io/gcsclabs/bql-server:latest

Triển khai bằng Docker Compose

Môi trường development (kèm OpenSearch)

File docker-compose.dev.yml trong repo BQL khởi động OpenSearch 3.1.0 và BQL Server cùng lúc — phù hợp để phát triển và thử nghiệm:

services:
  opensearch:
    image: opensearchproject/opensearch:3.1.0
    container_name: bql-opensearch
    environment:
      - discovery.type=single-node
      - OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m
      - DISABLE_INSTALL_DEMO_CONFIG=true
      - DISABLE_SECURITY_PLUGIN=true
    ports:
      - "9200:9200"
      - "9600:9600"
    ulimits:
      memlock:
        soft: -1
        hard: -1

  bql-server:
    build: .
    container_name: bql-server
    ports:
      - "9090:9090"
    depends_on:
      - opensearch

docker compose -f docker-compose.dev.yml up -d

⚠️

Cấu hình dev này tắt security plugin của OpenSearch (`DISABLE_SECURITY_PLUGIN=true`). Không dùng cho production.

Môi trường production (image có sẵn)

File docker-compose.deploy.yml chạy BQL Server từ image GHCR, tham gia network stg-net có sẵn:

services:
  app:
    image: ${APP_IMAGE}
    container_name: bql-server
    ports:
      - "9090:9090"
    restart: unless-stopped
    networks:
      - stg-net

networks:
  stg-net:
    external: true

# Tạo network trước (một lần)
docker network create stg-net

# Chạy với image cụ thể
APP_IMAGE=ghcr.io/gcsclabs/bql-server:main docker compose -f docker-compose.deploy.yml up -d

Đây chính là quy trình mà CI/CD dùng khi deploy lên runner blh-stg:

APP_IMAGE=ghcr.io/gcsclabs/bql-server:<tag> \
  docker compose -f docker-compose.deploy.yml pull app
docker compose -f docker-compose.deploy.yml up -d --no-build app

📝

Đảm bảo OpenSearch nằm trong cùng network (`stg-net`) hoặc truy cập được qua URL mà client gửi trong request.

Triển khai bằng systemd (Linux)

Nếu muốn chạy binary trực tiếp trên máy chủ (không Docker), bạn có thể chạy BQL Server như một systemd service.

Bước 1: Tạo user hệ thống

sudo adduser \
  --system \
  --shell /bin/false \
  -U \
  --no-create-home \
  bql

Bước 2: Đặt binary vào vị trí chuẩn

Tải binary release (hoặc copy từ build) vào /opt/bql-server:

sudo mkdir -p /opt/bql-server
# Copy binary bql-server vào /opt/bql-server/bql-server
sudo chown -R bql:bql /opt/bql-server

Bước 3: Tạo systemd unit

Tạo /etc/systemd/system/bql-server.service:

[Unit]
Description=BlackHole BQL Server (gRPC)
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
ExecStart=/opt/bql-server/bql-server
WorkingDirectory=/opt/bql-server

User=bql
Group=bql

Environment=RUST_LOG=info

Restart=on-failure
RestartSec=5

LimitNOFILE=65535
TimeoutStartSec=30

[Install]
WantedBy=multi-user.target

Bước 4: Khởi động

sudo systemctl daemon-reload
sudo systemctl enable --now bql-server
sudo systemctl status bql-server

Xem log:

journalctl -u bql-server -f

Build từ source

Yêu cầu

• Rust 1.88+ (rustc --version để kiểm tra)
• Toolchain build cho binary (xem workspace Cargo.toml)

Build

# Từ workspace root của repo BQL
cargo build -p bql-server --release

Binary nằm tại target/release/bql-server.

Chạy

# Default: listen trên 0.0.0.0:9090
./target/release/bql-server

# Hoặc qua cargo (debug)
RUST_LOG=debug cargo run -p bql-server

Server shutdown mượt (graceful) khi nhận Ctrl+C (Unix: cả SIGTERM).

📝

Nếu OpenSearch dùng HTTPS với certificate tự ký, hãy đảm bảo client gửi đúng URL và credential trong request — BQL Server chuyển tiếp nguyên trạng.

Kiểm tra sau triển khai

Sau khi server chạy, kiểm tra nhanh bằng grpcurl (server reflection đã bật):

# Liệt kê service
grpcurl -plaintext localhost:9090 list

# Mô tả service Bql
grpcurl -plaintext localhost:9090 describe bql.v1.Bql

# Mô tả message ExecuteRequest
grpcurl -plaintext localhost:9090 describe bql.v1.ExecuteRequest

Kết quả mong đợi:

bql.v1.Bql
transform.v1.TransformService
grpc.reflection.v1.ServerReflection

⚠️

BQL Server mặc định chạy **plaintext gRPC** (không TLS). Trong production, hãy đặt server phía sau reverse proxy hỗ trợ TLS/gRPC, hoặc giới hạn truy cập mạng (firewall/private network) cho port 9090.

Liên kết liên quan

• Tổng quan BQL Server
• Cấu hình BQL Server
• Vận hành BQL Server
• Khắc phục sự cố
• Ngôn ngữ truy vấn BQL