Hướng dẫn cài đặt Trigger.dev bằng Docker Compose trên Ubuntu

Trong thế giới phát triển phần mềm hiện đại, việc xử lý các tác vụ nền (background jobs) là một yêu cầu gần như không thể thiếu. Từ việc gửi email xác nhận, xử lý video, tạo báo cáo định kỳ, cho đến đồng bộ hóa dữ liệu với các dịch vụ bên thứ ba, các tác vụ này cần được thực thi một cách đáng tin cậy mà không làm ảnh hưởng đến trải nghiệm người dùng trên giao diện chính.

Trigger.dev là một framework mã nguồn mở được thiết kế đặc biệt để giải quyết bài toán này, với trọng tâm là trải nghiệm của lập trình viên (Developer Experience – DX). Nó cung cấp một giải pháp toàn diện để tạo, quản lý và giám sát các tác vụ nền một cách đơn giản và hiệu quả. Nền tảng này có thể được xem như một sự thay thế hiện đại và dễ tiếp cận hơn so với các hệ thống phức tạp như Celery hay BullMQ.

Các tính năng cốt lõi của Trigger.dev bao gồm:

• Tác vụ chạy dài (Long-running jobs): Khả năng thực thi các công việc kéo dài hàng giờ hoặc thậm chí hàng ngày mà không bị gián đoạn.
• Tác vụ định kỳ (Scheduled jobs): Dễ dàng thiết lập các công việc lặp lại theo lịch trình (cron-based) để tự động hóa các quy trình như gửi báo cáo hàng tuần hoặc dọn dẹp dữ liệu hàng tháng.
• Kích hoạt qua API (API endpoint triggers): Mỗi tác vụ có thể được kích hoạt thông qua một endpoint API duy nhất, cho phép tích hợp linh hoạt với bất kỳ ứng dụng hoặc dịch vụ nào.
• Giao diện giám sát tích hợp: Cung cấp một dashboard trực quan để theo dõi trạng thái, xem lại lịch sử thực thi, kiểm tra logs và quản lý các tác vụ một cách tập trung.
• Tích hợp sẵn (First-party integrations): Hỗ trợ tích hợp nhanh chóng với các dịch vụ phổ biến như Slack, SendGrid, Resend, giúp giảm thiểu thời gian và công sức viết mã kết nối.

Lợi ích của việc tự host (self-hosting) Trigger.dev

Việc lựa chọn tự host một nền tảng như Trigger.dev không chỉ là một quyết định kỹ thuật mà còn là một lựa chọn chiến lược, phù hợp với các nguyên tắc DevOps hiện đại về quyền sở hữu, kiểm soát và tự động hóa. Trong khi phiên bản cloud (SaaS) mang lại sự tiện lợi, việc tự host trên hạ tầng của riêng mình mang lại những lợi ích vượt trội:

• Toàn quyền kiểm soát dữ liệu (Data Sovereignty): Đây là lợi ích quan trọng nhất. Khi tự host, toàn bộ dữ liệu liên quan đến tác vụ—bao gồm payload, logs, và các thông tin nhạy cảm—đều nằm hoàn toàn trong hạ tầng của bạn. Điều này cực kỳ quan trọng đối với các tổ chức có yêu cầu nghiêm ngặt về bảo mật và tuân thủ các quy định như GDPR hay HIPAA.
• Chi phí hiệu quả ở quy mô lớn (Cost-Effectiveness at Scale): Các nền tảng SaaS thường tính phí dựa trên số lượng tác vụ thực thi, số lượng người dùng, hoặc các giới hạn khác. Mô hình này có thể trở nên rất tốn kém khi quy mô sử dụng tăng lên. Với việc tự host, bạn chỉ phải trả chi phí cho máy chủ và bảo trì, giúp tối ưu hóa chi phí vận hành trong dài hạn.
• Tùy biến và Mở rộng không giới hạn (Unlimited Customization and Extensibility): Vì Trigger.dev là mã nguồn mở, bạn có toàn quyền truy cập vào mã nguồn. Điều này cho phép tùy chỉnh sâu, sửa đổi các tính năng để phù hợp với quy trình làm việc đặc thù, và quan trọng nhất là tích hợp với các hệ thống nội bộ, độc quyền mà một nhà cung cấp SaaS không thể hỗ trợ.

