How to Install, Configure and use Horizon in Laravel

Posted on August 9th, 2024

If you’re new to Laravel and looking to set up Horizon to manage your queues, you’re in the right place. Laravel Horizon is a powerful queue manager designed specifically for Laravel applications. It provides a beautiful dashboard and code-driven configuration for monitoring and managing queues. Horizon gives insights into job throughput, runtime, and failures and allows you to manage job retries. This tool is essential for applications that leverage Laravel’s queue system for background job processing. This step-by-step guide will help you start with Horizon in your Laravel application.

Prerequisites

Before you begin setting up Laravel Horizon, make sure you have the following prerequisites:

  • Composer: Ensure Composer is installed on your local machine. Composer is a dependency manager for PHP that you can download from getcomposer.org.
  • Laravel Project: Set up and run a Laravel project. It’s recommended that you use Laravel version 5.7 or higher. You can create a new Laravel project by following the instructions on the Laravel installation page.
  • Redis: Horizon requires Redis as the queue backend. Ensure Redis is installed and running on your local machine or server.

Installing Laravel Horizon

To add Horizon to your Laravel project, follow these steps:

Step 1: Open your terminal or command prompt: This is where you will execute the commands to set up Horizon.

Step 2: Navigate to your Laravel project directory using the following command.

cd /path/to/your/laravel/project

Replace /path/to/your/laravel/project with the path to your Laravel project directory.

Execute the following command to install Laravel Horizon using Composer:

composer require laravel/horizon

This command installs Horizon as a dependency in your Laravel project. Once installed, We can publish the Horizon configuration files and install Horizon in our project.

Publishing The Horizon Configuration

After installing Horizon, you need to publish its configuration file. This step will create a horizon.php file in your config directory. Run this command:

php artisan horizon:install

Once done, Let’s move on to the configuration part.

Configure Your Environment

Step 1 – Open .env file: Locate and open the .env file in the root directory of your Laravel project.

Step 2 – Set queue connection: Ensure the queue connection is set to Redis by adding or updating the following line:

QUEUE_CONNECTION=redis

This configuration tells Laravel to use Redis as the backend for queueing jobs.

Step 3 – Configure Redis settings: Add or update Redis connection details to match your Redis server configuration using the following three directives in the environment file.

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

Replace your_redis_password with the actual password for your Redis server. If you’re unsure of the password, you can find it by running the following command:

sudo grep requirepass /etc/redis/redis.conf

This command searches the Redis configuration file for the requirepass directive, which contains the password.

Step 4 – Save and cache configuration: After updating the .env file, run the following command to cache the updated configuration:

php artisan config:cache

This command optimizes your configuration settings and ensures Laravel uses the latest environment values.

Step 4: Configuring Horizon

You can customize Horizon’s behaviour using the configuration file located at config/horizon.php. This file provides various settings to tailor Horizon’s operation to fit your application’s needs. Here’s a detailed explanation of each setting:

1. Domain and Path

Domain: Specifies the subdomain where Horizon will be accessible. If set to null, Horizon will use the main domain.

'domain' => env('HORIZON_DOMAIN'),

Path: Specifies the URI path for accessing Horizon. The default is the horizon.

'path' => env('HORIZON_PATH', 'horizon'),

2. Redis Prefix

Set the prefix for Horizon-related keys in Redis to avoid collisions.

'prefix' => env(
    'HORIZON_PREFIX',
    Str::slug(env('APP_NAME', 'laravel'), '_').'_horizon:'
)

Note that it is very important to specify the Prefix. If you have other applications on the same server using Redis, Not setting the prefix will result into collisions. Collisions will make your application behave illogically.

3. Middleware

Middleware: Defines the middleware applied to Horizon routes. The default is ['web'].

'middleware' => ['web'],

4. Queue Wait Times

Waits: Configures how long Horizon waits for jobs on specified queues before taking action.

'waits' => [
    'redis:default' => 60,
],

5. Trimming

Trimming: Configures how long Horizon retains job records for different categories.

