VeloxFactory processes background work — thumbnail generation, nightly purge routines, print task cleanup — through a Redis-backed queue managed by Laravel Horizon. Horizon runs as a single supervised process and manages its own worker pool internally. It replaces the simple `queue:work` approach with dynamic scaling, real-time monitoring, and a built-in dashboard. ---

Prerequisites

Horizon has two hard requirements beyond the base VeloxFactory stack: a running Redis instance and the `php-redis` PHP extension. Neither is optional — Horizon will refuse to start without both.

Redis

Redis can be installed natively or run as a Docker container. Both work equally well; the choice depends on your infrastructure preferences. **Native installation:** ```bash apt install redis-server systemctl enable redis-server systemctl start redis-server ``` **Docker container:** ```bash docker run -d \ --name redis \ --restart unless-stopped \ -p 127.0.0.1:6379:6379 \ redis:alpine ``` The container binds to `127.0.0.1` only — Redis is not exposed to the network, which is the correct default for a single-server deployment. Whichever method you choose, verify connectivity before proceeding: ```bash redis-cli ping # Expected: PONG ```

PHP Redis Extension

VeloxFactory is configured to use `phpredis` as the Redis client. The extension must be installed and active for PHP: ```bash apt install php-redis systemctl restart php8.2-fpm # adjust version to match your PHP installation ``` Confirm the extension is loaded: ```bash php -m | grep redis # Expected: redis ```

.env Configuration

With Redis running and the extension installed, update your `.env` to activate Redis as the queue driver: ```dotenv QUEUE_CONNECTION=redis REDIS_CLIENT=phpredis REDIS_HOST=127.0.0.1 REDIS_PASSWORD=null REDIS_PORT=6379 ``` ---

Web Server

VeloxFactory requires a web server that routes all requests through Laravel's `public/index.php` entry point. Both Apache2 and nginx are supported. The Horizon dashboard at `/horizon` and the Reverb WebSocket endpoint require no special routing rules — they are handled by Laravel and PHP-FPM like any other request, with one exception: Reverb needs a WebSocket proxy pass.

Apache2

Enable `mod_rewrite` before configuring the vhost: ```bash a2enmod rewrite proxy proxy_http proxy_wstunnel systemctl restart apache2 ``` Virtual host configuration: ```apache ServerName veloxfactory.example.com DocumentRoot /var/www/veloxfactory/public Options -Indexes +FollowSymLinks AllowOverride All Require all granted # Reverb WebSocket proxy ProxyPreserveHost On ProxyPass /app ws://127.0.0.1:8080/app ProxyPassReverse /app ws://127.0.0.1:8080/app ErrorLog ${APACHE_LOG_DIR}/veloxfactory-error.log CustomLog ${APACHE_LOG_DIR}/veloxfactory-access.log combined ``` Laravel's bundled `.htaccess` in `public/` handles the rewrite rules — no additional configuration needed for URL routing.

nginx

```nginx server { listen 80; server_name veloxfactory.example.com; root /var/www/veloxfactory/public; index index.php; # Laravel URL routing location / { try_files $uri $uri/ /index.php?$query_string; } # PHP-FPM location ~ \.php$ { fastcgi_pass unix:/var/run/php/php8.2-fpm.sock; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; include fastcgi_params; fastcgi_read_timeout 120; } # Reverb WebSocket proxy location /app { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; proxy_set_header Host $host; } # Block dotfile access location ~ /\.(?!well-known).* { deny all; } } ```

ℹ️ Adjust the PHP-FPM socket path to match your PHP version. On systems with multiple PHP versions installed, the socket is typically at /var/run/php/php8.2-fpm.sock. Verify with ls /var/run/php/.

---

Queues

VeloxFactory uses two queues with distinct priorities:

Queue	Jobs	Notes
`high`	Thumbnail generation	Dispatched on-demand when a report is rendered. Processed with highest priority — workers on this queue are never blocked by maintenance routines.
`default`	Nightly purge jobs	Scheduled automatically at midnight. Cleans up expired Report History Records, orphaned files, and completed Print Tasks according to the configured retention policies.

