Download the PHP package fof/horizon without Composer

Horizon - Advanced Queue Dashboard & Management

A comprehensive queue management solution for Flarum, powered by Laravel Horizon. This extension provides a beautiful dashboard for monitoring your Redis queues, along with powerful worker management and scaling capabilities.

Features

• 📊 Real-time Dashboard - Beautiful web interface at /admin/horizon
• 🔄 Auto-scaling Workers - Dynamically scale workers based on queue load
• ⚖️ Load Balancing - Multiple balancing strategies (simple, auto, false)
• 📈 Metrics & Insights - Job throughput, wait times, and failure rates
• 🎯 Job Monitoring - Track specific jobs and tags
• 🔍 Failed Job Management - Retry, inspect, and clear failed jobs
• 🚦 Supervisor Control - Pause, continue, and terminate workers
• 📦 Batch Job Support - Monitor and manage job batches

Requirements

• Flarum 2.0+
• Redis Server (required for Horizon to function)
• PHP 8.2+

Installation

Step 1: Install Redis (if not already installed)

On Ubuntu/Debian:

On macOS (via Homebrew):

Verify Redis is running:

Step 2: Install the Extension

This will automatically install fof/redis as a dependency.

Configuration

Basic Setup

Horizon requires Redis to be configured. Create or modify your extend.php in the root of your Flarum installation:

Advanced Redis Configuration

Using separate databases for different services:

Disabling specific Redis features:

Redis Sentinel (High Availability):

Customizing Horizon Configuration

You can override Horizon's default configuration by creating a custom config file:

1. Create a Horizon config file (e.g., config/horizon.php in your Flarum root):

2. Register your config in extend.php:

Running Horizon

Development (Manual)

Start Horizon from your Flarum root directory:

This will run as long as the terminal session is active. Press Ctrl+C to stop.

Production (Supervisor)

For production environments, use a process monitor like Supervisor to keep Horizon running:

1. Install Supervisor:

2. Create a Supervisor configuration (/etc/supervisor/conf.d/horizon.conf):

3. Start Supervisor:

4. Check status:

Systemd (Alternative)

Create a systemd service file (/etc/systemd/system/flarum-horizon.service):

Enable and start:

Usage

Accessing the Dashboard

Navigate to: https://yourforum.com/admin/horizon

Available Commands

Start Horizon:

View active supervisors:

Pause all workers:

Continue processing after pause:

Pause a specific supervisor:

Continue a specific supervisor:

View Horizon status:

View supervisor status:

Terminate all workers gracefully:

Clear all jobs from a queue:

Purge failed jobs:

Delete a specific failed job:

Delete all failed jobs:

Clear metrics:

Dashboard Features

Real-time Monitoring

• Jobs Per Minute - Current throughput
• Pending Jobs - Jobs waiting to be processed
• Failed Jobs - Recent failures
• Processes - Active worker processes
• Wait Time - Average queue wait time
• Status - Horizon operational status (running/paused/inactive)

Job Management

• View pending jobs - See what's in the queue
• View completed jobs - Recent successful jobs
• View failed jobs - Inspect failures with full stack traces
• Retry failed jobs - Re-queue failed jobs
• Monitor specific tags - Track tagged jobs

Metrics

• Job Metrics - Performance stats per job type
• Queue Metrics - Stats per queue
• Throughput - Jobs processed over time
• Runtime - Job execution times

Troubleshooting

Dashboard shows errors

Issue: 500 errors or "Redis not configured" messages

Solution: Ensure Redis is properly configured in extend.php:

Workers not processing jobs

Issue: Jobs remain in pending state

Solution:

1. Ensure Horizon is running: sudo supervisorctl status horizon
2. Restart Horizon: php flarum horizon:terminate then start again
3. Check for errors: tail -f storage/logs/horizon.log

After deployment, workers process old code

Issue: Code changes not reflected in running workers

Solution: Always terminate and restart Horizon after deployments:

Or via Supervisor:

Memory issues

Issue: Workers consuming too much memory, or you see Memory limit exceeded: Using X/128MB. Consider increasing horizon.memory_limit.

There are two separate memory limits:

• memory_limit — the master supervisor process. When exceeded, Horizon restarts itself gracefully. Default: 128 MB.
• memory (per supervisor) — each individual worker process. When exceeded after a job completes, the worker is recycled. Default: 128 MB.

Solution: Override either limit via config.php:

Or via the Horizon extender in extend.php:

You can also limit how long a worker runs before being recycled:

Performance Tips

1. Use Auto-scaling: Set 'balance' => 'auto' to automatically scale workers based on load
2. Separate Queues: Use different queues for high/low priority jobs
3. Set Memory Limits: Configure memory to restart workers before they consume too much
4. Monitor Metrics: Regularly check the dashboard for bottlenecks
5. Tag Jobs: Use tags to group and monitor related jobs

Security

• The Horizon dashboard is automatically protected by Flarum's admin authentication
• No additional security configuration needed
• Only forum administrators can access /admin/horizon

Upgrading

Then restart Horizon (via Supervisor or manually).

Migration from Blomstra Redis

If you're upgrading from the older blomstra/redis package:

1. Simply update namespace references from Blomstra\Redis to FoF\Redis in your extend.php
2. All configuration options remain the same

Links

• Packagist: fof/horizon
• GitHub: FriendsOfFlarum/horizon
• Discuss: Flarum Community
• Documentation: Laravel Horizon Docs

License

MIT

Made with ❤️ by FriendsOfFlarum