Installing Laravel Horizon on Heroku: A Complete Guide

Laravel Horizon provides a beautiful dashboard and code-driven configuration for your Redis queues. Here’s a detailed guide to installing and setting up Laravel Horizon on Heroku.

Step 1: Install Redis

1. Login to Heroku
2. Select Your App
   • Choose the app where you want to install Redis (staging/production).
3. Go to the Resources Tab
4. Add Redis Add-on
   • In the Add-ons section, search for "Heroku Data for Redis."
   • Click on the result with the title “Heroku Data for Redis.”
   • Select the monthly subscription plan for Redis.
   • Click the Submit Order button.

Step 2: Set Up Horizon

1. Login to Heroku
2. Select Your App
   • Choose the app where you want to set up Horizon (staging/production).
3. Go to the Resources Tab
4. Select Redis Add-on
   • In the Add-ons section, select "Heroku Data for Redis."
5. Get Redis Credentials
   • Go to the Settings tab.
   • Click on the View Credentials button.
   • Copy the URI value.

6. Configure Environment Variables

   • Go back to your app (staging/production).
   • Open the Settings tab.
   • Click on the Reveal Config Vars button.
   • Add the following key-value pairs:
     • Key: REDIS_CLIENT, Value: predis (ensure predis is installed; check your composer.json file).
     • Key: QUEUE_CONNECTION, Value: redis.
     • Key: REDIS_URL, Value: <paste your Redis URI>.

   Note: It’s recommended to add REDIS_URL as a config var instead of separate REDIS_HOST and REDIS_PASSWORD because Heroku frequently changes the credentials automatically, which can cause issues if using REDIS_HOST and REDIS_PASSWORD.

   • Click the Add button.
7. Update Procfile
   • Open the Procfile in your Laravel project.

   • Add the following commands:

     release: php artisan horizon:terminate
     worker: php artisan horizon

8. Deploy Your Code
   • Deploy your code using Git or any other deployment service you use.

Step 3: Scale Worker

1. Ensure Heroku CLI is Installed
   • Make sure you have the Heroku CLI installed on your system to access your Heroku server via the terminal.
2. Login to Heroku
   • Open the terminal on your system.
   • Run: heroku login
   • This command will open your browser; login to your Heroku account. After authorization, the terminal will be logged in. You can close the browser afterward.
3. Check Existing Workers
   • Run: heroku ps --app <your-heroku-app-name>
   • If the output shows something like worker.x up 2024/07/02 00:10:39 +0530 (~ 45m ago) (where x is the number of workers), it means a worker is already installed, and you can skip the next step. Make sure to check the required amount of workers from your Procfile.
4. Scale Worker
   • Run: heroku ps:scale worker=1 --app <your-heroku-app-name>
   • Adjust the number of workers according to the number specified in your Laravel project's Procfile.
   • If you encounter an error saying Couldn't find that process type (worker), ensure the worker is added in your Procfile and deployed on the server.

Step 4: Test Installation

1. Access Your App
   • Open <your-app.com>/login (replace with your website URL).
2. Login with Admin Account

   • Login with an admin account. You can check allowed users in the gate() method inside App\Providers\HorizonServiceProvider.php:

     protected function gate(): void
     {
         Gate::define('viewHorizon', function ($user) {
             return in_array($user->email, [
                 'admin@example.com'
             ]);
         });
     }
     

3. Open Horizon Dashboard
   • Open <your-app.com>/horizon.

Extra Tip:

If you are using predis with horizon, you may face an annoying error related to redis connection failure, such as:

Error while reading line from the server. [tls://your.redis.ip.address:port]

A quick fix for this error on heroku is setting timout to 0, not in the script but on your heroku server by running below command:

heroku redis:timeout --seconds 0 --app your-app-name

To verify if timout is changed to zero, you can run below command:

heroku redis --app you-app-name

By following these steps, you’ll have Laravel Horizon set up on Heroku, allowing you to manage your Redis queues efficiently.