SkinbaseNova/docs/QUEUE.md

Queue worker setup

This document explains how to run Laravel queue workers for Skinbase and suggested Supervisor / systemd configs included in deploy/.

1. Choose a queue driver

---

Pick a driver in your .env, for example using the database driver (simple to run locally):

QUEUE_CONNECTION=database

Or use Redis for production:

QUEUE_CONNECTION=redis

2. Database queue (if using database driver)

---

Create the jobs table and run migrations:

php artisan queue:table
php artisan migrate

3. Supervisor (recommended for many setups)

---

We provide an example Supervisor config at deploy/supervisor/skinbase-queue.conf.

The example worker listens on the application queues currently used by Skinbase features, including AI and discovery jobs:

forum-security,forum-moderation,vision,recommendations,discovery,mail,default

If you split workloads across dedicated workers, make sure any queues configured through VISION_QUEUE, RECOMMENDATIONS_QUEUE, or DISCOVERY_QUEUE are explicitly covered by at least one worker process.

To use it on a Debian/Ubuntu server:

# copy the file to supervisor's config directory
sudo cp deploy/supervisor/skinbase-queue.conf /etc/supervisor/conf.d/skinbase-queue.conf
# make sure the logs dir exists
sudo mkdir -p /var/log/skinbase
sudo chown www-data:www-data /var/log/skinbase
# tell supervisor to reload configs and start
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start skinbase-queue
# check status
sudo supervisorctl status skinbase-queue

Adjust the command and user in the conf to match your deployment (path to PHP, project root and user).

4. systemd alternative

---

If you prefer systemd, an example unit is at deploy/systemd/skinbase-queue.service.

sudo cp deploy/systemd/skinbase-queue.service /etc/systemd/system/skinbase-queue.service
sudo systemctl daemon-reload
sudo systemctl enable --now skinbase-queue.service
sudo systemctl status skinbase-queue.service

Adjust WorkingDirectory and User in the unit to match your deployment.

5. Helpful artisan commands

---

• Start a one-off worker (foreground):

php artisan queue:work --sleep=3 --tries=3

• Restart all workers gracefully (useful after deployments):

php artisan queue:restart

• Inspect failed jobs:

php artisan queue:failed
php artisan queue:retry {id}
php artisan queue:flush

6. Logging & monitoring

---

• Supervisor example logs to /var/log/skinbase/queue.log (see deploy/supervisor/skinbase-queue.conf).
• Use journalctl -u skinbase-queue for systemd logs.

7. Notes and troubleshooting

---

• Ensure QUEUE_CONNECTION in .env matches the driver you've configured.
• If using database driver, the jobs and failed_jobs tables must exist.
• The mailable used for contact submissions is queued; if the queue worker is not running mails will accumulate in the queue table (or Redis).
• AI auto-tagging, embedding generation, vector index repair, and recommendation cache regeneration are all queued. If you move them onto dedicated queues, the shipped example worker commands must be updated to consume those queue names.

8. AI and discovery queue checklist

---

If you are enabling the recommendation AI stack in production, verify all of the following:

• QUEUE_CONNECTION is backed by a real worker-capable driver such as redis or database
• VISION_QUEUE, RECOMMENDATIONS_QUEUE, and DISCOVERY_QUEUE either stay on default or are present in a worker --queue= list
• UPLOAD_QUEUE_DERIVATIVES=true has workers online before you enable it, otherwise upload post-processing will stall
• php artisan queue:restart is run after deploys so workers pick up new code and config

See docs/recommendation-ai-production.md for a stack-specific runbook.

Questions or prefer a different process manager? Tell me your target host and I can produce exact commands tailored to it.