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.