Tải về và cấu hình file docker-compose.yml cho Materialize
Chúng ta sẽ tạo thư mục làm việc riêng biệt cho cụm Materialize để cô lập các dịch vụ và quản lý file cấu hình dễ dàng hơn.
mkdir -p /opt/materialize-cluster
cd /opt/materialize-cluster
Thư mục này sẽ chứa file docker-compose.yml và các volume data cần thiết. Kết quả mong đợi là bạn đang đứng trong thư mục /opt/materialize-cluster.
File docker-compose.yml là trái tim của việc triển khai, nơi định nghĩa các service: Materialized (core engine), Frontend (web UI), Computation Node (xử lý dữ liệu), và PostgreSQL (lưu trữ metadata). Chúng ta sẽ sử dụng version 3.9 để đảm bảo tương thích cao với Docker Compose hiện đại.
Đường dẫn file: /opt/materialize-cluster/docker-compose.yml. Nội dung hoàn chỉnh dưới đây đã được tối ưu cho môi trường Ubuntu 24.04:
version: '3.9'
services:
# Service lưu trữ metadata (PostgreSQL)
# Lưu ý: Materialize cần một PostgreSQL riêng để lưu catalog (metadata), không dùng chung với source data
postgres:
image: postgres:15-alpine
container_name: mz-postgres
environment:
- POSTGRES_DB=materialize
- POSTGRES_USER=materialize
- POSTGRES_PASSWORD=materialize-password
volumes:
- postgres_data:/var/lib/postgresql/data
networks:
- materialize-net
healthcheck:
test: ["CMD-SHELL", "pg_isready -U materialize -d materialize"]
interval: 5s
timeout: 5s
retries: 5
# Core engine của Materialize
materialized:
image: materialize/materialized:v0.40.0
container_name: mz-core
command:
- --storage-url=postgres://materialize:materialize-password@postgres:5432/materialize
- --internal-addr=0.0.0.0:6875
- --external-addr=0.0.0.0:6876
- --listen-addr=0.0.0.0:6877
- --admission-control-enabled=false
- --dataflow-http-api-addr=0.0.0.0:6878
ports:
- "6876:6876"
- "6877:6877"
- "6878:6878"
environment:
- MZ_AUTHENTICATION=dev
- MZ_DEVELOPMENT_MODE=1
depends_on:
postgres:
condition: service_healthy
networks:
- materialize-net
volumes:
- mz_data:/var/lib/materialize
# Computation Node (Dataflow)
# Xử lý các tác vụ stream processing nặng nề
computation-node:
image: materialize/materialized:v0.40.0
container_name: mz-compute
command:
- --storage-url=postgres://materialize:materialize-password@postgres:5432/materialize
- --internal-addr=0.0.0.0:6875
- --external-addr=0.0.0.0:6876
- --listen-addr=0.0.0.0:6877
- --admission-control-enabled=false
- --dataflow-http-api-addr=0.0.0.0:6878
- --role=compute
- --compute-id=1
networks:
- materialize-net
depends_on:
postgres:
condition: service_healthy
materialized:
condition: service_started
# Frontend (Web UI)
# Giao diện quản lý người dùng
frontend:
image: materialize/materialize-frontend:v0.40.0
container_name: mz-frontend
ports:
- "3000:3000"
environment:
- MATERIALIZE_HOST=mz-core
- MATERIALIZE_PORT=6877
- MATERIALIZE_PROTOCOL=postgres
- MATERIALIZE_USER=materialize
- MATERIALIZE_PASSWORD=materialize-password
depends_on:
materialized:
condition: service_started
networks:
- materialize-net
networks:
materialize-net:
driver: bridge
volumes:
postgres_data:
mz_data:
Kết quả mong đợi: File docker-compose.yml đã được tạo thành công với cấu hình 4 dịch vụ, mạng riêng materialize-net và volume lưu trữ.
Khởi động cụm Materialize với Docker Compose
Trước khi khởi động, chúng ta cần kiểm tra lại file cấu hình có syntax đúng hay không để tránh lỗi khởi tạo.
docker compose config
Kết quả mong đợi: Docker Compose in ra nội dung file đã được phân tích (parsed) mà không báo lỗi yaml: line X: ....
Bây giờ chúng ta sẽ khởi động toàn bộ cụm. Sử dụng flag -d để chạy ở chế độ background (detached) và flag --wait để Docker Compose chờ cho các service con (như PostgreSQL) sẵn sàng trước khi coi là hoàn tất khởi động.
docker compose up -d --wait
Kết quả mong đợi: Dòng lệnh trả về thông báo Successfully started cho các container mz-postgres, mz-core, mz-compute, và mz-frontend.
Để xác minh trạng thái khởi động, chúng ta cần kiểm tra xem các container đã lên running và đã vượt qua health check (nếu có) hay chưa.
docker compose ps
Kết quả mong đợi: Tất cả 4 container đều có trạng thái running. Container mz-postgres nên có trạng thái healthy trong cột health.
Quan trọng nhất là kiểm tra log của core service materialized để đảm bảo nó đã kết nối thành công với PostgreSQL metadata và sẵn sàng nhận kết nối.
docker logs mz-core --tail 20
Kết quả mong đợi: Trong log xuất hiện dòng listening on 0.0.0.0:6877 và không có lỗi connection refused hoặc password authentication failed liên quan đến PostgreSQL.
Cấu hình kết nối giữa Materialize và PostgreSQL
Về mặt kỹ thuật, kết nối giữa Materialize và PostgreSQL đã được cấu hình sẵn trong file docker-compose.yml thông qua biến môi trường --storage-url trong command của service materialized. Tuy nhiên, để đảm bảo kết nối này hoạt động thực tế, chúng ta cần kiểm tra tính khả dụng của dịch vụ từ bên ngoài.
Materialize sử dụng PostgreSQL làm nơi lưu trữ metadata (catalog). Để verify, chúng ta sẽ dùng CLI psql để kết nối trực tiếp vào database materialize trên container PostgreSQL và kiểm tra xem các bảng system catalog đã được Materialize tạo ra chưa.
docker exec -it mz-postgres psql -U materialize -d materialize -c "\dt mz_system.*"
Kết quả mong đợi: Xuất hiện danh sách các bảng thuộc schema mz_system (ví dụ: mz_system.mz_columns, mz_system.mz_databases). Nếu không có bảng nào, nghĩa là Materialize chưa kịp khởi tạo metadata.
Bước tiếp theo là kiểm tra kết nối từ client SQL vào Materialize (qua cổng 6877) để đảm bảo core engine đã nhận diện được kết nối đến PostgreSQL backend.
docker exec -it mz-core mz-tpc -e "SELECT mz_system.mz_build_info;" --host mz-core --port 6877 --username materialize --password materialize-password
Chú ý: Nếu bạn chưa cài đặt mz-tpc hoặc CLI Materialize, hãy dùng psql từ container khác hoặc host ngoài:
psql "host=127.0.0.1 port=6877 dbname=materialize user=materialize password=materialize-password" -c "SELECT mz_build_info();"
Kết quả mong đợi: Trả về thông tin phiên bản của Materialize (ví dụ: Materialize 0.40.0...). Điều này xác nhận thành công cả 3 khâu: PostgreSQL lưu metadata, Materialized engine khởi động, và kết nối giữa chúng đã hoạt động.
Để kiểm tra nhanh hơn với Web UI (Frontend), mở trình duyệt và truy cập:
http://localhost:3000
Kết quả mong đợi: Trang đăng nhập Materialize xuất hiện. Nhập materialize (user) và materialize-password (password) để đăng nhập. Nếu vào được Dashboard, chứng tỏ Frontend đã kết nối thành công với Core và Core đã kết nối với PostgreSQL.
Điều hướng series:
Mục lục: Series: Triển khai Database Stream-native với Materialize trên Ubuntu 24.04
« Phần 1: Chuẩn bị môi trường Ubuntu 24.04 và cài đặt Docker Engine
Phần 3: Cấu hình nguồn dữ liệu Kafka và Confluent Schema Registry »