Yêu cầu phần cứng và môi trường Ubuntu 24.04
EdgeDB là một hệ thống quản trị cơ sở dữ liệu (database) hiện đại, yêu cầu tài nguyên để chạy engine cốt lõi và các dịch vụ phụ trợ như PostgreSQL (backend) và các trình biên dịch EdgeQL.
Để đảm bảo hiệu năng ổn định khi triển khai trên Ubuntu 24.04, bạn cần đáp ứng các thông số tối thiểu sau:
- CPU: Tối thiểu 2 nhân (cores), kiến trúc x86_64 hoặc ARM64.
- RAM: Tối thiểu 4GB (khuyến nghị 8GB để chạy container và cache hiệu quả).
- Disk: Tối thiểu 20GB dung lượng trống, ưu tiên SSD để tăng tốc độ I/O.
- Network: Cổng 5656 (gRPC) và 5660 (HTTP/REST) phải mở.
Trước khi bắt đầu cài đặt, hãy xác minh phiên bản hệ điều hành của bạn. EdgeDB yêu cầu nền tảng Linux tương đối mới để hỗ trợ các tính năng container hóa.
cat /etc/os-release
Kết quả mong đợi: Dòng VERSION_CODENAME phải hiển thị "noble" và VERSION là "24.04 LTS". Nếu không, bạn cần nâng cấp hoặc chọn một bản Ubuntu mới hơn.
Cập nhật hệ thống và cài đặt gói phụ thuộc
Ubuntu 24.04 có thể có các gói cũ trong kho mặc định. Bước này đảm bảo bạn có các công cụ hệ thống mới nhất và các thư viện cần thiết để chạy Docker và EdgeDB.
sudo apt update && sudo apt upgrade -y
Kết quả mong đợi: Hệ thống báo cáo đã cập nhật xong, không có lỗi về gói bị thiếu hoặc xung đột.
Cài đặt các công cụ cần thiết: curl để tải file, wget để tải tài nguyên, git để quản lý mã nguồn, và build-essential nếu bạn cần biên dịch một số thành phần tùy chọn.
sudo apt install -y curl wget git build-essential ca-certificates gnupg lsb-release
Kết quả mong đợi: Các gói được cài đặt thành công, không có cảnh báo về lỗi checksum.
Cài đặt Docker Engine để chạy EdgeDB trong container. Đây là phương pháp triển khai được khuyến nghị chính thức cho EdgeDB trên Linux.
sudo apt install -y docker.io docker-compose-plugin
Kết quả mong đợi: Docker Engine và plugin Docker Compose được cài đặt. Bạn cần thêm user hiện tại vào group docker để chạy lệnh không cần sudo.
sudo usermod -aG docker $USER && newgrp docker
Kết quả mong đợi: Không có đầu ra (silent success). Bạn cần đăng xuất và đăng nhập lại, hoặc chạy lệnh newgrp docker để áp dụng thay đổi quyền ngay lập tức.
Kiểm tra xem Docker có hoạt động không.
docker --version && docker compose version
Kết quả mong đợi: Hiển thị phiên bản Docker Engine và Docker Compose (ví dụ: Docker version 26.0.x, Docker Compose version 2.2x.x).
Cài đặt EdgeDB CLI và cấu hình Docker Compose
EdgeDB CLI là công cụ dòng lệnh chính để tương tác với cơ sở dữ liệu. Nó giúp tạo instance, chạy query và quản lý schema.
Tải và cài đặt EdgeDB CLI từ kho chính thức của EdgeDB.
curl -fsSL https://sh.edgedb.com | sudo sh
Kết quả mong đợi: Script tải file binary, tạo thư mục cài đặt, và thêm alias edgedb vào PATH. Lệnh sẽ thông báo "EdgeDB CLI installed successfully".
Khởi tạo một instance EdgeDB mới bằng CLI. Lệnh này tự động tạo cấu hình Docker Compose cần thiết cho bạn.
edgedb instance create mydb --port 5656
Kết quả mong đợi: CLI sẽ in ra thông báo đang tạo instance, tải image Docker, và khởi động container. Bạn sẽ thấy thông báo "Instance 'mydb' created successfully".
Lệnh trên đã tự động tạo file cấu hình trong thư mục ẩn ~/.edgedb/. Để minh họa cấu trúc, hãy xem file Docker Compose đã được tạo.
cat ~/.edgedb/instances/mydb/docker-compose.yml
Kết quả mong đợi: Một file YAML định nghĩa dịch vụ edgedb, ánh xạ cổng 5656, và cấu hình volume để lưu trữ dữ liệu.
Đảm bảo file docker-compose.yml có nội dung chính xác như sau để bạn có thể tùy chỉnh sau này nếu cần:
version: "3.9"
services:
edgedb:
image: edgedb/edgedb:latest
ports:
- "5656:5656"
volumes:
- edgedb-data:/var/lib/edgedb
environment:
- EDGEDB_SERVER_PORT=5656
- EDGEDB_SERVER_ADDRESS=0.0.0.0
restart: unless-stopped
healthcheck:
test: ["CMD", "edgedb", "cli", "query", "SELECT 1"]
interval: 30s
timeout: 10s
retries: 5
volumes:
edgedb-data:
Kết quả mong đợi: File cấu hình này đảm bảo container chạy với tên edgedb, ánh xạ cổng gRPC 5656, và sử dụng volume để dữ liệu không mất khi container bị xóa.
Khởi động và kiểm tra trạng thái dịch vụ EdgeDB
Dịch vụ EdgeDB thường tự động khởi động sau khi tạo instance bằng CLI. Tuy nhiên, hãy kiểm tra trạng thái để đảm bảo mọi thứ ổn định.
docker compose -f ~/.edgedb/instances/mydb/docker-compose.yml ps
Kết quả mong đợi: Một bảng hiển thị service edgedb với trạng thái Up (hoặc Running) và cổng 5656 được ánh xạ.
Chạy lệnh kiểm tra sức khỏe (healthcheck) thông qua CLI để xác nhận database đã sẵn sàng nhận kết nối.
edgedb query "SELECT 'Hello from EdgeDB'"
Kết quả mong đợi: Đầu ra hiển thị chuỗi ["Hello from EdgeDB"] hoặc tương tự. Nếu lỗi xảy ra, hãy kiểm tra log.
Xem log của container để debug nếu gặp sự cố khởi động.
docker logs -f edgedb-mydb
Kết quả mong đợi: Dòng log cuối cùng phải là "Listening on 0.0.0.0:5656" hoặc "Server is ready". Nếu thấy lỗi Permission denied hoặc Port already in use, bạn cần kiểm tra quyền hoặc giải phóng cổng.
Đẩy mạnh việc kiểm tra bằng cách liệt kê các instance hiện có.
edgedb instance list
Kết quả mong đợi: Danh sách hiển thị instance mydb với trạng thái Active hoặc Running, xác nhận môi trường đã sẵn sàng cho các bước thiết kế Schema tiếp theo.
Điều hướng series:
Mục lục: Series: Triển khai Database Edge-native với EdgeDB trên Ubuntu 24.04
Phần 2: Thiết kế mô hình dữ liệu Schema với EdgeQL »