Tổng quan kiến trúc triển khai với Docker Compose

Sử dụng Docker Compose là phương pháp được khuyến nghị để triển khai Trigger.dev một cách nhanh chóng và nhất quán. Kiến trúc này bao gồm nhiều container được quản lý và kết nối với nhau một cách tự động.

Mô hình triển khai cơ bản bao gồm các thành phần sau:

• App Service: Đây là container chính, chạy ứng dụng Next.js, có nhiệm vụ cung cấp giao diện người dùng (UI dashboard) và các API endpoint để quản lý và kích hoạt tác vụ.
• Worker Service: Container này chịu trách nhiệm thực thi các tác vụ nền. Nó lắng nghe hàng đợi công việc và xử lý chúng một cách độc lập với App Service.
• Database Service (PostgreSQL): Một container chạy cơ sở dữ liệu PostgreSQL, đóng vai trò là nơi lưu trữ bền vững cho mọi dữ liệu của hệ thống, bao gồm thông tin về jobs, projects, logs, và các cấu hình.
• Docker Network: Docker Compose tự động tạo ra một mạng ảo riêng biệt, cho phép các container (App, Worker, DB) giao tiếp với nhau một cách an toàn và cô lập với môi trường bên ngoài.
• Docker Volumes: Để đảm bảo dữ liệu không bị mất khi container cơ sở dữ liệu được khởi động lại hoặc xóa đi, chúng ta sử dụng volumes để ánh xạ thư mục dữ liệu của PostgreSQL ra máy chủ host.

Chuẩn bị môi trường cài đặt

Trước khi tiến hành cài đặt, việc chuẩn bị một môi trường sạch và đúng chuẩn là yếu tố then chốt để đảm bảo hệ thống hoạt động ổn định và an toàn.

Yêu cầu hệ thống

Để triển khai Trigger.dev cho môi trường production, một máy chủ ảo (VPS) hoặc máy chủ vật lý với cấu hình tối thiểu sau đây được khuyến nghị:

• Hệ điều hành: Ubuntu 22.04 LTS (hoặc mới hơn). Việc chọn phiên bản LTS (Long Term Support) đảm bảo bạn nhận được các bản vá bảo mật và hỗ trợ ổn định trong thời gian dài.
• CPU: Tối thiểu 4 vCPU.
• RAM: Tối thiểu 8 GB. Mức RAM này đủ để hệ điều hành, Docker, container PostgreSQL và các tiến trình Node.js của app và worker hoạt động thoải mái mà không cần dùng đến swap, vốn có thể làm giảm hiệu năng nghiêm trọng.
• Ổ cứng: Tối thiểu 40 GB SSD. Sử dụng ổ cứng SSD sẽ cải thiện đáng kể tốc độ đọc/ghi của cơ sở dữ liệu và hiệu năng chung của ứng dụng.

Cài đặt Docker Engine

Thực hiện các lệnh sau theo thứ tự để cài đặt phiên bản Docker Engine mới nhất từ kho lưu trữ chính thức của Docker.

1. Cập nhật danh sách gói của apt và cài đặt các gói cần thiết:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

2. 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

3. Thiết lập kho lưu trữ của Docker:

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

4. Cài đặt Docker Engine:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin

5. Xác minh cài đặt thành công bằng cách chạy container hello-world:

sudo docker run hello-world

6. Bước hậu cài đặt (quan trọng): Thêm người dùng hiện tại vào nhóm docker để có thể chạy các lệnh Docker mà không cần sudo. Đây không chỉ là một sự tiện lợi, mà còn là một bước cải thiện quy trình làm việc và bảo mật. Việc liên tục sử dụng sudo sẽ trao quyền root cho toàn bộ tiến trình Docker, trong khi việc thêm người dùng vào nhóm docker chỉ cấp quyền tương tác với Docker daemon, tuân thủ nguyên tắc đặc quyền tối thiểu.

