thankcard-system/docs/crob-job.md

Hướng dẫn thiết lập Cron Job cho Laravel trên Server (Ubuntu)

Để hệ thống tự động thực hiện các tác vụ định kỳ (bao gồm việc tự động reset thẻ vào lúc 23:59 ngày cuối tháng thông qua lệnh cards:reset), bạn cần cấu hình Cron Job trên hệ điều hành Ubuntu Server.

Dưới đây là hướng dẫn chi tiết cho cả hai trường hợp: Chạy qua Docker Compose (mặc định của dự án) và Chạy trực tiếp trên Host (Không dùng Docker).

---

TRƯỜNG HỢP 1: Chạy qua Docker Compose (Khuyên dùng cho dự án này)

Vì dự án chạy trong container Docker, Cron Job trên server Ubuntu (máy Host) cần gọi lệnh của Laravel vào bên trong container app.

Các bước thiết lập:

1. Mở file cấu hình Crontab của Ubuntu: Mở terminal của Ubuntu Server và chạy lệnh:

   crontab -e
   

2. Thêm cấu hình chạy Laravel Scheduler: Thêm dòng dưới đây vào cuối file crontab:

   * * * * * cd /đường-dẫn-đến-thư-mục-dự-án && docker compose -f docker/docker-compose.yml exec -T app php artisan schedule:run >> /dev/null 2>&1
   

   Lưu ý quan trọng:

   • Thay /đường-dẫn-đến-thư-mục-dự-án thành đường dẫn tuyệt đối đến dự án trên server (Ví dụ: /var/www/thankcard-system).
   • Tham số -T (trong exec -T) là bắt buộc để tắt chế độ TTY (Tương tác nhập liệu), giúp cron chạy ngầm thành công mà không bị lỗi TTY error.

3. Lưu và Thoát:

   • Nếu bạn dùng trình soạn thảo nano: Nhấn Ctrl + O -> nhấn Enter để lưu, sau đó bấm Ctrl + X để thoát.

---

TRƯỜNG HỢP 2: Chạy trực tiếp trên Ubuntu Host (Nếu deploy dạng truyền thống)

Nếu bạn cấu hình chạy PHP và Web Server (Nginx/Apache) trực tiếp trên Ubuntu mà không qua Docker.

Các bước thiết lập:

1. Mở cấu hình Crontab: Truy cập terminal của Ubuntu Server dưới quyền của user chạy Web (thường là www-data hoặc user deploy) và chạy lệnh:

   crontab -e
   

2. Thêm cấu hình chạy Laravel Scheduler: Thêm dòng dưới đây vào cuối file crontab:

   * * * * * cd /đường-dẫn-đến-thư-mục-dự-án && php artisan schedule:run >> /dev/null 2>&1
   

   Lưu ý: Thay /đường-dẫn-đến-thư-mục-dự-án bằng đường dẫn tuyệt đối đến thư mục chứa dự án.

3. Lưu và Thoát.

---

Hướng dẫn kiểm tra trạng thái Cron Job

1. Xem danh sách cron job đang hoạt động:

   crontab -l
   

2. Kiểm tra danh sách các tác vụ đã lên lịch trong Laravel:

   # Nếu dùng Docker:
   docker compose -f docker/docker-compose.yml exec -T app php artisan schedule:list
   
   # Nếu không dùng Docker:
   php artisan schedule:list
   

3. Chạy thử scheduler ngay lập tức bằng tay để kiểm thử:

   # Nếu dùng Docker:
   docker compose -f docker/docker-compose.yml exec -T app php artisan schedule:run
   
   # Nếu không dùng Docker:
   php artisan schedule:run