Queues & background jobs

Background work in Inventorix — including asset imports and exports, warranty-expiry digest emails, and applying runtime settings to long-lived workers — runs on queues. Laravel Horizon manages the queue workers and provides a real-time dashboard.

Queue backend

Inventorix uses Redis as the queue backend for Horizon. The default queue connection is set by the QUEUE_CONNECTION environment variable.

Variable	Default	Purpose
QUEUE_CONNECTION	database	Set to redis to use Horizon
REDIS_HOST	127.0.0.1	Redis server host
REDIS_PORT	6379	Redis server port
REDIS_PASSWORD	(null)	Redis password (leave null if not set)
REDIS_CLIENT	phpredis	PHP Redis client (phpredis or predis)

Redis required for Horizon

Laravel Horizon only works with the redis queue connection. Set QUEUE_CONNECTION=redis and ensure a Redis server is reachable before starting Horizon. The development default of database queues jobs to a database table and processes them asynchronously via php artisan queue:work; it cannot use Horizon (Horizon is Redis-only).

Laravel Horizon

Horizon is the worker process that picks up queued jobs. It is not started automatically by the Docker entrypoint — you must run it as a separate process or container.

Starting Horizon

php artisan horizon

In a Docker Compose setup, define a dedicated worker service:

worker:
  image: your-inventorix-image
  command: php artisan horizon
  depends_on:
    - redis
  environment:
    QUEUE_CONNECTION: redis
    REDIS_HOST: redis

To stop Horizon gracefully (allowing in-flight jobs to complete before exiting):

php artisan horizon:terminate

Horizon dashboard

The dashboard is available at /horizon (e.g. https://your-domain.com/horizon). It shows queued, processing, completed, and failed jobs, along with throughput metrics.

Dashboard access — tighten before production

The current HorizonServiceProvider gate (viewHorizon) grants access to any authenticated user. Before going to production, restrict the gate to administrators only. For example, in app/Providers/HorizonServiceProvider.php:

Gate::define('viewHorizon', function ($user) {
    return $user->is_admin; // or whatever admin check your app uses
});

Supervisors and queues

Horizon’s worker configuration is defined in config/horizon.php. The default supervisor processes the default queue:

Setting	Value	Purpose
Connection	redis	Queue connection
Queue	default	Queue name
Balance	auto	Auto-scales workers
Auto-scaling strategy	time	Scales based on queue wait time
Max processes (production)	10	Maximum concurrent workers
Max processes (local)	3	Maximum concurrent workers in development
Memory limit per worker	128 MB	Worker restart threshold
Job timeout	60 s	Per-job execution time limit
Job retries	1	How many times a job is attempted before failing

The master supervisor has a separate memory limit of 64 MB. If exceeded, Horizon restarts automatically.

Job retention

Category	Retention
Recent / pending / completed jobs	60 minutes
Failed jobs	7 days (10 080 minutes)

Troubleshooting stuck jobs

Jobs not processing

1. Verify Horizon is running: php artisan horizon:status
2. Check that QUEUE_CONNECTION=redis in the environment where Horizon runs.
3. Confirm Redis is reachable: redis-cli -h $REDIS_HOST ping

Jobs stuck in pending

If a job has been pending longer than the retry_after threshold (default 90 seconds for the Redis connection), Horizon will re-queue it. If jobs permanently pile up, check worker logs (storage/logs/laravel.log) for exceptions.

Retrying failed jobs

# List failed jobs
php artisan queue:failed

# Retry a single failed job by ID
php artisan queue:retry <id>

# Retry all failed jobs
php artisan queue:retry all

Flushing failed jobs

php artisan queue:flush

Horizon memory issues

If Horizon restarts frequently due to memory, increase the memory_limit value in config/horizon.php and the per-worker memory value in the supervisor definition.