sudo usermod -aG docker $USER

Lưu ý: Bạn cần đăng xuất và đăng nhập lại để thay đổi này có hiệu lực.

Cài đặt Docker Compose

Với các phiên bản Docker mới, Docker Compose được tích hợp dưới dạng một plugin.

1. Cài đặt plugin Docker Compose:

sudo apt-get install -y docker-compose-plugin

2. Kiểm tra phiên bản để xác nhận cài đặt:

docker compose version

Cấu trúc thư mục dự án

Việc tổ chức các tệp dự án một cách khoa học sẽ giúp việc quản lý, sao lưu và kiểm soát phiên bản trở nên dễ dàng hơn. Cấu trúc sau đây được khuyến nghị:

1. Tạo thư mục chính cho dự án. Việc đặt các phần mềm của bên thứ ba trong /opt là một quy ước phổ biến trên Linux.

sudo mkdir -p /opt/trigger.dev
sudo chown $USER:$USER /opt/trigger.dev
cd /opt/trigger.dev

2. Tạo cấu trúc thư mục con:

/opt/trigger.dev/
├── docker-compose.yml  # Tệp cấu hình các dịch vụ
├──.env                 # Tệp chứa các biến môi trường và khóa bí mật
└── data/               # Thư mục chứa dữ liệu bền vững
    └── postgres/

Tách biệt tệp cấu hình (docker-compose.yml, .env) khỏi dữ liệu (data/) giúp bạn dễ dàng đưa các tệp cấu hình vào hệ thống quản lý phiên bản (như Git) mà không làm lộ dữ liệu nhạy cảm.

Cấu hình và triển khai Trigger.dev với Docker Compose

Đây là phần cốt lõi của quá trình cài đặt, nơi chúng ta sẽ định nghĩa, cấu hình và khởi chạy toàn bộ hệ thống.

Phân tích chi tiết tệp docker-compose.yml

Tạo một tệp có tên docker-compose.yml trong thư mục /opt/trigger.dev với nội dung sau. Mỗi dòng cấu hình đều có mục đích rõ ràng để đảm bảo hệ thống hoạt động ổn định và an toàn.

# /opt/trigger.dev/docker-compose.yml

services:
  # Dịch vụ cơ sở dữ liệu PostgreSQL
  db:
    image: postgres:15
    container_name: trigger_db
    restart: always
    environment:
      # Các biến này được lấy từ tệp.env để thiết lập CSDL
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      # Ánh xạ dữ liệu CSDL ra thư mục trên host để đảm bảo tính bền vững
      -./data/postgres:/var/lib/postgresql/data
    ports:
      # Chỉ mở port CSDL cho máy chủ host, không public ra ngoài
      - "127.0.0.1:5432:5432"
    healthcheck:
      test:
      interval: 10s
      timeout: 5s
      retries: 5

  # Dịch vụ chính của Trigger.dev (UI và API)
  app:
    image: triggerdotdev/trigger.dev:latest
    container_name: trigger_app
    restart: always
    depends_on:
      db:
        condition: service_healthy # Đảm bảo CSDL đã sẵn sàng trước khi khởi chạy app
    ports:
      # Mở port 3000 để truy cập giao diện web
      - "3000:3000"
    environment:
      # Tải toàn bộ cấu hình từ tệp.env
      - NODE_ENV=production
      - DATABASE_URL=${DATABASE_URL}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - SECRET_KEY=${SECRET_KEY}
      - APP_ORIGIN=${APP_ORIGIN}
      - TRIGGER_API_URL=${TRIGGER_API_URL}
      - PORT=${PORT}

  # Dịch vụ thực thi các tác vụ nền
  worker:
    image: triggerdotdev/trigger.dev:latest
    container_name: trigger_worker
    restart: always
    depends_on:
      db:
        condition: service_healthy # Đảm bảo CSDL đã sẵn sàng
    command: ["pnpm", "nx", "run", "apps-v3:worker"] # Ghi đè lệnh mặc định để chạy worker
    environment:
      # Worker cũng cần các biến môi trường tương tự để kết nối và hoạt động
      - NODE_ENV=production
      - DATABASE_URL=${DATABASE_URL}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - SECRET_KEY=${SECRET_KEY}
      - APP_ORIGIN=${APP_ORIGIN}
      - TRIGGER_API_URL=${TRIGGER_API_URL}

