Hướng Dẫn Tự Host Supabase Trên Ubuntu Server Chi Tiết Từ A-Z

Tự host Supabase trên Ubuntu Server là lựa chọn hàng đầu cho các lập trình viên muốn sở hữu hạ tầng Backend-as-a-Service (BaaS) mạnh mẽ, toàn quyền kiểm soát cơ sở dữ liệu PostgreSQL mà không lo ngại chi phí tăng cao theo quy mô từ các dịch vụ Cloud. Bài viết này của InterData sẽ hướng dẫn bạn từng bước triển khai hệ thống hoàn chỉnh bằng Docker Compose, tối ưu bảo mật và sẵn sàng đưa vào vận hành thực tế.

1. Yêu cầu cấu hình phần cứng để tự host Supabase trên Ubuntu Server

Supabase không phải là một ứng dụng đơn lẻ mà là một hệ sinh thái microservices chạy đồng thời hơn 10 container độc lập: Kong (API Gateway), GoTrue (Xác thực Auth), PostgREST (REST API), Realtime Engine, Supabase Storage, Supabase Studio Dashboard, và lõi PostgreSQL (tích hợp sẵn extension pgvector). Do đó, việc phân bổ tài nguyên phần cứng chính xác đóng vai trò quyết định đến độ ổn định của toàn bộ hệ thống.

Nếu bạn chạy trên máy chủ có cấu hình dưới mức tối thiểu, hệ điều hành Linux sẽ kích hoạt cơ chế OOM Killer (Out Of Memory) để tắt bớt container, dẫn đến tình trạng mất kết nối cơ sở dữ liệu hoặc lỗi cổng Gateway. Trước khi tiến hành triển khai trên hệ điều hành Ubuntu Server, bạn nên thực hiện các thao tác kiểm tra cấu hình máy chủ hiện tại để đảm bảo đáp ứng bảng thông số kỹ thuật dưới đây.

2. Bước 1: Chuẩn bị Ubuntu Server và cài đặt Docker Compose

Các phiên bản Ubuntu Server khuyến nghị gồm Ubuntu 22.04 LTS hoặc Ubuntu 24.04 LTS. Trước khi triển khai, hãy kết nối SSH vào máy chủ với quyền root hoặc người dùng có đặc quyền sudo và cập nhật toàn bộ package index lên phiên bản mới nhất.

# Cập nhật danh sách gói và nâng cấp hệ thống
sudo apt update && sudo apt upgrade -y

# Cài đặt các gói phụ trợ cần thiết
sudo apt install -y curl apt-transport-https ca-certificates gnupg lsb-release git

Supabase sử dụng định dạng compose specification chuẩn hiện đại, do đó bạn cần cài đặt Docker Engine kèm plugin Docker Compose V2 (sử dụng cú pháp lệnh docker compose thay vì phiên bản cũ docker-compose). Để tìm hiểu chi tiết về cách quản lý container, bạn có thể tham khảo bài viết hướng dẫn cài đặt Docker Compose trên Ubuntu.

# Thêm khóa GPG chính thức của Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Thiết lập Docker repository
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Cài đặt Docker Engine và Docker Compose Plugin
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Kiểm tra phiên bản hoạt động
docker --version
docker compose version

3. Bước 2: Tải mã nguồn Supabase và cấu hình biến môi trường an toàn

Để tránh kéo toàn bộ repository lớn của Supabase về máy chủ, chúng ta chỉ clone thư mục chứa cấu hình Docker chính thức. Thao tác này giúp cấu trúc dự án trên server gọn gàng và tiết kiệm băng thông.

# Clone thư mục docker từ kho lưu trữ chính thức của Supabase
git clone --depth 1 https://github.com/supabase/supabase
cd supabase/docker

# Tạo file cấu hình môi trường từ mẫu
cp .env.example .env

Cảnh báo bảo mật quan trọng: File .env.example đi kèm sẵn các khóa JWT và mật khẩu mặc định công khai trên GitHub. Nếu giữ nguyên các giá trị này trên môi trường Production, bất kỳ ai cũng có thể chiếm toàn quyền kiểm soát hệ quản trị cơ sở dữ liệu PostgreSQL và dữ liệu người dùng. Bạn bắt buộc phải tạo các chuỗi khóa bảo mật mới.

Sử dụng tiện ích openssl trên terminal để sinh các chuỗi bảo mật ngẫu nhiên với độ dài 32 ký tự trở lên:

# Tạo chuỗi bí mật cho JWT Secret
openssl rand -hex 32

# Tạo mật khẩu mạnh cho PostgreSQL root user
openssl rand -base64 24

Mở file .env bằng trình soạn thảo nano .env và thay đổi các thông số then chốt sau:

