Eko Sudarmaji

Laravel Queue Worker di Ubuntu dengan Supervisor

Pada artikel sebelumnya kita sudah membahas cara menggunakan Laravel Queue dengan Redis untuk menjalankan background job.

Saat development, menjalankan queue worker cukup dengan:

php artisan queue:work

Masalahnya, command tersebut akan berhenti ketika terminal ditutup atau proses worker mengalami crash.

Untuk aplikasi production, kita membutuhkan cara agar queue worker dapat tetap berjalan secara otomatis dan kembali dijalankan jika terjadi masalah.

Salah satu solusi yang umum digunakan di Ubuntu adalah Supervisor.

Apa Itu Supervisor?

Supervisor adalah process control system yang dapat digunakan untuk memantau dan mengelola proses yang berjalan di server.

Dalam kasus Laravel Queue, Supervisor dapat digunakan untuk:

  • Menjalankan queue worker secara otomatis
  • Menjaga worker tetap berjalan
  • Menjalankan kembali worker ketika berhenti
  • Menjalankan beberapa worker sekaligus
  • Mengelola proses background di server

Arsitekturnya menjadi:

Laravel
   ↓
Redis
   ↓
Queue Worker
   ↑
Supervisor

Supervisor bertugas memastikan proses php artisan queue:work tetap berjalan.

Persiapan

Contoh pada artikel ini menggunakan:

  • Ubuntu
  • Laravel
  • PHP
  • Redis
  • Composer
  • Supervisor

Pastikan aplikasi Laravel dan Redis sudah berjalan dengan baik.

Untuk memastikan Redis aktif:

redis-cli ping

Jika berhasil, hasilnya:

PONG

Jika Anda belum menginstall Redis, lihat artikel:

Cara Install Redis di Ubuntu untuk Laravel

Sedangkan untuk memahami konfigurasi queue dengan Redis, lihat:

Laravel Queue dengan Redis: Panduan Background Job untuk Pemula

Install Supervisor di Ubuntu

Install Supervisor menggunakan apt:

sudo apt update

Kemudian:

sudo apt install supervisor

Setelah proses instalasi selesai, pastikan service Supervisor berjalan:

sudo systemctl status supervisor

Jika belum aktif, jalankan:

sudo systemctl enable --now supervisor

Dengan enable, Supervisor akan otomatis dijalankan ketika server melakukan boot.

Membuat Konfigurasi Queue Worker

Konfigurasi Supervisor biasanya disimpan di:

/etc/supervisor/conf.d/

Buat file konfigurasi baru:

sudo nano /etc/supervisor/conf.d/laravel-worker.conf

Kemudian isi:

[program:laravel-worker]

process_name=%(program_name)s_%(process_num)02d

command=php /var/www/example.com/artisan queue:work redis --sleep=3 --tries=3 --timeout=90

autostart=true
autorestart=true

stopasgroup=true
killasgroup=true

numprocs=1

redirect_stderr=true

stdout_logfile=/var/www/example.com/storage/logs/worker.log

stopwaitsecs=3600

Sesuaikan:

/var/www/example.com

dengan lokasi project Laravel Anda.

Misalnya project berada di:

/var/www/sites/example.com

maka command menjadi:

command=php /var/www/sites/example.com/artisan queue:work redis --sleep=3 --tries=3 --timeout=90

Begitu juga dengan lokasi log:

stdout_logfile=/var/www/sites/example.com/storage/logs/worker.log

Menentukan User

Queue worker sebaiknya dijalankan menggunakan user yang memiliki permission sesuai terhadap aplikasi Laravel.

Misalnya aplikasi dijalankan menggunakan user www-data, konfigurasi dapat menggunakan:

user=www-data

Contohnya:

[program:laravel-worker]

process_name=%(program_name)s_%(process_num)02d

command=php /var/www/example.com/artisan queue:work redis --sleep=3 --tries=3 --timeout=90

user=www-data

autostart=true
autorestart=true

stopasgroup=true
killasgroup=true

numprocs=1

redirect_stderr=true

stdout_logfile=/var/www/example.com/storage/logs/worker.log

stopwaitsecs=3600

Pastikan user tersebut memiliki permission yang sesuai terhadap project Laravel, terutama directory storage.