ℹ️ The two queues run in separate worker pools. A long-running purge job on the default queue cannot delay thumbnail generation on the high queue — they never compete for the same worker.

---

Horizon Supervisors

Horizon manages workers through internal supervisors — process groups, each responsible for one queue. The system-level Supervisor (Supervisord) only ever manages the single Horizon master process; Horizon itself handles everything below that.

Supervisor	Queue	Balancing	Notes
`supervisor-rendering`	`high`	Auto	Scales worker processes dynamically based on queue depth — up to 10 in production. Job timeout: 120 seconds.
`supervisor-default`	`default`	Simple	Fixed worker count. Runs with lower CPU priority (`nice 10`) — purge jobs are maintenance work and should not compete with rendering for system resources. Job timeout: 300 seconds.

---

System Supervisor Configuration

Supervisord keeps the Horizon master process alive and restarts it automatically on failure. The following blocks replace the previous `queue:work`-based configuration entirely. ```ini ; Horizon — manages all VeloxFactory queue workers internally [program:veloxfactory-horizon] directory=/var/www/veloxfactory command=/usr/bin/php artisan horizon user=www-data process_name=%(program_name)s numprocs=1 autostart=true autorestart=true startretries=10 stopasgroup=true killasgroup=true stopsignal=TERM startsecs=3 stopwaitsecs=600 redirect_stderr=true stdout_logfile=/var/log/supervisor/veloxfactory-horizon.log environment=HOME="/home/www-data",PATH="/usr/local/bin:/usr/bin:/bin" ; Reverb — WebSocket server for real-time events [program:veloxfactory-reverb] directory=/var/www/veloxfactory command=/usr/bin/php artisan reverb:start user=www-data autostart=true autorestart=true startretries=10 stopasgroup=true killasgroup=true stopsignal=INT startsecs=3 stopwaitsecs=60 redirect_stderr=true stdout_logfile=/var/log/supervisor/veloxfactory-reverb.log environment=HOME="/home/www-data",PATH="/usr/local/bin:/usr/bin:/bin" ; Scheduler — runs Laravel's task schedule every minute [program:veloxfactory-schedule] directory=/var/www/veloxfactory command=/usr/bin/php artisan schedule:work user=www-data autostart=true autorestart=true startretries=10 stopasgroup=true killasgroup=true stopsignal=INT startsecs=3 stopwaitsecs=60 redirect_stderr=true stdout_logfile=/var/log/supervisor/veloxfactory-schedule.log environment=HOME="/home/www-data",PATH="/usr/local/bin:/usr/bin:/bin" ```

ℹ️ stopsignal=TERM is required for Horizon. SIGTERM triggers a graceful shutdown — Horizon finishes any in-flight jobs before stopping its workers. Using SIGKILL or SIGINT instead will interrupt running jobs mid-execution and may leave Report History Records in an incomplete state.

After updating the configuration: ```bash supervisorctl reread supervisorctl update supervisorctl status ``` ---

The Dashboard

The Horizon dashboard is available at `/horizon`. It is restricted to users with the `global:admin` permission — the same permission required to manage users and system-wide settings. The dashboard provides a real-time view of the entire queue system: pending and completed jobs, throughput metrics, worker counts per supervisor, and a full log of failed jobs with their stack traces. Failed jobs can be retried directly from the dashboard without any CLI access. ---

Graceful Shutdown & Deployments

When Horizon is stopped — for deployments, configuration changes, or server maintenance — it finishes any jobs currently in flight before exiting. The Supervisord configuration allows up to 600 seconds for this drain, which comfortably covers the longest expected job timeouts. ```bash # Stop Horizon gracefully (in-flight jobs will finish first) supervisorctl stop veloxfactory-horizon # Restart after a deployment supervisorctl restart veloxfactory-horizon ``` Never force-kill the Horizon process during a deployment. Always use `supervisorctl stop` or `supervisorctl restart` — both send SIGTERM and wait for the drain period.