volumes:
  data:

Kiến trúc này thể hiện một điểm rất mạnh của containerization. Việc tách app và worker thành hai dịch vụ riêng biệt dù sử dụng chung một Docker image là một quyết định thiết kế thông minh. Nhu cầu tài nguyên của một máy chủ web (xử lý request HTTP) khác với một worker (thường cần nhiều CPU/RAM cho các tác vụ nặng). Thiết kế này cho phép chúng ta mở rộng quy mô một cách độc lập. Nếu việc xử lý tác vụ trở thành nút thắt cổ chai, bạn có thể dễ dàng tăng số lượng container worker (docker compose up -d --scale worker=5) mà không cần phải triển khai thêm các container app, giúp tiết kiệm chi phí và tài nguyên một cách hiệu quả.

Tạo và cấu hình tệp biến môi trường .env

Bảo mật là ưu tiên hàng đầu. Không bao giờ lưu trữ các thông tin nhạy cảm như mật khẩu hay khóa bí mật trực tiếp trong tệp docker-compose.yml. Thay vào đó, chúng ta sẽ sử dụng tệp .env.

1. Tạo tệp .env trong thư mục /opt/trigger.dev:

touch .env

2. Mở tệp .env và điền vào các giá trị. Đối với các khóa bí mật, hãy sử dụng lệnh openssl rand -base64 32 để tạo ra các chuỗi ngẫu nhiên, an toàn về mặt mật mã.Nội dung mẫu cho tệp .env:

# /opt/trigger.dev/.env

# Cấu hình PostgreSQL
POSTGRES_USER=trigger
POSTGRES_PASSWORD=your_very_strong_and_secret_password # <-- THAY BẰNG MẬT KHẨU MẠNH CỦA BẠN
POSTGRES_DB=trigger

# Cấu hình kết nối CSDL cho Trigger.dev
# Định dạng: postgresql://<user>:<password>@<service_name>:<port>/<db_name>
DATABASE_URL=postgresql://trigger:your_very_strong_and_secret_password@db:5432/trigger

# Các khóa bí mật (SỬ DỤNG LỆNH openssl rand -base64 32 ĐỂ TẠO)
ENCRYPTION_KEY= # <-- Dán khóa được tạo từ openssl vào đây
SECRET_KEY= # <-- Dán một khóa khác được tạo từ openssl vào đây

# Cấu hình URL
# URL của ứng dụng sẽ kết nối đến Trigger.dev (ví dụ: trang web Next.js của bạn)
APP_ORIGIN=http://localhost:3001
# URL công khai của chính instance Trigger.dev này. Thay your_server_ip bằng IP máy chủ của bạn.
TRIGGER_API_URL=http://<your_server_ip>:3000

# Port cho dịch vụ App
PORT=3000

Bảng dưới đây tóm tắt vai trò của từng biến môi trường, giúp bạn cấu hình chính xác và giảm thiểu lỗi.

Khởi chạy và kiểm tra hệ thống

Sau khi đã chuẩn bị xong các tệp cấu hình, hãy khởi chạy toàn bộ hệ thống.

1. Từ thư mục /opt/trigger.dev, chạy lệnh sau để khởi tạo và chạy các container ở chế độ nền (detached mode):

docker compose up -d

2. Kiểm tra trạng thái của các container:

docker compose up -d

