126 lines
4.1 KiB
Markdown
126 lines
4.1 KiB
Markdown
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
# 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`.
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
php artisan queue:work --sleep=3 --tries=3
|
|
```
|
|
|
|
- Restart all workers gracefully (useful after deployments):
|
|
|
|
```bash
|
|
php artisan queue:restart
|
|
```
|
|
|
|
- Inspect failed jobs:
|
|
|
|
```bash
|
|
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.
|