Memuat Konfigurasi Supervisor

Setelah konfigurasi selesai, jalankan:

sudo supervisorctl reread

Jika konfigurasi terdeteksi, biasanya akan muncul:

laravel-worker: available

Kemudian:

sudo supervisorctl update

Supervisor akan membuat dan menjalankan program berdasarkan konfigurasi tersebut.

Menjalankan Queue Worker

Untuk memastikan worker berjalan:

sudo supervisorctl status

Contohnya:

laravel-worker:laravel-worker_00   RUNNING   pid 12345, uptime 0:00:10

Status RUNNING menunjukkan bahwa queue worker sedang berjalan.

Kita juga dapat menjalankannya secara manual:

sudo supervisorctl start laravel-worker:*

Untuk menghentikan:

sudo supervisorctl stop laravel-worker:*

Menggunakan Beberapa Worker

Salah satu keuntungan Supervisor adalah kita dapat menjalankan beberapa worker secara bersamaan.

Misalnya:

numprocs=3

Supervisor kemudian akan menjalankan:

laravel-worker_00
laravel-worker_01
laravel-worker_02

Ketiga worker tersebut dapat mengambil job dari Redis secara bersamaan.

Ini berguna ketika aplikasi memiliki banyak pekerjaan yang harus diproses.

Namun, jangan langsung menggunakan banyak worker tanpa memperhatikan kapasitas server. Jumlah worker harus disesuaikan dengan CPU, memory, dan karakteristik pekerjaan yang dijalankan.

Memantau Queue Worker

Untuk melihat status worker:

sudo supervisorctl status

Untuk melihat log worker:

tail -f /var/www/example.com/storage/logs/worker.log

Jika aplikasi menggunakan Laravel log, error aplikasi juga dapat diperiksa melalui:

storage/logs/laravel.log

Dengan melihat log, kita dapat mengetahui apakah job berhasil diproses atau mengalami error.

Setelah Mengubah Kode Laravel

Queue worker merupakan proses yang berjalan terus-menerus.

Artinya, ketika Anda melakukan perubahan pada kode Job, worker yang sedang berjalan belum tentu langsung menggunakan kode terbaru.

Karena itu, setelah melakukan deployment, worker sebaiknya di-restart dengan:

php artisan queue:restart

Command tersebut meminta worker Laravel untuk menyelesaikan job yang sedang dikerjakan kemudian berhenti.

Supervisor akan melihat bahwa proses worker berhenti dan menjalankannya kembali.

Alurnya:

Deploy kode baru
      ↓
php artisan queue:restart
      ↓
Worker selesai
      ↓
Worker berhenti
      ↓
Supervisor mendeteksi
      ↓
Worker dijalankan kembali

Ini merupakan salah satu alasan Supervisor sangat berguna untuk production.

Troubleshooting

Jika worker tidak berjalan, periksa status Supervisor:

sudo supervisorctl status

Kemudian periksa log:

tail -f /var/www/example.com/storage/logs/worker.log

Periksa juga apakah Laravel dapat menjalankan queue worker secara manual:

cd /var/www/example.com

php artisan queue:work redis

Jika command tersebut menghasilkan error, kemungkinan masalahnya bukan pada Supervisor, tetapi pada konfigurasi Laravel, PHP, Redis, permission, atau dependency aplikasi.

Anda juga dapat memastikan Redis masih berjalan:

redis-cli ping

Hasil yang diharapkan:

PONG

Kesimpulan

Menjalankan:

php artisan queue:work

cukup untuk development, tetapi production membutuhkan process manager agar worker tetap berjalan.

Dengan Supervisor, arsitektur Laravel Queue menjadi:

                Laravel
                   │
                   ↓
                 Redis
                   │
                   ↓
             Queue Worker
                   ↑
                   │
              Supervisor

Supervisor memastikan queue worker otomatis dijalankan dan dapat dimulai kembali ketika proses berhenti.

Untuk aplikasi Laravel yang menggunakan Redis sebagai queue driver, kombinasi Redis + Queue Worker + Supervisor merupakan setup yang sederhana dan cukup umum untuk menjalankan background job di server Ubuntu.