• POSTGRES_PASSWORD: Thay bằng mật khẩu cơ sở dữ liệu bạn vừa sinh ngẫu nhiên.
• JWT_SECRET: Điền chuỗi JWT Secret mới tạo ở bước trên.
• ANON_KEY & SERVICE_ROLE_KEY: Tạo 2 khóa JWT tương ứng với JWT_SECRET vừa đổi (hoặc sử dụng công cụ jwt.io để ký với payload role anon và service_role).
• DASHBOARD_USERNAME & DASHBOARD_PASSWORD: Thông tin đăng nhập trang quản trị Supabase Studio Dashboard.
• SUPABASE_URL & API_EXTERNAL_URL: Điền tên miền thật sử dụng SSL của bạn (ví dụ: https://api.yourdomain.com).

4. Bước 3: Khởi chạy cụm container Supabase với Docker Compose

Sau khi đã thiết lập an toàn các biến môi trường trong file .env, bạn tiến hành tải các Docker Image chính thức và kích hoạt toàn bộ cụm dịch vụ chạy dưới nền.

# Tải trước các Docker Image mới nhất
docker compose pull

# Khởi động toàn bộ container ở chế độ daemon
docker compose up -d

Kiểm tra danh sách các dịch vụ đang chạy bằng lệnh docker compose ps. Tất cả các container như supabase-db, supabase-kong, supabase-auth, supabase-studio, supabase-storage… phải ở trạng thái Up hoặc healthy.

# Kiểm tra trạng thái hoạt động của các container
docker compose ps

5. Bước 4: Thiết lập Reverse Proxy Nginx, SSL và tường lửa UFW

Trong môi trường Production, không nên mở trực tiếp cổng 8000 (Kong API Gateway) hoặc cổng 3000 (Supabase Studio) ra Internet. Giải pháp tối ưu là sử dụng web server Nginx làm Reverse Proxy tiếp nhận lưu lượng HTTPS và chuyển tiếp nội bộ về các cổng dịch vụ tương ứng.

Cài đặt Nginx và công cụ Certbot trên máy chủ Ubuntu:

# Cài đặt Nginx và Certbot
sudo apt install -y nginx certbot python3-certbot-nginx

Tạo file cấu hình Virtual Host cho Supabase Studio và API tại /etc/nginx/sites-available/supabase.conf:

# Cấu hình cho Supabase Studio Dashboard
server {
    server_name studio.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Cấu hình cho Kong API Gateway
server {
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Kích hoạt file cấu hình và cấp phát chứng chỉ bảo mật HTTPS theo quy trình cài đặt SSL miễn phí qua Let’s Encrypt:

# Kích hoạt cấu hình Nginx
sudo ln -s /etc/nginx/sites-available/supabase.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Đăng ký chứng chỉ SSL tự động với Certbot
sudo certbot --nginx -d studio.yourdomain.com -d api.yourdomain.com

Cuối cùng, tiến hành cấu hình tường lửa UFW để chặn truy cập trực tiếp vào các cổng dịch vụ nội bộ (như PostgreSQL cổng 5432, Kong cổng 8000, Studio cổng 3000), chỉ cho phép lưu lượng truy cập qua SSH, HTTP và HTTPS:

# Thiết lập chính sách mặc định cho tường lửa
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Mở các cổng cần thiết
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Bật tường lửa UFW
sudo ufw enable
sudo ufw status

6. Bước 5: Giám sát, sao lưu cơ sở dữ liệu và nâng cấp hạ tầng

Trong quá trình vận hành, việc giám sát tài nguyên và sao lưu định kỳ là yêu cầu bắt buộc để duy trì tính liên tục của dịch vụ khi bạn tự host Supabase trên Ubuntu Server.

Kiểm tra nhật ký hệ thống (Logs): Khi một dịch vụ gặp sự cố kết nối, bạn có thể kiểm tra trực tiếp log của container tương ứng:

# Xem log thời gian thực của container Database
docker compose logs -f db

# Xem log của API Gateway Kong
docker compose logs -f kong

Sao lưu cơ sở dữ liệu PostgreSQL: Bạn có thể xuất toàn bộ schema và dữ liệu của PostgreSQL bằng lệnh pg_dumpall mà không cần cài thêm client trên máy chủ:

# Tạo file sao lưu SQL nén theo ngày
docker compose exec -T db pg_dumpall -U postgres | gzip > "supabase_backup_$(date +%Y%m%d_%H%M%S).sql.gz"

Khi nào cần nâng cấp từ VPS lên Cloud Server?

Khi cơ sở dữ liệu đạt dung lượng hàng trăm Gigabyte, các truy vấn phức tạp trên pgvector đòi hỏi tốc độ xử lý I/O cao, hoặc số lượng kết nối WebSocket đồng thời qua Realtime vượt quá giới hạn tài nguyên của một máy chủ ảo thông thường, việc chuyển đổi sang hạ tầng Cloud Server chuyên dụng sẽ mang lại khả năng mở rộng tức thì và độ ổn định cao hơn.

7. Câu hỏi thường gặp khi tự host Supabase (FAQ)

Lưu ý: Hướng dẫn này dựa trên tài liệu chính thức từ Supabase. Các cấu hình cổng, biến môi trường và yêu cầu phiên bản Docker có thể thay đổi theo từng bản cập nhật của dự án. Hãy luôn sao lưu dữ liệu trước khi nâng cấp hệ thống production.