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.
- 📊 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
- Flarum 2.0+
- Redis Server (required for Horizon to function)
- PHP 8.2+
On Ubuntu/Debian:
sudo apt update
sudo apt install redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-serverOn macOS (via Homebrew):
brew install redis
brew services start redisVerify Redis is running:
redis-cli ping
# Should return: PONGcomposer require fof/horizon:"*"
php flarum cache:clearThis will automatically install fof/redis as a dependency.
Horizon requires Redis to be configured. Create or modify your extend.php in the root of your Flarum installation:
<?php
use FoF\Redis\Extend\Redis;
return [
// Basic Redis configuration
new Redis([
'host' => '127.0.0.1',
'password' => null,
'port' => 6379,
'database' => 0,
]),
// ... other extenders
];Using separate databases for different services:
return [
(new Redis([
'host' => '127.0.0.1',
'password' => null,
'port' => 6379,
]))
->useDatabaseWith('cache', 1)
->useDatabaseWith('queue', 2)
->useDatabaseWith('session', 3),
];Disabling specific Redis features:
return [
(new Redis([
'host' => '127.0.0.1',
'port' => 6379,
]))
->disable(['cache']), // Only use Redis for queue and sessions
];Redis Sentinel (High Availability):
return [
new Redis([
'host' => '127.0.0.1',
'port' => 26379,
'options' => [
'replication' => 'sentinel',
'service' => 'mymaster',
],
]),
];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):
<?php
return [
'defaults' => [
'supervisor-1' => [
'connection' => 'redis',
'queue' => ['default'],
'balance' => 'auto',
'autoScalingStrategy' => 'time',
'maxProcesses' => 10,
'maxTime' => 0,
'maxJobs' => 0,
'memory' => 128,
'tries' => 3,
'timeout' => 60,
'nice' => 0,
],
],
'environments' => [
'production' => [
'supervisor-1' => [
'maxProcesses' => 20,
'balanceMaxShift' => 1,
'balanceCooldown' => 3,
],
],
],
];2. Register your config in extend.php:
<?php
use FoF\Horizon\Extend\Horizon;
return [
(new Horizon)->config('./config/horizon.php'),
];Start Horizon from your Flarum root directory:
php flarum horizonThis will run as long as the terminal session is active. Press Ctrl+C to stop.
For production environments, use a process monitor like Supervisor to keep Horizon running:
1. Install Supervisor:
# Ubuntu/Debian
sudo apt install supervisor
# macOS
brew install supervisor
brew services start supervisor2. Create a Supervisor configuration (/etc/supervisor/conf.d/horizon.conf):
[program:horizon]
process_name=%(program_name)s
command=php /var/www/flarum/flarum horizon
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/flarum/storage/logs/horizon.log
stopwaitsecs=36003. Start Supervisor:
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon4. Check status:
sudo supervisorctl status horizonCreate a systemd service file (/etc/systemd/system/flarum-horizon.service):
[Unit]
Description=Flarum Horizon
After=network.target
[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/flarum
ExecStart=/usr/bin/php /var/www/flarum/flarum horizon
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.targetEnable and start:
sudo systemctl daemon-reload
sudo systemctl enable flarum-horizon
sudo systemctl start flarum-horizon
sudo systemctl status flarum-horizonNavigate to: https://yourforum.com/admin/horizon
Start Horizon:
php flarum horizonView active supervisors:
php flarum horizon:listPause all workers:
php flarum horizon:pauseContinue processing after pause:
php flarum horizon:continuePause a specific supervisor:
php flarum horizon:pause-supervisor supervisor-1Continue a specific supervisor:
php flarum horizon:continue-supervisor supervisor-1View Horizon status:
php flarum horizon:statusView supervisor status:
php flarum horizon:supervisor-status supervisor-1Terminate all workers gracefully:
php flarum horizon:terminateClear all jobs from a queue:
php flarum horizon:clear redis --queue=defaultPurge failed jobs:
php flarum horizon:purgeDelete a specific failed job:
php flarum horizon:forget {job-id}Delete all failed jobs:
php flarum horizon:forget --allClear metrics:
php flarum horizon:clear-metrics- 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)
- 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
- Job Metrics - Performance stats per job type
- Queue Metrics - Stats per queue
- Throughput - Jobs processed over time
- Runtime - Job execution times
Issue: 500 errors or "Redis not configured" messages
Solution: Ensure Redis is properly configured in extend.php:
# Test Redis connection
redis-cli ping
# Check Flarum logs
tail -f storage/logs/flarum-*.logIssue: Jobs remain in pending state
Solution:
- Ensure Horizon is running:
sudo supervisorctl status horizon - Restart Horizon:
php flarum horizon:terminatethen start again - Check for errors:
tail -f storage/logs/horizon.log
Issue: Code changes not reflected in running workers
Solution: Always terminate and restart Horizon after deployments:
php flarum horizon:terminate
# Wait a few seconds for graceful shutdown
php flarum horizonOr via Supervisor:
sudo supervisorctl restart horizonIssue: Workers consuming too much memory
Solution: Adjust memory limits in your Horizon config:
'defaults' => [
'supervisor-1' => [
'memory' => 128, // MB
'maxJobs' => 1000, // Restart after X jobs
'maxTime' => 3600, // Restart after X seconds
],
],- Use Auto-scaling: Set
'balance' => 'auto'to automatically scale workers based on load - Separate Queues: Use different queues for high/low priority jobs
- Set Memory Limits: Configure
memoryto restart workers before they consume too much - Monitor Metrics: Regularly check the dashboard for bottlenecks
- Tag Jobs: Use tags to group and monitor related jobs
- The Horizon dashboard is automatically protected by Flarum's admin authentication
- No additional security configuration needed
- Only forum administrators can access
/admin/horizon
composer update fof/horizon
php flarum migrate
php flarum cache:clear
php flarum horizon:terminateThen restart Horizon (via Supervisor or manually).
If you're upgrading from the older blomstra/redis package:
- Simply update namespace references from
Blomstra\RedistoFoF\Redisin yourextend.php - All configuration options remain the same
- Packagist: fof/horizon
- GitHub: FriendsOfFlarum/horizon
- Discuss: Flarum Community
- Documentation: Laravel Horizon Docs
MIT
Made with ❤️ by FriendsOfFlarum