'trim' => [
    'recent' => 60,
    'pending' => 60,
    'completed' => 60,
    'recent_failed' => 10080,
    'failed' => 10080,
    'monitored' => 10080,
]

Here is the detailed information about each type of job.

  • Recent Jobs: Retains recent job records for 60 minutes.
  • Pending Jobs: Keeps records of pending jobs for 60 minutes.
  • Completed Jobs: Retains records of completed jobs for 60 minutes.
  • Recent Failed Jobs: Keeps records of recently failed jobs for 10,080 minutes (7 days).
  • Failed Jobs: Retains failed job records for 10,080 minutes (7 days).
  • Monitored Jobs: Retains monitored job records for 10,080 minutes (7 days).

6. Silenced Jobs

Silenced: Specifies jobs that should not appear on the dashboard’s completed jobs list.

'silenced' => [
    // App\Jobs\ExampleJob::class,
],

7. Metrics

Metrics: Configures how many snapshots Horizon retains for metrics graphs.

'metrics' => [
    'trim_snapshots' => [
        'job' => 24,
        'queue' => 24,
    ],
],

8. Fast Termination

Fast Termination: When enabled, allows a new Horizon instance to start before the old one finishes shutting down.

'fast_termination' => false,

9. Memory Limit

Memory Limit: Sets the maximum memory Horizon’s master supervisor can use before restarting.

'memory_limit' => 64,

10. Environments

Environments: Defines different configurations for Horizon supervisors based on the environment.

'environments' => [
    'production' => [
        'supervisor-1' => [
            'maxProcesses' => 10,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
        ],
    ],

    'local' => [
        'supervisor-1' => [
            'maxProcesses' => 3,
        ],
    ],
],

Here is the explaination on both the default environments. However, If you have more environments, You can create a configuration according to your requirements.

  • Production: Configures the supervisor to manage 10 processes with specific balancing and cooldown settings.
  • Local: Configures the supervisor to manage 3 processes suitable for a local development environment.

By carefully configuring these settings, you can optimize Horizon’s performance, tailor it to your operational requirements, and ensure efficient job processing and resource management in your Laravel application.

Step 5: Securing the Horizon Dashboard

You must configure dashboard authorization to ensure that only authorized users can access the Horizon dashboard. By default, Horizon uses Laravel’s authentication system to restrict access.

Define Authorization Logic: Open the HorizonServiceProvider located in app/Providers/HorizonServiceProvider.php and update the gate method:

protected function gate()
{
    Gate::define('viewHorizon', function ($user) {
        return in_array($user->email, [
            '[email protected]',
        ]);
    });
}

Replace [email protected] with the email addresses of users who should have access to the Horizon dashboard.

Step 6: Run Horizon

Now it’s time to start Horizon. Use the following Artisan command to run Horizon:

php artisan horizon

Horizon will start processing jobs and provide a dashboard for monitoring the queues. The Horizon dashboard is available at /horizon in your application by default.

Step 7: Accessing Horizon Dashboard

After setting up and configuring Horizon, you can access the Horizon dashboard in your browser using the configured path. For example, if you kept the default path, you can access it at http://your-laravel-app.test/horizon. This dashboard provides a comprehensive view of all monitored aspects of your Laravel application’s queues.

Understanding Horizon Features

Laravel Horizon provides a comprehensive suite of tools for managing and monitoring your queues. The Horizon dashboard organizes its features into sections accessible from the sidebar. Here’s an in-depth look at each section:

Dashboard

This is Horizon’s main view and provides an overview of your queue system. It offers a snapshot of job performance, recent activity, and general statistics.

Monitoring

This section lets you monitor your queues’ overall health and performance. You can see real-time information about job processing and supervisor status.

Metrics

In the Metrics section, Horizon provides detailed analytics on various aspects of your job queues. You can view:

  • Job Throughput: The number of jobs processed over time.
  • Runtime: How long jobs are taking to process.
  • Failure Rates: The frequency of job failures, helping you track and address issues promptly.