Một kết quả tốt sẽ hiển thị tất cả các container (trigger_db, trigger_app, trigger_worker) với trạng thái running hoặc healthy.

3. Để xem logs của một dịch vụ cụ thể (ví dụ: app) nếu có sự cố:

docker compose logs -f app

Nhấn Ctrl+C để thoát khỏi chế độ xem logs.

Các bước sau cài đặt và xác minh

Khi các container đã chạy ổn định, bạn có thể bắt đầu sử dụng Trigger.dev.

Truy cập giao diện người dùng (UI)

Mở trình duyệt web và truy cập vào địa chỉ http://<your_server_ip>:3000, thay <your_server_ip> bằng địa chỉ IP của máy chủ Ubuntu của bạn. Bạn sẽ thấy màn hình chào mừng và thiết lập ban đầu của Trigger.dev.

Tạo Organization và Project đầu tiên

Giao diện sẽ hướng dẫn bạn qua các bước đầu tiên:

1. Tạo tài khoản quản trị: Điền email và mật khẩu để tạo người dùng đầu tiên.
2. Tạo Organization: Đặt tên cho tổ chức của bạn. Một tổ chức có thể chứa nhiều dự án.
3. Tạo Project: Đặt tên cho dự án đầu tiên của bạn. Mỗi dự án sẽ có một môi trường riêng biệt cho các tác vụ và API keys.

Lấy API Key và Endpoint URL

Sau khi tạo project, bạn sẽ được chuyển đến trang tổng quan của project đó. Đây là nơi bạn sẽ tìm thấy hai thông tin quan trọng nhất để kết nối các ứng dụng của mình với instance Trigger.dev vừa cài đặt:

• API Key: Một chuỗi ký tự dài dùng để xác thực các yêu cầu từ client của bạn.
• Endpoint URL: Địa chỉ mà client của Trigger.dev sẽ gửi yêu cầu đến.

Hãy sao chép và lưu trữ hai giá trị này một cách an toàn. Chúng sẽ được sử dụng trong mã nguồn ứng dụng của bạn khi bạn định nghĩa và kích hoạt các tác vụ.

Xử lý sự cố thường gặp

Việc xử lý sự cố trong môi trường container hóa tuân theo một quy trình chẩn đoán logic. Hướng dẫn này không chỉ giải quyết các vấn đề cụ thể của Trigger.dev mà còn trang bị cho bạn một phương pháp luận chung để xử lý bất kỳ ứng dụng nào chạy trên Docker Compose.

Lỗi Container liên tục khởi động lại (Restarting Loop)

• Triệu chứng: Khi chạy docker compose ps, bạn thấy một hoặc nhiều container có trạng thái Restarting.
• Nguyên nhân: Đây thường là dấu hiệu của lỗi cấu hình. Nguyên nhân phổ biến nhất là sai chuỗi kết nối DATABASE_URL trong tệp .env, hoặc lỗi trong quá trình khởi tạo (migration) cơ sở dữ liệu ban đầu.
• Giải pháp:
  1. Kiểm tra trạng thái để xác định container nào đang gặp sự cố: docker compose ps
  2. Đọc logs của container đó để tìm thông báo lỗi cụ thể: docker compose logs <tên_service>, ví dụ: docker compose logs app
  3. Dựa vào thông báo lỗi, kiểm tra và sửa lại các biến trong tệp .env.
  4. Sau khi sửa, khởi động lại hệ thống: docker compose up -d

Lỗi “Permission Denied” với Docker Volumes

• Triệu chứng: Logs của container db hiển thị các lỗi liên quan đến quyền truy cập tệp trong thư mục /var/lib/postgresql/data.
• Nguyên nhân: Sự không khớp giữa User ID (UID) của người dùng postgres bên trong container (mặc định là 999 trong image chính thức) và quyền sở hữu của thư mục ./data/postgres trên máy chủ host.
• Giải pháp: Thay đổi quyền sở hữu của thư mục trên máy chủ host để khớp với UID trong container: sudo chown -R 999:999./data/postgres