This section is crucial for understanding performance trends and making data-driven decisions to optimize queue management.

Batches

This feature helps you manage and monitor jobs processed in batches. Batches are groups of jobs that are processed together. In this section, you can:

  • Track Batch Progress: You can see the status of each batch, including how many jobs have been processed versus how many remain.
  • View Batch Details: Access detailed information about each job in the batch, including any failures or issues encountered.

Pending Jobs

This section displays jobs that are in the queue but have yet to be processed. It helps you monitor:

  • Job Status: See which jobs are waiting to be picked up by workers.
  • Queue Load: Understand how many jobs are pending and if there are any delays in processing.

Completed Jobs

Here, you can view jobs that have been successfully processed. This section provides:

  • Job Details: Information about each completed job, including processing time and result.
  • Success Metrics: These metrics provide insight into how many jobs have been processed successfully, helping you gauge the efficiency of your queue system.

Silenced Jobs

This section shows jobs that have been silenced or are no longer being processed. Jobs might be silenced due to specific conditions or configurations. You can:

  • Review Silenced Jobs: Understand why these jobs are not being processed and determine if any action is needed.
  • Reconfigure Jobs: Adjust job settings or resubmit jobs if necessary.

Failed Jobs

Displays all jobs that have been unable to be processed. This section includes:

  • Error Details: Detailed error messages and stack traces for each failed job.
  • Retry Options: You can retry failed jobs or investigate issues to prevent future failures.

Understanding these sections helps you effectively manage and troubleshoot your Laravel queues using Horizon, ensuring smooth operation and optimal performance of background job processing.

Step 8: Deploying Horizon

When deploying Horizon in a production environment, running it as a daemon is a good practice to keep it active. You can use a process manager like a Supervisor to ensure Horizon stays running. Here’s an example configuration for Supervisor:

Create a configuration file at /etc/supervisor/conf.d/horizon.conf:

[program:horizon]
process_name=%(program_name)s
command=php /path/to/your/project/artisan horizon
autostart=true
autorestart=true
user=yourusername
redirect_stderr=true
stdout_logfile=/path/to/your/project/storage/logs/horizon.log

After creating the configuration file, update Supervisor and start Horizon:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon

Replace /path/to/your/project with the path to your Laravel project and yourusername with your system username.

Advanced Usage Examples

Explore advanced use cases with Horizon to optimize and manage your Laravel application’s queues:

  • Balancing Queue Loads: Use Horizon’s balancing options to distribute jobs evenly across workers.
  • Handling Failed Jobs: Utilize Horizon’s failed jobs dashboard to retry or investigate failed jobs efficiently.
  • Monitoring Specific Queues: Set up monitored jobs to keep a closer eye on critical queues.

Customizing Horizon

Customize Horizon to fit your specific queue management needs:

  • Modifying Configuration: Adjust config/horizon.php settings to change the dashboard path, enable/disable features, and configure supervisor options.
  • Adding Custom Middleware: Extend Horizon by adding custom middleware for additional access control or logging.
  • Integrating with Other Tools: Combine Horizon with Laravel Echo for real-time updates or with Laravel Forge for deployment monitoring.

Best Practices for Using Horizon

Follow these best practices to maximize the effectiveness of Horizon:

  • Regular Monitoring: Periodically review Horizon dashboards to ensure your queues are performing optimally.
  • Error Handling: Set up alerts for failed jobs to address issues promptly.
  • Resource Management: Adjust supervisor settings based on your application’s workload to optimize resource usage.

Conclusion

Laravel Horizon is an indispensable tool for managing and monitoring queues in Laravel applications. This guide will help you effectively set up, configure, and utilize Horizon to streamline queue management processes, optimize job performance, and ensure robust queue operations.

Additional Resources

For further reading and resources on Laravel Horizon:

By understanding and using Laravel Horizon, you can significantly improve your queue management workflow. Horizon will make it easier to monitor job performance, handle failures, and ensure a smoother operation of your background job processing.

Leave a Reply