Lỗi Giao diện không thể kết nối đến Worker

• Triệu chứng: Giao diện người dùng hiển thị cảnh báo không thể kết nối đến worker, hoặc các tác vụ được kích hoạt nhưng không được xử lý (trạng thái PENDING).
• Nguyên nhân: Container worker có thể đã bị lỗi và dừng lại, hoặc có vấn đề về mạng giữa các container.
• Giải pháp:
  1. Kiểm tra logs của worker để tìm nguyên nhân: docker compose logs worker.
  2. Đảm bảo tất cả các container đều nằm trên cùng một mạng Docker được định nghĩa trong docker-compose.yml.
  3. Kiểm tra lại các biến môi trường trong .env vì worker cũng cần chúng để kết nối đến cơ sở dữ liệu.

Các bước nâng cao cho môi trường Production

Bằng cách làm theo hướng dẫn này, bạn đã triển khai thành công một instance Trigger.dev hoàn chỉnh, tự chủ và sẵn sàng hoạt động trên nền tảng Ubuntu với Docker Compose. Bạn đã nắm trong tay một công cụ mạnh mẽ để tự động hóa các tác vụ nền, với toàn quyền kiểm soát dữ liệu và chi phí.

Các bước tiếp theo (Nâng cao)

Một hệ thống hoạt động không đồng nghĩa với một hệ thống sẵn sàng cho môi trường production. Việc chạy một dịch vụ trên IP và port mà không có HTTPS là không an toàn và thiếu chuyên nghiệp. Dữ liệu bị mất do sự cố máy chủ có thể là một thảm họa. Do đó, các bước sau đây không phải là tùy chọn “có thì tốt” mà là những yêu cầu thiết yếu cho bất kỳ hệ thống nghiêm túc nào.

• Sử dụng Reverse Proxy (Nginx/Caddy): Thiết lập một reverse proxy đứng trước Trigger.dev là bước quan trọng nhất. Nó mang lại các lợi ích sống còn:
  • Bảo mật với SSL/TLS: Mã hóa toàn bộ lưu lượng truy cập bằng HTTPS, bảo vệ dữ liệu trên đường truyền. Đây là yêu cầu không thể thiếu cho production.
  • Tên miền tùy chỉnh: Cho phép truy cập dịch vụ qua một tên miền thân thiện (ví dụ: trigger.your-domain.com) thay vì địa chỉ IP và port.
  • Cân bằng tải (Tương lai): Reverse proxy là điểm khởi đầu để có thể mở rộng hệ thống bằng cách chạy nhiều instance app và phân phối tải giữa chúng.
• Chiến lược Sao lưu (Backup Strategy): Dữ liệu là tài sản quý giá nhất. Bạn phải có một kế hoạch sao lưu định kỳ cho volume dữ liệu của PostgreSQL.
  • Mục tiêu: Sao lưu thư mục ./data/postgres trên máy chủ host.
  • Phương pháp: Sử dụng cron để tự động nén thư mục này thành một tệp .tar.gz hàng đêm và lưu trữ ở một nơi an toàn (ví dụ: một máy chủ khác hoặc dịch vụ lưu trữ đám mây).
  • Lệnh mẫu cho cron job: tar -czf /path/to/backups/trigger_db_$(date +\%Y\%m\%d).tar.gz /opt/trigger.dev/data/postgres
• Giám sát và Cảnh báo (Monitoring and Alerting): Trong môi trường production, bạn cần biết hệ thống của mình có đang hoạt động tốt hay không. Thiết lập các công cụ giám sát để theo dõi sức khỏe của các container, mức sử dụng CPU, RAM và dung lượng ổ cứng. Các công cụ mã nguồn mở như Prometheus kết hợp với Grafana, hoặc các dịch vụ thương mại, có thể giúp bạn phát hiện sớm các vấn đề và gửi cảnh báo trước khi chúng ảnh hưởng đến người dùng.