Forem: HoudaifaDevBS

From Slow Requests to Scalable Background Jobs with Laravel Queues & Horizon

HoudaifaDevBS — Fri, 10 Apr 2026 13:55:16 +0000

Almost anyone has experienced a scenario where you click a "Register / Submit" button, then stare at the screen waiting seconds — if not minutes — for a response, only to see a success message or, even worse, some errors popping up.

I know, it feels frustrating. It gives a bad user experience, and honestly? Everyone will just go find another faster solution.

In this article, we'll explain what's actually happening behind that loading spinner — and how you can better architect your solution to fix this once and for all.

Part 1 — The Problem (The Real One)

Let's make it concrete. Here's what a typical registration endpoint looks like in most Laravel apps:

public function register(Request $request)
{
    $user = User::create($request->validated());

    // Send welcome email
    Mail::to($user->email)->send(new WelcomeEmail($user));

    // Generate and store a welcome PDF
    $pdf = Pdf::loadView('pdfs.welcome', compact('user'));
    Storage::put("welcome/{$user->id}.pdf", $pdf->output());

    return response()->json(['message' => 'Registration successful!']);
}

Looks familiar, right?

The problem is that everything here runs sequentially, inside the same request. Laravel won't return that success response until every single line finishes executing — the email, the Slack call, the PDF, all of it.

So if your mail provider takes 2 seconds and the PDF takes another second, your user just waited 3+ seconds to see "Registration successful". And that's on a good day, with no timeouts or failures.

This pattern shows up everywhere:

Sending emails or SMS after an action
Calling third-party APIs (payment gateways, webhooks, analytics)
Generating reports or exports
Processing uploaded files or images

All of these have one thing in common — the user doesn't need to wait for them. They just need to know their action was received. The rest can happen in the background.

That's exactly what we're going to fix.

Part 2 — How Laravel Queues Work

Before jumping into code, let's build a quick mental model — I promise this is the only "theory" section.

When a user hits your endpoint, Laravel normally does everything in that same request lifecycle — sends the email, calls the API, generates the PDF — and only then returns a response. The user waits for all of it.

Queues flip that completely.

Instead of doing the heavy work immediately, you push a job onto a queue — think of it as a to-do list — and return the response right away. A separate process called a worker is running in the background, picking jobs off that list and executing them one by one, completely outside the user's request.

Three actors to keep in mind:

Job — the class that contains the actual work (SendWelcomeEmail, GenerateInvoice...)
Queue — the list where jobs wait (we'll use Redis, more on that in a second)
Worker — the background process that pulls jobs from the queue and runs them (php artisan queue:work)

That's really it. The rest is just configuration and knowing which scenarios to apply this to — which is exactly what we'll cover next.

💡 Why Redis and not the database driver? Laravel supports multiple queue drivers — database, Redis, SQS, and others. The database driver works fine for getting started, but Redis is faster and lighter on your DB, and it's what you'll realistically use in production. So we'll go with Redis from the start and skip the detour.

Part 3 — Setting Up Redis & Queue Config

Alright, enough theory — let's get our hands dirty.

Install Redis

On Ubuntu / your VPS:

sudo apt update
sudo apt install redis-server -y
sudo systemctl enable redis-server
sudo systemctl start redis-server

redis-cli ping        # If you got PONG — you're good.

Find below the installation instructions for each platform:
https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis/

Install the Laravel Redis Package

Laravel needs one extra package to talk to Redis:

composer require predis/predis

Configure Your `.env`

Two changes only in .env:

QUEUE_CONNECTION=redis           # switch to the redis driver

REDIS_CLIENT=predis              # use the predis package installed
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

By default, Laravel uses sync as the queue driver — meaning jobs run immediately, synchronously, defeating the whole purpose. Switching to redis is what actually enables the background behavior.

Quick Sanity Check

Before writing a single job, let's confirm everything is wired correctly. Run your worker:

php artisan queue:work

You should see something like:

INFO  Processing jobs from the [default] queue.

No errors? Perfect. Leave that terminal open — that's your worker listening for jobs. Open a second terminal for the next steps.

💡 Heads up for production: Running queue:work manually is fine for local development, but on your server you need a process manager to keep it alive — if it crashes, your jobs just pile up with nobody processing them. We'll cover that with Supervisor in the Horizon section.

Part 4 — Your First Real Job

Remember that messy controller from Part 1? Let's start fixing it — one job at a time.

We'll tackle the welcome email first since it's the most common and the cleanest example to learn the pattern with.

php artisan make:job SendWelcomeEmail        # Create the Job

This creates app/Jobs/SendWelcomeEmail.php. Open it up:

class SendWelcomeEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public User $user) {}

    public function handle(): void
    {
        Mail::to($this->user->email)->send(new WelcomeEmail($this->user));
    }
}

Two things to notice here:

ShouldQueue — This interface is what tells Laravel "don't run this now, push it to the queue."
SerializesModels — handles serializing and deserializing your Eloquent models automatically so that you can pass $user directly without worrying about it.

Dispatch It From Your Controller

Now go back to your controller and replace the Mail::to(...) line:

// Before
Mail::to($user->email)->send(new WelcomeEmail($user));

// After
SendWelcomeEmail::dispatch($user);

That's it — one line. Your controller doesn't care when or how the email gets sent anymore — it just says "handle this" and moves on.

Your registration endpoint now looks like this:

public function register(Request $request)
{
    $user = User::create($request->validated());
    SendWelcomeEmail::dispatch($user);
    return response()->json(['message' => 'Registration successful!']);
}

The response comes back instantly. The email is sent in the background by your worker.

💡 Want to delay a job? You can dispatch a job with a delay super easily:
SendWelcomeEmail::dispatch($user)->delay(now()->addMinutes(5));
Useful for things like "send a follow-up email 10 minutes after registration".

That's the core pattern — everything else you'll do with queues is just a variation of this. Create a job, move the logic into handle(), and dispatch it. Let's now apply this to three real-world scenarios you'll actually run into.

Part 5 — Real World Scenarios

Scenario A — Calling a Third-Party API (Slack, SMS, Webhooks)

Third-party APIs are the #1 culprit for slow responses. You have zero control over their response time — and they can fail.

php artisan make:job NotifyAdminOnSlack   # create the job

class NotifyAdminOnSlack implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 3;
    public int $backoff = 10;

    public function __construct(public User $user) {}

    public function handle(): void
    {
        Http::post(config('services.slack.webhook'), [
            'text' => "New user registered: {$this->user->email}"
        ]);
    }
}

Notice $tries = 3 and $backoff = 10 — if Slack is down or slow, Laravel will automatically retry the job 3 times, waiting 10 seconds between each attempt. Your user never sees any of this.

Dispatch both jobs from your controller:

SendWelcomeEmail::dispatch($user);
NotifyAdminOnSlack::dispatch($user);
return response()->json(['message' => 'Registration successful!']);

Two background jobs, zero waiting.

Scenario B — Generating a PDF or Report on Demand

This one is slightly different — the user actually needs the result, they just don't need to wait for it right now.

php artisan make:job GenerateWelcomePdf       # create the job

class GenerateWelcomePdf implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public User $user) {}

    public function handle(): void
    {
        $pdf = Pdf::loadView('pdfs.welcome', [
            'user' => $this->user
        ]);
        Storage::put(
            "welcome/{$this->user->id}.pdf",
            $pdf->output()
        );
        // Notify the user it's ready
        $this->user->notify(new PdfReadyNotification());
    }
}

The pattern here is: generate → store → notify. The user gets an instant response on registration, and a notification (email, in-app, whatever you prefer) once their PDF is actually ready. Clean and professional.

Scenario C — Processing a Bulk CSV Import

This is where queues really shine. Importing 5,000 rows in a single request is a recipe for timeouts and misery.

Instead of one giant job, chunk your data into smaller jobs:

php artisan make:job ImportUserRow            # create the job

class ImportUserRow implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public array $row) {}

    public function handle(): void
    {
        User::updateOrCreate(
            ['email' => $this->row['email']],
            [
                'name' => $this->row['name'],
                'phone' => $this->row['phone'],
            ]
        );
    }
}

Then, in your import controller, loop through the CSV and dispatch one job per row (or per chunk):

public function import(Request $request)
{
    $rows = array_map('str_getcsv', file($request->file('csv')));
    foreach ($rows as $row) {
        ImportUserRow::dispatch($row);
    }
    return response()->json([
        'message' => 'Import started! We will notify you when it\'s done.'
    ]);
}

5,000 rows? 50,000 rows? Doesn't matter — your endpoint returns in milliseconds, and your workers chew through the data in the background at their own pace.

💡 Need all jobs to finish before doing something? Laravel has Bus::batch() for exactly this — group jobs together, track their progress, and run a callback when they all complete. Worth a separate deep-dive on its own.

Three scenarios, one pattern. Create the job, handle the work, dispatch and forget. Next up — what happens when things go wrong?

Part 6 — Handling Failures Like a Pro

Background jobs fail. Mail providers go down, APIs timeout, PDFs throw exceptions — it happens. The difference between a solid implementation and a fragile one is how you handle it when things go wrong.

Set Up the Failed Jobs Table

First, make sure you have the failed jobs table:

php artisan queue:failed-table             # create the migration file
php artisan migrate

Laravel will now store any failed job in this table instead of silently dropping it — including the exception, the payload, and when it failed.

Retries, Timeouts & Backoff

You can control failure behavior directly on the job class:

class SendWelcomeEmail implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public int $tries = 3;        // retry up to 3 times
    public int $timeout = 30;     // kill the job if it runs longer than 30s
    public int $backoff = 15;     // wait 15 seconds between retries

    // ...
}

Or if you want exponential backoff — waiting longer after each failed attempt:

public function backoff(): array
{
    return [10, 30, 60]; // 10s after 1st fail, 30s after 2nd, 60s after 3rd
}

This is great for flaky third-party APIs — instead of hammering them every 10 seconds, you give them room to recover.

The `failed()` Method

When a job exhausts all its retries, Laravel calls the failed() method on it — if you define one:

public function failed(\Throwable $exception): void
{
    // Notify yourself, log it, alert the user...
    Log::error("SendWelcomeEmail failed for user {$this->user->id}", [
        'error' => $exception->getMessage()
    ]);
    $this->user->notify(new EmailFailedNotification());
}

Never leave this empty on jobs that matter. Silently failing jobs are worse than crashing — at least a crash is loud.

Managing Failed Jobs via CLI

php artisan queue:failed       # See all failed jobs
php artisan queue:retry 5      # Retry a specific failed job by its ID
php artisan queue:retry all    # Retry all failed jobs at once
php artisan queue:forget 5     # Delete a specific failed job
php artisan queue:flush        # Clear the entire failed jobs table

`ShouldBeUnique` — Prevent Duplicate Jobs

Sometimes the same job gets dispatched multiple times — user double-clicks, a webhook fires twice, whatever. For jobs where duplicates are a real problem, implement ShouldBeUnique:

class GenerateWelcomePdf implements ShouldQueue, ShouldBeUnique
{
    public int $uniqueFor = 3600; // lock for 1 hour

    public function uniqueId(): string
    {
        return $this->user->id; // one job per user at a time
    }
}

Laravel will skip dispatching if a job with the same uniqueId() is already in the queue. Clean solution, zero extra code on the dispatch side.

💡 Golden rule: always define $tries, $timeout, and failed() on any job that touches a third-party service or generates critical data. The 2 minutes it takes to add them will save you hours of debugging in production.

Part 7 — Laravel Horizon

queue:work gets the job done locally, but in production, you need visibility — which jobs are running, how long they're taking, what's failing, and whether your workers are keeping up. That's exactly what Horizon gives you.

Install Horizon

composer require laravel/horizon
php artisan horizon:install            # install and create migration files
php artisan migrate

This publishes a config file at config/horizon.php and sets up the dashboard.

Basic Configuration

Open config/horizon.php. The part you care about most is environments:

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

Horizon uses supervisors to manage your workers internally — don't confuse these with the system-level Supervisor we'll set up in a moment. These are Horizon's own worker groups.

You can also assign specific jobs to specific queues and control priority:

'supervisor-1' => [
    'connection' => 'redis',
    'queue' => ['critical', 'default', 'low'],
    'balance' => 'auto',
    'maxProcesses' => 10,
],

Jobs on the critical queue get processed before default, which gets processed before low. Useful when you want invoice processing to always beat bulk imports.

Dispatch to a specific queue like this:

GenerateInvoice::dispatch($order)->onQueue('critical');
ImportUserRow::dispatch($row)->onQueue('low');

Protect the Dashboard

The Horizon dashboard runs at /horizon and exposes sensitive data — failed jobs, job payloads, throughput. Lock it down:

// app/Providers/HorizonServiceProvider.php
protected function gate(): void
{
    Gate::define('viewHorizon', function ($user) {
        return in_array($user->email, [
            'you@yourdomain.com',
        ]);
    });
}

Only whitelisted emails can access the dashboard in production. Simple, effective.

Reading the Dashboard

Once Horizon is running (php artisan horizon), head to /horizon:

Throughput — how many jobs per minute your workers are processing
Runtime — average execution time per job class — if something spikes here, that's your bottleneck
Wait time — how long jobs sit in the queue before a worker picks them up — if this grows, you need more workers
Failed jobs — everything that broke, with the full exception and payload right there in the UI — no more digging through logs

This alone is worth installing Horizon for.

Keep Horizon Running with Supervisor

On your server, you need Supervisor to keep Horizon alive. If it crashes or the server restarts, Supervisor brings it back automatically.

sudo apt install supervisor -y                   # Install Supervisor

sudo nano /etc/supervisor/conf.d/horizon.conf    # Create a config file

# horizon.conf
[program:horizon]
process_name=%(program_name)s
command=php /var/www/yourapp/artisan horizon
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/yourapp/storage/logs/horizon.log
stopwaitsecs=3600

Apply and start:

sudo supervisorctl reread                  # reload the config
sudo supervisorctl update
sudo supervisorctl start horizon

One last thing — whenever you deploy new code, restart Horizon gracefully so it picks up the changes without dropping running jobs:

php artisan horizon:terminate        # run manually or put in CI/CD pipeline

Part 8 — Production Checklist

Before you ship, run through this quickly:

Redis

[ ] Redis is installed and running on your server (redis-cli ping returns PONG)
[ ] QUEUE_CONNECTION=redis in your production .env
[ ] Redis password is set if your server is exposed

Jobs

[ ] Every job that touches a third-party service has $tries, $timeout, and backoff() defined
[ ] Critical jobs implement failed() and notify you when they break
[ ] Duplicate-sensitive jobs implement ShouldBeUnique
[ ] Failed jobs table migrated (queue:failed-table)

Horizon

[ ] Dashboard protected with gate() — not open to the public
[ ] Queue priorities configured (critical, default, low)
[ ] maxProcesses tuned to your server's capacity

Supervisor

[ ] Horizon running under Supervisor (supervisorctl status horizon shows RUNNING)
[ ] horizon:terminate added to your deploy script
[ ] Horizon logs are accessible at storage/logs/horizon.log

Sanity Check

[ ] Trigger a job locally and confirm the worker picks it up
[ ] Intentionally fail a job and confirm it shows up in /horizon and queue:failed
[ ] Check wait times in Horizon after your first real traffic — scale workers if needed

Part 9 — Conclusion

Let's go back to where we started — a user clicking "Register" and staring at a spinner for 8 seconds.

With everything we've set up, here's what that same flow looks like now:

User clicks Register
    → Controller creates the user
    → Dispatches 3 jobs to Redis (takes ~2ms)
    → Returns "Registration successful" instantly ✓

Meanwhile, in the background:
    → Worker picks up SendWelcomeEmail   → email sent
    → Worker picks up NotifyAdminOnSlack → Slack notified
    → Worker picks up GenerateWelcomePdf → PDF stored, user notified

The user is already on the dashboard while your workers are still doing the heavy lifting. That's the difference.

To recap what we covered:

Why synchronous code kills user experience and where it hides in typical Laravel apps
How the queue / job / worker model works under the hood
Setting up Redis and wiring it to Laravel in minutes
Converting slow controller logic into clean, dispatchable jobs
Three real-world scenarios — API calls, PDF generation, bulk imports
Handling failures properly with retries, backoff, and failed()
Monitoring everything in production with Laravel Horizon and Supervisor

Queues aren't an advanced topic — they're a fundamental tool, and once you get comfortable with the pattern, you'll start seeing opportunities to use them everywhere.

What's Next?

If you want to go deeper, here's where to go from here:

Job Batching with Bus::batch() — group related jobs, track progress, run callbacks on completion
Broadcasting job progress — combine queues with Laravel Reverb to show a real-time progress bar in your UI
Horizontal scaling — running multiple workers across multiple servers with Redis as the shared backbone

🔗 Stay Connected

Follow me for more Laravel tutorials, dev tips, deployment workflows and solving real-world production headaches.

Follow me on LinkedIn
Follow me here on Medium and join my mailing list
Follow me here on Dev.to for more in-depth content and tutorials!

Found this article useful?

🙏 Show your support by clapping 👏, subscribing 🔔, sharing to social networks

From Polling to Real-Time: Building a Laravel 12 Chat with WebSockets & Reverb

HoudaifaDevBS — Wed, 25 Feb 2026 17:40:35 +0000

Have you ever wondered how chat applications deliver messages instantly without overwhelming the server?

I recently worked on a legacy Laravel application that included a built-in chat system. At first glance, everything seemed functional — messages were sent and received, and the feature "worked."

But the experience felt off.

Messages were delayed. The interface became slower after a few minutes. Opening multiple tabs made things worse. Something clearly wasn't right.

After digging into the code, I discovered the issue: the application was repeatedly requesting new messages every few seconds. It was using a technique known as polling.

In other words, every connected user was continuously asking the server:

"Do you have new messages now?"
"What about now?"
"Now?"

This approach might work for small internal tools, but it doesn't scale. With enough users, the number of HTTP requests explodes — consuming server resources while still delivering a delayed "real-time" experience.

That's when I decided to rebuild the entire chat system using a proper WebSocket-based architecture with Laravel Reverb.

The difference was dramatic:

Latency dropped significantly
HTTP request volume decreased drastically
The UI became truly real-time

In this article, I'll walk you through how I built a production-ready WebSocket solution using Laravel 12, Reverb, and Nginx.

1. Why Polling Fails at Scale

Polling seems simple. The client sends an HTTP request every few seconds asking: "Do you have new messages?"

If there are new messages, the server responds with them. If not, it returns an empty response.

At small scale, this works. But let's look at the math.

If one user polls every 3 seconds:

20 requests per minute
1,200 requests per hour

Now imagine 100 concurrent users:

2,000 requests per minute
120,000 requests per hour

And most of those requests return… nothing.

This creates three major problems:

1. Massive Waste of Resources — Every single HTTP request requires the server to accept the connection, bootstrap the Laravel framework, hit the routing layer, check authentication, and likely query the database — just to return an empty JSON array. This eats up CPU and RAM for zero actual payload.

2. Artificial Latency — If a user polls every 3 seconds, and a message is sent right after a poll finishes, the receiving user won't see it for almost 3 seconds. In a modern chat application, a 3-second delay feels like an eternity.

3. Client-Side Degradation — Opening multiple tabs means multiplying those requests. Browsers limit the number of concurrent connections to the same domain. If your polling clogs up those connections, the rest of your application (like loading images or saving form data) starts to crawl.

2. The WebSocket Solution: From Asking to Listening

Instead of the client repeatedly asking the server for updates, what if the server just told the client when something happened?

Enter WebSockets.

A WebSocket creates a persistent, bi-directional, full-duplex connection between the client and the server.

Connect Once — The client makes a single HTTP request to establish the connection, which is then "upgraded" to a WebSocket.
Listen Continuously — The connection stays open with minimal overhead. The client simply waits.
Push Instantly — When User A sends a message, the server instantly pushes that payload through the open connection directly to User B.

Zero wasted requests. Zero artificial delay. True real-time communication.

3. Laravel Real-Time Options

Historically, achieving this in Laravel meant making a tough choice.

For years, the standard approach was relying on third-party SaaS platforms like Pusher. While incredibly easy to set up, third-party services can become prohibitively expensive as your concurrent connections and daily message limits scale up.

If you wanted to self-host to save costs, you had to venture outside the PHP ecosystem. You might have used Laravel WebSockets (which required running a long-lived PHP process that wasn't natively optimized for it and is now mostly abandoned).

Then came Laravel Reverb.

Introduced as a first-party package, Reverb is a blazing-fast, highly scalable WebSocket server written entirely in PHP using ReactPHP. It integrates perfectly with Laravel's existing broadcasting system.

4. Setting Up Reverb and Broadcasting

Since we are using Laravel 12, installing and configuring Reverb is incredibly streamlined. Laravel 12 doesn't enable broadcasting by default, but it provides a single, powerful Artisan command to scaffold everything we need.

# Install Broadcasting + Reverb + Node dependencies (Pusher, Echo)
php artisan install:broadcasting

INFO  Published 'broadcasting' configuration file.
INFO  Published 'channels' route file.

┌ Which broadcasting driver would you like to use? ────────────┐
│ Laravel Reverb                                               │
└──────────────────────────────────────────────────────────────┘

┌ Would you like to install Laravel Reverb? ───────────────────┐
│ Yes                                                          │
└──────────────────────────────────────────────────────────────┘

┌ Would you like to install and build the Node dependencies required for broadcasting? ┐
│ Yes                                                                                   │
└───────────────────────────────────────────────────────────────────────────────────────┘

If you check your .env file, you'll see Laravel has automatically generated the keys for your local Reverb server:

BROADCAST_CONNECTION=reverb

REVERB_APP_ID=your_generated_id
REVERB_APP_KEY=your_generated_key
REVERB_APP_SECRET=your_generated_secret
REVERB_HOST="localhost"
REVERB_PORT=8080
REVERB_SCHEME=http

VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="${REVERB_HOST}"
VITE_REVERB_PORT="${REVERB_PORT}"
VITE_REVERB_SCHEME="${REVERB_SCHEME}"

Now spin up the actual WebSocket server. Open a new terminal tab and run:

php artisan reverb:start

🔥 You now have a blazing-fast, self-hosted WebSocket server running on port 8080.

5. Building the Chat System & Firing Events

The Data Layer

First, set up a simple Message model linked to our User.

php artisan make:model Message -m

In your migration, keep it lean — just the essentials:

Schema::create('messages', function (Blueprint $table) {
    $table->id();
    $table->foreignId('sender_id')->constrained('users');
    $table->foreignId('receiver_id')->constrained('users');
    $table->text('body');
    $table->timestamps();
});

The Broadcast Event

Generate an event that Laravel will automatically push to Reverb.

php artisan make:event MessageSent

Implement the ShouldBroadcastNow interface to tell Laravel to skip the queue and push the payload to Reverb immediately.

class MessageSent implements ShouldBroadcastNow
{
    use Dispatchable, SerializesModels;

    public function __construct(public Message $message) {}

    // Securing the channel so only the receiver user can listen
    public function broadcastOn(): Channel
    {
        return new PrivateChannel('chat.' . $this->message->receiver_id);
    }
}

⚠️ In high traffic, use the ShouldBroadcast interface instead — this lets queue workers handle broadcasting so the server can respond immediately.

Securing Private Channels

Open routes/channels.php and add:

use Illuminate\Support\Facades\Broadcast;

Broadcast::channel('chat.{userId}', function ($user, $userId) {
    return (int) $user->id === (int) $userId;
});

This ensures:

Only the authenticated user can listen to their own private chat channel
No user can subscribe to another user's channel

Without this, Laravel will reject the WebSocket subscription.

Firing the Event

When a user submits a new message via your controller, save it to the database and fire the event:

public function store(Request $request)
{
    $message = Message::create([
        'sender_id'   => $request->user()->id,
        'receiver_id' => $request->receiver_id,
        'body'        => $request->body,
    ]);

    // This sends the pulse ONLY to the receiver's private channel
    broadcast(new MessageSent($message))->toOthers();

    return response()->json($message);
}

That's it for the backend — Reverb is now catching that event and blasting it out to the connected WebSocket client on the chat.{receiverId} channel.

6. Catching the Event & Updating the UI in Real-Time

The backend is now broadcasting events through Reverb. But broadcasting alone does nothing unless the frontend is actively listening. This is where Laravel Echo comes into play.

Configuring Echo

// resources/js/bootstrap.js
import Echo from 'laravel-echo';
import Pusher from 'pusher-js';
window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'reverb',
    key: import.meta.env.VITE_REVERB_APP_KEY,
    wsHost: import.meta.env.VITE_REVERB_HOST,
    wsPort: import.meta.env.VITE_REVERB_PORT ?? 80,
    wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,
    forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'http') === 'https',
    enabledTransports: ['ws', 'wss'],
});

key → Must match your REVERB_APP_KEY
wsHost and wsPort → Point to your Reverb server
forceTLS → Automatically switches to wss:// in production

At this point, the browser will establish a persistent WebSocket connection to the Reverb server as soon as your app loads.

Listening to the Private Channel

const userId = window.App.user.id;

window.Echo.private(`chat.${userId}`)
    .listen('MessageSent', (event) => {
        console.log('New message received:', event.message);
        appendMessage(event.message);
    });

No polling. No intervals. No repeated API calls. The client is now simply listening.

Updating the UI

function appendMessageToUI(message) {
    const chatBox = document.getElementById('chat-box');
    const messageElement = document.createElement('div');
    messageElement.classList.add('message');
    messageElement.innerText = message.body;
    chatBox.appendChild(messageElement);
}

The moment MessageSent is broadcast:

Reverb pushes it to the browser
Echo catches it
Your callback executes
The DOM updates instantly

7. Real Metrics: Before vs After

When migrating from polling to WebSockets, the improvement isn't theoretical — it's measurable. The comparison below is based on 80 concurrent users.

Metric	Polling	WebSockets (Reverb)
HTTP Requests/min	~1,600	~0 (persistent connection)
Message Latency	Up to 3 seconds	Near-instant
Server Load	High (constant requests)	Low (event-driven)
Multi-tab Behavior	Degrades quickly	Stable

8. Real-World Use Cases Beyond Chat

This architecture is not limited to messaging. Once WebSockets are in place, you unlock powerful capabilities:

🔔 Live Notifications — Instant alerts without refreshing the page
📊 Real-Time Dashboards — Admin panels that update metrics instantly
📦 Order Tracking — Delivery status updates pushed in real-time
🧠 Live Analytics — Active user counters, sales metrics, traffic monitoring
🏭 IoT Monitoring — Devices pushing sensor data instantly to dashboards

Any system where "something happens" and users must see it immediately is a perfect candidate.

9. Final Thoughts

Rebuilding the chat system was only half the journey.

Moving from polling to WebSockets solved the performance and latency problems — but running WebSockets in production introduces new challenges:

Reverse proxy configuration
SSL termination (wss://)
Process supervision
Firewall rules
Scaling strategy

In Part 2, I'll walk through how to deploy Laravel Reverb in production behind Nginx — including the exact configuration, common pitfalls, and issues you may encounter along the way.

🔗 Stay Connected

Follow me for more Laravel tutorials, dev tips, deployment workflows and solving real-world production headaches.

Follow me on LinkedIn
Follow me here on Medium and join my mailing list
Follow me here on Dev.to for more in-depth content and tutorials!

Found this article useful?

🙏 Show your support by clapping 👏, subscribing 🔔, sharing to social networks

DeepTrack CLI: Gamify Your Learning with AI 🎯 | GitHub Copilot CLI Challenge

HoudaifaDevBS — Sat, 14 Feb 2026 14:45:43 +0000

This is a submission for the GitHub Copilot CLI Challenge

What I Built

I built DeepTrack CLI, a minimal AI-inspired learning tracker that helps me turn my learning into daily quizzes and track progress with gamification elements like XP, levels, streaks, and badges.

As a developer, I consume a lot of articles, videos, and tutorials, but I realized that reading alone isn’t enough — I needed a system to reinforce knowledge and make learning fun. DeepTrack CLI is my solution: a terminal-first tool that generates quizzes, tracks my performance, and highlights my weak topics, giving me a clear path to focus each day.

This project is especially meaningful because it reflects how AI-assisted development can accelerate building useful tools while keeping workflows minimal and practical.

Demo

GitHub Repository: houdaifaboucenna/deeptrack-CLI

Here is a look at DeepTrack in action:

A robust CLI interface to manage your learning journey: The CLI comes packed with commands to learn new topics, take a daily challenge, or check your leaderboard.

Interactive, AI-Generated Quizzes: Taking a quiz on Laravel Queues. The CLI instantly grades your answers, updates your stats, and awards badges based on your performance.

The Web Dashboard: Because staring at the terminal isn't always what we want, DeepTrack can generate a clean dashboard to visualize your overall statistics, track your top topics, and review your mastery levels.

My Experience with GitHub Copilot CLI

I relied heavily on GitHub Copilot CLI throughout development:

Generating project scaffolding: I asked Copilot to create the folder structure, CLI commands, and basic service files.

Writing core logic: Copilot suggested code for quiz generation, gamification calculations, and weakest-topic analysis, which I refined manually.

Refactoring & explanations: I used Copilot to review functions and suggest improvements, ensuring clean, readable, and maintainable code.

Workflow acceleration: Tasks that usually take hours — like creating the CLI commands or service skeletons — were completed in minutes, letting me focus on design and usability instead of boilerplate code.

This submission showcases how Copilot CLI can act as a true pair programmer, especially in small, high-impact projects

I wrote a step-by-step tutorial, sharing my solution for ZERO-DOWNTIME deployment of a Laravel app in a VPS / EC2 environment with Github Actions https://dev.to/houdaifa360/deploy-laravel-to-vps-with-github-actions-zero-downtime-cicd-f3

HoudaifaDevBS — Tue, 10 Feb 2026 21:13:37 +0000

Deploy Laravel to VPS with GitHub Actions (Zero Downtime CI/CD) - DEV Community

Deploying a Laravel application to a freshly created VPS can quickly become overwhelming. There are...

dev.to

Deploy Laravel to VPS with GitHub Actions (Zero Downtime CI/CD)

HoudaifaDevBS — Tue, 10 Feb 2026 16:15:10 +0000

Deploying a Laravel application to a freshly created VPS can quickly become overwhelming. There are many ways to put a web application online, and it's easy to lose focus trying to build the "perfect" deployment workflow — only to end up with something hard to maintain.

In real projects, what matters most is a reliable, repeatable, and safe deployment process that lets you focus on writing code rather than manually pushing changes to servers.

In this article, I'll walk through a minimal yet production-ready CI/CD approach for deploying Laravel applications to a VPS (or EC2 instance) using GitHub Actions and SSH.

⚠️ The goal is not to cover every possible optimization, but to present a workflow that works well for real client projects and personal products.

💡 Not on a VPS yet? This guide focuses on automated deployment for servers where you have full root privileges. If you are stuck with Shared Hosting (cPanel) and don't have SSH access, check out my alternative guide: 👉 How to Deploy Laravel on Shared Hosting (No SSH Required)

Stack Used

To keep things concrete, this guide assumes the following setup:

Ubuntu Server (20.04+)
Laravel 12 with PHP 8.3
Nginx + PHP-FPM
MySQL
GitHub Actions for CI/CD

This guide assumes basic familiarity with Linux and Laravel.

Step 1 — Installing Server Requirements

After connecting to your server via SSH, it's recommended not to work as root, but as a sudo-enabled user.

The key idea here is that this setup is done once. After the initial server preparation, deployments should not require installing system dependencies again.

# Update system list and upgrade packages  
sudo apt update && sudo apt upgrade -y  

# Install Nginx  
sudo apt install nginx -y  

# Install Mysql Server  
sudo apt install mysql-server -y  

# Install PHP and required Packages  
sudo apt install php-cli php-fpm php-mysql php-xml php-mbstring php-curl unzip -y  

# Install Composer   
sudo curl -sS https://getcomposer.org/installer | php  
sudo mv composer.phar /usr/local/bin/composer  

# Install Node.js and NPM  
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -  
sudo apt install -y nodejs

⚠️ Be careful to install a PHP version that matches your Laravel version requirements. Mismatches here are a common source of production issues.

Step 2 — Configuring Nginx for Laravel

We need to configure Nginx to point to the current/public directory (which we will create later via our CI/CD pipeline). Let's create configs:

sudo touch /etc/nginx/sites-available/laravel-app

server {  
    listen 80;  
    server_name your-domain.com;  

    # POINT TO 'current/public' FOR ATOMIC DEPLOYMENTS  
    root /var/www/laravel-app/current/public;  

    add_header X-Frame-Options "SAMEORIGIN";  
    add_header X-Content-Type-Options "nosniff";  

    index index.php;  
    charset utf-8;  

    location / {  
        try_files $uri $uri/ /index.php?$query_string;  
    }  

    location = /favicon.ico { access_log off; log_not_found off; }  
    location = /robots.txt  { access_log off; log_not_found off; }  

    error_page 404 /index.php;  

    location ~ \.php$ {  
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;  
        fastcgi_index index.php;  
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;  
        include fastcgi_params;  
    }  

    location ~ /\.(?!well-known).* {  
        deny all;  
    }  
}

Then, we enable the configuration and ensure it is working:

sudo ln -s /etc/nginx/sites-available/laravel-app /etc/nginx/sites-enabled/  
sudo unlink /etc/nginx/sites-enabled/default  
sudo nginx -t  
sudo systemctl restart nginx

⚠️ Replace your-domain.com with your actual domain.

Step 3 — Set up MySQL server and create a database

Let's execute the MySQL security script:

# Secure MySQL (set root password, remove anonymous users)  
sudo mysql_secure_installation  

# Log in to MySQL  
sudo mysql -u root -p

Then, we create the application database that we will use:

CREATE DATABASE laravel_db;  
CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY 'your-strong-password';  
GRANT ALL PRIVILEGES ON laravel_db.* TO 'laravel_user'@'localhost';  
FLUSH PRIVILEGES;  
EXIT;

Once created, we should add the database access in the production .env

⚠️ The .env is never committed to Git and is created only once on the server. CI/CD pipelines should never modify it.

Step 4 — Initializing the Application on the Server

Before automation, we need to set up the folder structure. We will create a "shared" structure so that logs and uploads persist between deployments.

# 1. Create the main directory  
sudo mkdir -p /var/www/laravel-app  
sudo chown -R $USER:www-data /var/www/laravel-app  

# 2. Setup the persistent folders  
cd /var/www/laravel-app  
mkdir -p shared/storage/framework/{cache/data,sessions,views}  

# 3. Create the .env file  
nano shared/.env  
# (Paste your production env content here)  

# 4. Set permissions ONE TIME  
sudo chown -R $USER:www-data /var/www/laravel-app  
sudo chmod -R 775 shared/storage

Step 5 — CI/CD Strategy with GitHub Actions

Instead of running Composer and NPM commands directly on the server, the deployment workflow follows a build-then-deploy strategy:

Why build in CI instead of the server?

Faster deployments
More predictable results
Fewer production dependencies
Easier debugging
Reduced server load

In this approach:

GitHub Actions installs PHP and Node
Composer dependencies are installed
Frontend assets are built
A clean release artifact is generated
The artifact is deployed to the server via SSH
A new release directory is created
The current symlink is updated atomically

The server becomes a stable runtime environment, not a build machine.

Create .github/workflows/deploy.yml in your Laravel project:

name: Deploy Laravel to VPS  

on:  
  push:  
    branches: [ main ]  

jobs:  
  deploy:  
    runs-on: ubuntu-latest  

    steps:  
    # 1️⃣ Checkout Code  
    - name: Checkout repository  
      uses: actions/checkout@v4  

    # 2️⃣ Setup PHP  
    - name: Setup PHP  
      uses: shivammathur/setup-php@v2  
      with:  
        php-version: 8.3  
        extensions: mbstring, xml, ctype, iconv, intl, pdo_mysql  

    # 3️⃣ Install Backend Dependencies  
    - name: Install Composer dependencies  
      run: |  
        composer install --no-dev --prefer-dist --optimize-autoloader  

    # 4️⃣ Build Frontend Assets  
    - name: Setup Node & Build  
      uses: actions/setup-node@v4  
      with:  
        node-version: 20  
    - run: |  
        npm ci  
        npm run build  

    # 5️⃣ Prepare Files for Transfer  
    - name: Archive application  
      run: |  
        tar --exclude='./storage' \  
            --exclude='./.git' \  
            --exclude='./node_modules' \  
            --exclude='./tests' \  
            -czf /tmp/release.tar.gz .  

        # 2. Move it back to the workspace  
        mv /tmp/release.tar.gz .  

    # 6️⃣ Upload to Server  
    - name: Upload artifact via SCP  
      uses: appleboy/scp-action@master  
      with:  
        host: ${{ secrets.VPS_HOST }}  
        username: ${{ secrets.VPS_USERNAME }}  
        key: ${{ secrets.VPS_SSH_KEY }}  
        port: ${{ secrets.VPS_PORT || 22 }}  
        source: "release.tar.gz"  
        target: "/var/www/laravel-app"  

    # 7️⃣ Deploy on Server  
    - name: Execute Remote SSH Commands  
      uses: appleboy/ssh-action@master  
      with:  
        host: ${{ secrets.VPS_HOST }}  
        username: ${{ secrets.VPS_USERNAME }}  
        key: ${{ secrets.VPS_SSH_KEY }}  
        port: ${{ secrets.VPS_PORT || 22 }}  
        script: |  
          set -e  

          APP_DIR="/var/www/laravel-app"  
          RELEASE_ID=$(date +%Y%m%d%H%M%S)  
          RELEASE_PATH="$APP_DIR/releases/$RELEASE_ID"  

          # 1. Create new release directory  
          mkdir -p $RELEASE_PATH  

          # 2. Extract files  
          tar -xzf $APP_DIR/release.tar.gz -C $RELEASE_PATH  
          rm $APP_DIR/release.tar.gz  

          # 3. Link Shared Resources  
          ln -sfn $APP_DIR/shared/.env $RELEASE_PATH/.env  
          ln -sfn $APP_DIR/shared/storage $RELEASE_PATH/storage  

          # 4. Set Permissions  
          sudo chown -R $USER:www-data $RELEASE_PATH  

          # Ensure group write access for cache (so webserver can write to it)  
          sudo chmod -R 775 $RELEASE_PATH/bootstrap/cache  

          # 5. Run Migrations & Storage Link & Optimize & Reload
          cd $RELEASE_PATH
          php artisan migrate --force
          php artisan storage:link
          php artisan optimize
          php artisan reload

          # 6. Atomic Switch (Zero Downtime)  
          ln -sfn $RELEASE_PATH $APP_DIR/current  

          # 7. Reload PHP-FPM (Ensure this matches your server version!)  
          sudo systemctl reload php8.3-fpm  

          # 8. Cleanup old releases (keep latest 5)   
          cd $APP_DIR/releases  
          ls -t | tail -n +6 | xargs -r rm -rf  

          echo "🚀 Deployment $RELEASE_ID success!"

In your GitHub repository:

Go to Settings → Secrets and variables → Actions
Add these secrets:
- VPS_HOST: Your VPS IP address
- VPS_USERNAME: SSH username
- VPS_SSH_KEY: Private SSH key
- VPS_PORT: SSH port (default: 22)

Step 6 — Release-Based Deployment Flow

Each deployment creates a new release directory:

/var/www/laravel-app/releases/20260210151258

Shared directories such as storage and bootstrap/cache are symlinked into each release.

Once everything is ready:

Database migrations are executed with --force
Caches are optimized
The current symlink is switched to the new release

⚡ Because the symlink update is atomic, users rarely notice downtime.

Troubleshooting Common Issues

500 Internal Server Error

Most commonly caused by:

Incorrect file permissions
Missing PHP extensions
Wrong PHP-FPM socket version
Broken symlink paths

Check that storage/ and bootstrap/cache/ are writable.

Blank Page After Deployment

Often caused by:

Incorrect Nginx root path
Missing .env
Application key not generated

Make sure:

APP_ENV=production  
APP_DEBUG=false

SSH Action Fails

Usually due to:

Incorrect private key format
Wrong SSH username
Server firewall rules

Test SSH access manually before debugging CI.

Final Thoughts

This setup gives you a professional, automated pipeline. You push to main, and GitHub Actions handles the rest — running tests, building assets, and switching the live site without dropping connections.

Happy Deploying! 🚀

🔗 Stay Connected

Follow me for more Laravel tutorials, dev tips, deployment workflows and solving real-world production headaches.

Follow me on LinkedIn
Follow me here on Medium and join my mailing list for more in-depth content and tutorials!

Found this article useful?

🙏 Show your support by clapping 👏, subscribing 🔔, sharing to social networks

Tags: Laravel, VPS, GitHub Actions, CI/CD, Nginx

Step 1 — Installing Server Requirements

After connecting to your server via SSH, it's recommended not to work as root, but as a sudo-enabled user.

The key idea here is that this setup is done once. After the initial server preparation, deployments should not require installing system dependencies again.

# Update system list and upgrade packages  
sudo apt update && sudo apt upgrade -y  

# Install Nginx  
sudo apt install nginx -y  

# Install Mysql Server  
sudo apt install mysql-server -y  

# Install PHP and required Packages  
sudo apt install php-cli php-fpm php-mysql php-xml php-mbstring php-curl unzip -y  

# Install Composer   
sudo curl -sS https://getcomposer.org/installer | php  
sudo mv composer.phar /usr/local/bin/composer  

# Install Node.js and NPM  
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -  
sudo apt install -y nodejs

⚠️ Be careful to install a PHP version that matches your Laravel version requirements. Mismatches here are a common source of production issues.

Step 2 — Configuring Nginx for Laravel

We need to configure Nginx to point to the current/public directory (which we will create later via our CI/CD pipeline). Let's create configs:

sudo touch /etc/nginx/sites-available/laravel-app

server {  
    listen 80;  
    server_name your-domain.com;  

    # POINT TO 'current/public' FOR ATOMIC DEPLOYMENTS  
    root /var/www/laravel-app/current/public;  

    add_header X-Frame-Options "SAMEORIGIN";  
    add_header X-Content-Type-Options "nosniff";  

    index index.php;  
    charset utf-8;  

    location / {  
        try_files $uri $uri/ /index.php?$query_string;  
    }  

    location = /favicon.ico { access_log off; log_not_found off; }  
    location = /robots.txt  { access_log off; log_not_found off; }  

    error_page 404 /index.php;  

    location ~ \.php$ {  
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;  
        fastcgi_index index.php;  
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;  
        include fastcgi_params;  
    }  

    location ~ /\.(?!well-known).* {  
        deny all;  
    }  
}

Then, we enable the configuration and ensure it is working:

sudo ln -s /etc/nginx/sites-available/laravel-app /etc/nginx/sites-enabled/  
sudo unlink /etc/nginx/sites-enabled/default  
sudo nginx -t  
sudo systemctl restart nginx

⚠️ Replace your-domain.com with your actual domain.

Step 3 — Set up MySQL server and create a database

Let's execute the MySQL security script:

# Secure MySQL (set root password, remove anonymous users)  
sudo mysql_secure_installation  

# Log in to MySQL  
sudo mysql -u root -p

Then, we create the application database that we will use:

CREATE DATABASE laravel_db;  
CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY 'your-strong-password';  
GRANT ALL PRIVILEGES ON laravel_db.* TO 'laravel_user'@'localhost';  
FLUSH PRIVILEGES;  
EXIT;

Once created, we should add the database access in the production .env

⚠️ The .env is never committed to Git and is created only once on the server. CI/CD pipelines should never modify it.

Step 4 — Initializing the Application on the Server

Before automation, we need to set up the folder structure. We will create a "shared" structure so that logs and uploads persist between deployments.

# 1. Create the main directory  
sudo mkdir -p /var/www/laravel-app  
sudo chown -R $USER:www-data /var/www/laravel-app  

# 2. Setup the persistent folders  
cd /var/www/laravel-app  
mkdir -p shared/storage/framework/{cache/data,sessions,views}  

# 3. Create the .env file  
nano shared/.env  
# (Paste your production env content here)  

# 4. Set permissions ONE TIME  
sudo chown -R $USER:www-data /var/www/laravel-app  
sudo chmod -R 775 shared/storage

Step 5 — CI/CD Strategy with GitHub Actions

Instead of running Composer and NPM commands directly on the server, the deployment workflow follows a build-then-deploy strategy:

Why build in CI instead of the server?

Faster deployments
More predictable results
Fewer production dependencies
Easier debugging
Reduced server load

In this approach:

GitHub Actions installs PHP and Node
Composer dependencies are installed
Frontend assets are built
A clean release artifact is generated
The artifact is deployed to the server via SSH
A new release directory is created
The current symlink is updated atomically

The server becomes a stable runtime environment, not a build machine.

Create .github/workflows/deploy.yml in your Laravel project:

name: Deploy Laravel to VPS  

on:  
  push:  
    branches: [ main ]  

jobs:  
  deploy:  
    runs-on: ubuntu-latest  

    steps:  
    # 1️⃣ Checkout Code  
    - name: Checkout repository  
      uses: actions/checkout@v4  

    # 2️⃣ Setup PHP  
    - name: Setup PHP  
      uses: shivammathur/setup-php@v2  
      with:  
        php-version: 8.3  
        extensions: mbstring, xml, ctype, iconv, intl, pdo_mysql  

    # 3️⃣ Install Backend Dependencies  
    - name: Install Composer dependencies  
      run: |  
        composer install --no-dev --prefer-dist --optimize-autoloader  

    # 4️⃣ Build Frontend Assets  
    - name: Setup Node & Build  
      uses: actions/setup-node@v4  
      with:  
        node-version: 20  
    - run: |  
        npm ci  
        npm run build  

    # 5️⃣ Prepare Files for Transfer  
    - name: Archive application  
      run: |  
        tar --exclude='./storage' \  
            --exclude='./.git' \  
            --exclude='./node_modules' \  
            --exclude='./tests' \  
            -czf /tmp/release.tar.gz .  

        # 2. Move it back to the workspace  
        mv /tmp/release.tar.gz .  

    # 6️⃣ Upload to Server  
    - name: Upload artifact via SCP  
      uses: appleboy/scp-action@master  
      with:  
        host: ${{ secrets.VPS_HOST }}  
        username: ${{ secrets.VPS_USERNAME }}  
        key: ${{ secrets.VPS_SSH_KEY }}  
        port: ${{ secrets.VPS_PORT || 22 }}  
        source: "release.tar.gz"  
        target: "/var/www/laravel-app"  

    # 7️⃣ Deploy on Server  
    - name: Execute Remote SSH Commands  
      uses: appleboy/ssh-action@master  
      with:  
        host: ${{ secrets.VPS_HOST }}  
        username: ${{ secrets.VPS_USERNAME }}  
        key: ${{ secrets.VPS_SSH_KEY }}  
        port: ${{ secrets.VPS_PORT || 22 }}  
        script: |  
          set -e  

          APP_DIR="/var/www/laravel-app"  
          RELEASE_ID=$(date +%Y%m%d%H%M%S)  
          RELEASE_PATH="$APP_DIR/releases/$RELEASE_ID"  

          # 1. Create new release directory  
          mkdir -p $RELEASE_PATH  

          # 2. Extract files  
          tar -xzf $APP_DIR/release.tar.gz -C $RELEASE_PATH  
          rm $APP_DIR/release.tar.gz  

          # 3. Link Shared Resources  
          ln -sfn $APP_DIR/shared/.env $RELEASE_PATH/.env  
          ln -sfn $APP_DIR/shared/storage $RELEASE_PATH/storage  

          # 4. Set Permissions  
          sudo chown -R $USER:www-data $RELEASE_PATH  

          # Ensure group write access for cache (so webserver can write to it)  
          sudo chmod -R 775 $RELEASE_PATH/bootstrap/cache  

          # 5. Run Migrations & Optimize  
          cd $RELEASE_PATH  
          php artisan migrate --force  
          php artisan optimize  

          # 6. Atomic Switch (Zero Downtime)  
          ln -sfn $RELEASE_PATH $APP_DIR/current  

          # 7. Reload PHP-FPM (Ensure this matches your server version!)  
          sudo systemctl reload php8.3-fpm  

          # 8. Cleanup old releases (keep latest 5)   
          cd $APP_DIR/releases  
          ls -t | tail -n +6 | xargs -r rm -rf  

          echo "🚀 Deployment $RELEASE_ID success!"

In your GitHub repository:

Go to Settings → Secrets and variables → Actions
Add these secrets:
- VPS_HOST: Your VPS IP address
- VPS_USERNAME: SSH username
- VPS_SSH_KEY: Private SSH key
- VPS_PORT: SSH port (default: 22)

Step 6 — Release-Based Deployment Flow

Each deployment creates a new release directory:

/var/www/laravel-app/releases/20260210151258

Shared directories such as storage and bootstrap/cache are symlinked into each release.

Once everything is ready:

Database migrations are executed with --force
Caches are optimized
The current symlink is switched to the new release

⚡ Because the symlink update is atomic, users rarely notice downtime.

Troubleshooting Common Issues

500 Internal Server Error

Most commonly caused by:

Incorrect file permissions
Missing PHP extensions
Wrong PHP-FPM socket version
Broken symlink paths

Check that storage/ and bootstrap/cache/ are writable.

Blank Page After Deployment

Often caused by:

Incorrect Nginx root path
Missing .env
Application key not generated

Make sure:

APP_ENV=production  
APP_DEBUG=false

SSH Action Fails

Usually due to:

Incorrect private key format
Wrong SSH username
Server firewall rules

Test SSH access manually before debugging CI.

Final Thoughts

Happy Deploying! 🚀

🔗 Stay Connected

Follow me for more Laravel tutorials, dev tips, deployment workflows and solving real-world production headaches.

Follow me on LinkedIn
Follow me here on Medium and join my mailing list for more in-depth content and tutorials!

Found this article useful?

🙏 Show your support by clapping 👏, subscribing 🔔, sharing to social networks

Tags: Laravel, VPS, GitHub Actions, CI/CD, Nginx

Step 1 — Installing Server Requirements

After connecting to your server via SSH, it's recommended not to work as root, but as a sudo-enabled user.

The key idea here is that this setup is done once. After the initial server preparation, deployments should not require installing system dependencies again.

# Update system list and upgrade packages  
sudo apt update && sudo apt upgrade -y  

# Install Nginx  
sudo apt install nginx -y  

# Install Mysql Server  
sudo apt install mysql-server -y  

# Install PHP and required Packages  
sudo apt install php-cli php-fpm php-mysql php-xml php-mbstring php-curl unzip -y  

# Install Composer   
sudo curl -sS https://getcomposer.org/installer | php  
sudo mv composer.phar /usr/local/bin/composer  

# Install Node.js and NPM  
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -  
sudo apt install -y nodejs

⚠️ Be careful to install a PHP version that matches your Laravel version requirements. Mismatches here are a common source of production issues.

Step 2 — Configuring Nginx for Laravel

We need to configure Nginx to point to the current/public directory (which we will create later via our CI/CD pipeline). Let's create configs:

sudo touch /etc/nginx/sites-available/laravel-app

server {  
    listen 80;  
    server_name your-domain.com;  

    # POINT TO 'current/public' FOR ATOMIC DEPLOYMENTS  
    root /var/www/laravel-app/current/public;  

    add_header X-Frame-Options "SAMEORIGIN";  
    add_header X-Content-Type-Options "nosniff";  

    index index.php;  
    charset utf-8;  

    location / {  
        try_files $uri $uri/ /index.php?$query_string;  
    }  

    location = /favicon.ico { access_log off; log_not_found off; }  
    location = /robots.txt  { access_log off; log_not_found off; }  

    error_page 404 /index.php;  

    location ~ \.php$ {  
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;  
        fastcgi_index index.php;  
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;  
        include fastcgi_params;  
    }  

    location ~ /\.(?!well-known).* {  
        deny all;  
    }  
}

Then, we enable the configuration and ensure it is working:

sudo ln -s /etc/nginx/sites-available/laravel-app /etc/nginx/sites-enabled/  
sudo unlink /etc/nginx/sites-enabled/default  
sudo nginx -t  
sudo systemctl restart nginx

⚠️ Replace your-domain.com with your actual domain.

Step 3 — Set up MySQL server and create a database

Let's execute the MySQL security script:

# Secure MySQL (set root password, remove anonymous users)  
sudo mysql_secure_installation  

# Log in to MySQL  
sudo mysql -u root -p

Then, we create the application database that we will use:

CREATE DATABASE laravel_db;  
CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY 'your-strong-password';  
GRANT ALL PRIVILEGES ON laravel_db.* TO 'laravel_user'@'localhost';  
FLUSH PRIVILEGES;  
EXIT;

Once created, we should add the database access in the production .env

⚠️ The .env is never committed to Git and is created only once on the server. CI/CD pipelines should never modify it.

Step 4 — Initializing the Application on the Server

Before automation, we need to set up the folder structure. We will create a "shared" structure so that logs and uploads persist between deployments.

# 1. Create the main directory  
sudo mkdir -p /var/www/laravel-app  
sudo chown -R $USER:www-data /var/www/laravel-app  

# 2. Setup the persistent folders  
cd /var/www/laravel-app  
mkdir -p shared/storage/framework/{cache/data,sessions,views}  

# 3. Create the .env file  
nano shared/.env  
# (Paste your production env content here)  

# 4. Set permissions ONE TIME  
sudo chown -R $USER:www-data /var/www/laravel-app  
sudo chmod -R 775 shared/storage

Step 5 — CI/CD Strategy with GitHub Actions

Instead of running Composer and NPM commands directly on the server, the deployment workflow follows a build-then-deploy strategy:

Why build in CI instead of the server?

Faster deployments
More predictable results
Fewer production dependencies
Easier debugging
Reduced server load

In this approach:

GitHub Actions installs PHP and Node
Composer dependencies are installed
Frontend assets are built
A clean release artifact is generated
The artifact is deployed to the server via SSH
A new release directory is created
The current symlink is updated atomically

The server becomes a stable runtime environment, not a build machine.

Create .github/workflows/deploy.yml in your Laravel project:

name: Deploy Laravel to VPS  

on:  
  push:  
    branches: [ main ]  

jobs:  
  deploy:  
    runs-on: ubuntu-latest  

    steps:  
    # 1️⃣ Checkout Code  
    - name: Checkout repository  
      uses: actions/checkout@v4  

    # 2️⃣ Setup PHP  
    - name: Setup PHP  
      uses: shivammathur/setup-php@v2  
      with:  
        php-version: 8.3  
        extensions: mbstring, xml, ctype, iconv, intl, pdo_mysql  

    # 3️⃣ Install Backend Dependencies  
    - name: Install Composer dependencies  
      run: |  
        composer install --no-dev --prefer-dist --optimize-autoloader  

    # 4️⃣ Build Frontend Assets  
    - name: Setup Node & Build  
      uses: actions/setup-node@v4  
      with:  
        node-version: 20  
    - run: |  
        npm ci  
        npm run build  

    # 5️⃣ Prepare Files for Transfer  
    - name: Archive application  
      run: |  
        tar --exclude='./storage' \  
            --exclude='./.git' \  
            --exclude='./node_modules' \  
            --exclude='./tests' \  
            -czf /tmp/release.tar.gz .  

        # 2. Move it back to the workspace  
        mv /tmp/release.tar.gz .  

    # 6️⃣ Upload to Server  
    - name: Upload artifact via SCP  
      uses: appleboy/scp-action@master  
      with:  
        host: ${{ secrets.VPS_HOST }}  
        username: ${{ secrets.VPS_USERNAME }}  
        key: ${{ secrets.VPS_SSH_KEY }}  
        port: ${{ secrets.VPS_PORT || 22 }}  
        source: "release.tar.gz"  
        target: "/var/www/laravel-app"  

    # 7️⃣ Deploy on Server  
    - name: Execute Remote SSH Commands  
      uses: appleboy/ssh-action@master  
      with:  
        host: ${{ secrets.VPS_HOST }}  
        username: ${{ secrets.VPS_USERNAME }}  
        key: ${{ secrets.VPS_SSH_KEY }}  
        port: ${{ secrets.VPS_PORT || 22 }}  
        script: |  
          set -e  

          APP_DIR="/var/www/laravel-app"  
          RELEASE_ID=$(date +%Y%m%d%H%M%S)  
          RELEASE_PATH="$APP_DIR/releases/$RELEASE_ID"  

          # 1. Create new release directory  
          mkdir -p $RELEASE_PATH  

          # 2. Extract files  
          tar -xzf $APP_DIR/release.tar.gz -C $RELEASE_PATH  
          rm $APP_DIR/release.tar.gz  

          # 3. Link Shared Resources  
          ln -sfn $APP_DIR/shared/.env $RELEASE_PATH/.env  
          ln -sfn $APP_DIR/shared/storage $RELEASE_PATH/storage  

          # 4. Set Permissions  
          sudo chown -R $USER:www-data $RELEASE_PATH  

          # Ensure group write access for cache (so webserver can write to it)  
          sudo chmod -R 775 $RELEASE_PATH/bootstrap/cache  

          # 5. Run Migrations & Optimize  
          cd $RELEASE_PATH  
          php artisan migrate --force  
          php artisan optimize  

          # 6. Atomic Switch (Zero Downtime)  
          ln -sfn $RELEASE_PATH $APP_DIR/current  

          # 7. Reload PHP-FPM (Ensure this matches your server version!)  
          sudo systemctl reload php8.3-fpm  

          # 8. Cleanup old releases (keep latest 5)   
          cd $APP_DIR/releases  
          ls -t | tail -n +6 | xargs -r rm -rf  

          echo "🚀 Deployment $RELEASE_ID success!"

In your GitHub repository:

Go to Settings → Secrets and variables → Actions
Add these secrets:
- VPS_HOST: Your VPS IP address
- VPS_USERNAME: SSH username
- VPS_SSH_KEY: Private SSH key
- VPS_PORT: SSH port (default: 22)

Step 6 — Release-Based Deployment Flow

Each deployment creates a new release directory:

/var/www/laravel-app/releases/20260210151258

Shared directories such as storage and bootstrap/cache are symlinked into each release.

Once everything is ready:

Database migrations are executed with --force
Caches are optimized
The current symlink is switched to the new release

⚡ Because the symlink update is atomic, users rarely notice downtime.

Troubleshooting Common Issues

500 Internal Server Error

Most commonly caused by:

Incorrect file permissions
Missing PHP extensions
Wrong PHP-FPM socket version
Broken symlink paths

Check that storage/ and bootstrap/cache/ are writable.

Blank Page After Deployment

Often caused by:

Incorrect Nginx root path
Missing .env
Application key not generated

Make sure:

APP_ENV=production  
APP_DEBUG=false

SSH Action Fails

Usually due to:

Incorrect private key format
Wrong SSH username
Server firewall rules

Test SSH access manually before debugging CI.

Final Thoughts

Happy Deploying! 🚀

🔗 Stay Connected

Follow me for more Laravel tutorials, dev tips, deployment workflows and solving real-world production headaches.

Follow me on LinkedIn
Follow me here on Medium and join my mailing list
Follow me here on Dev.to for more in-depth content and tutorials!

Found this article useful?

🙏 Show your support by clapping 👏, subscribing 🔔, sharing to social networks

I wrote my first article here @dev.to, sharing my solution for deploying a Laravel app in a limited shared hosting environment without SSH access. I hope someone will find it useful, enjoy it, and leave a comment

HoudaifaDevBS — Sat, 07 Feb 2026 12:08:45 +0000

Deploying Laravel on Shared Hosting (No SSH Required) - DEV Community

Have you ever wondered if you can deploy a Laravel application on shared hosting without SSH? The...

dev.to

Deploying Laravel on Shared Hosting (No SSH Required)

HoudaifaDevBS — Sat, 07 Feb 2026 12:04:29 +0000

Have you ever wondered if you can deploy a Laravel application on shared hosting without SSH?

The answer is YES. I faced this exact situation during my early freelance journey: a client with a tight budget needed to see the first version of his Laravel website online before moving forward. The hosting environment had no SSH, no Composer, no Artisan, no NPM.

So I had to figure out a safe and reliable alternative.

In this article, I'll share the exact workflow I use to deploy Laravel applications on shared hosting without SSH access.

Why Laravel Deployment on Shared Hosting Is Different

1. Project File Structure

A typical Laravel project looks like this:

project/  
 ├── app/  
 ├── bootstrap/  
 ├── config/  
 ├── public/  
 ├── storage/  
 ├── vendor/  
 └── artisan

However, shared hosting usually exposes only one public directory:

├── public_html/

2. No SSH, No commands

If there is SSH access, obviously, there will be:

No composer dependencies can be installed
No asset building since we no longer have "npm run"
No migrations can be executed
No cache clearing or optimizing

How to solve the situation step-by-step

Step 1: Prepare Your Application Locally

First, I clone my Laravel project into a production-ready copy so I don't affect my development setup:

├── laravel_app/  
├── laravel_app_prod/

Inside laravel_app_prod, I prepare the application for production.

// clearing the cache  
php artisan config:clear  
php artisan cache:clear  
php artisan route:clear  
php artisan view:clear  

// installing production dependencies and optimize  
composer install --no-dev --optimize-autoloader  

// building frontend assets  
npm run build

Step 2 — Re-organize Project File Structure

To match shared hosting file structure, I move only public/ folder content inside the new public_html/ folder, like this:

public_html/  <-------------------|  
laravel_app_prod/                 |  
 ├── app/                         |  
 ├── bootstrap/                   |  
 ├── config/                      |  
 ├── public/ ---------------------|  
 ├── storage/             
 ├── vendor/              
 └── artisan

Step 3 — Fix Laravel Paths in index.php

Now, we should do one important step to make the app boot correctly, so we update the paths in public/index.php:

if (file_exists(  
    $maintenance = __DIR__ . '/../laravel_app_prod/storage/framework/maintenance.php')  
) {  
    require $maintenance;  
}  

require __DIR__ . '/../laravel_app_prod/vendor/autoload.php';  

(require_once __DIR__ . '/../laravel_app_prod/bootstrap/app.php')  
    ->handleRequest(Request::capture());

This is a critical step — incorrect paths will cause a 500 error.

Step 4 — Set Up The Database Using cPanel

From cPanel:

Open MySQL Database Wizard
Create a database
Create a database user
Assign the user ALL PRIVILEGES

Then update the .env file inside laravel_app_prod:

APP_NAME=MyApp  
APP_ENV=production  
APP_DEBUG=false          // very important (security)  
APP_URL=https://your-app-domain  

DB_DATABASE=database_name  
DB_USERNAME=database_user  
DB_PASSWORD=database_password  // (you already saved it)

⚠️ Never enable APP_DEBUG=true in production.

Step 5 — Temporary Deploy Route (Token Protected)

Coming to the important part, no SSH, no problem, we can temporarily execute Artisan commands via a protected web route.

⚠️ This route must be removed immediately after deployment.

Add a secret token to .env:

DEPLOY_TOKEN=verySecretRandomToken123

Add the route in routes/web.php:

use Illuminate\Support\Facades\Artisan;  
use Illuminate\Support\Facades\Route;  

Route::get('/deploy/{token}', function ($token) {  
  abort_unless($token === env('DEPLOY_TOKEN'), 403);  

  // 1. Run Migrations & Clear Cache  
  Artisan::call('migrate', ['--force' => true]);  
  Artisan::call('optimize:clear');  

  // 2. Fix Storage Link (The Custom Fix)  
  // We point to the 'public_html' folder using $_SERVER['DOCUMENT_ROOT']  
  $targetFolder = storage_path('app/public');  
  $linkFolder = $_SERVER['DOCUMENT_ROOT'] . '/storage';  

  if (!file_exists($linkFolder)) {  
    symlink($targetFolder, $linkFolder);  
    $storageStatus = 'Storage link created successfully.';  
  } else {  
    $storageStatus = 'Storage link already exists.';  
  }  

  return "Deployment completed.<br>" .  
      "Migrations run.<br>" .  
      "Cache cleared.<br>" .  
      $storageStatus;  
});

This ensures only someone with the correct token can trigger deployment.

Step 6 — Upload Files to the Server

Using cPanel File Manager:

Zip laravel_app_prod/
Zip the contents of public/
Upload:
- Put laravel_app_prod outside public_html
- Public files inside public_html

Then extract both archives.

Why did we put laravel_app_prod outside public_html?

This is a crucial security measure. By placing your core application logic, and most importantly your .env file, one level above the public directory, you ensure that they are physically impossible to access via a web browser.

Even if your server misconfigures and starts serving PHP files as text (which happens!), your credentials remain hidden because they live outside the public root.

Step 7 — Set Critical Permissions

Laravel requires write access to specific folders. If these aren't set, your logs won't write and sessions won't save.

In cPanel File Manager, navigate to laravel_app_prod/storage.
Right-click → Change Permissions.
Set to 775 (User: Read/Write/Execute, Group: Read/Write/Execute, World: Read/Execute).
Do the same for laravel_app_prod/bootstrap/cache.

🛑 Note: Never set folders to 777. It is a major security risk on shared hosting.

Step 8 — Run Migrations and Remove the Deploy Route

Open in the browser:

https://your-domain.com/deploy/verySecretRandomToken123

If everything is correct, you'll see:

Deployment completed successfully

Immediately after that:

❗ Delete the deploy route

❗ Remove DEPLOY_TOKEN from .env

This is critical for security.

Common Issues Faced

500 Internal Server Error

Incorrect file paths in index.php
Wrong PHP version (use cPanel MultiPHP Manager)
Incorrect folder permissions (storage 775, bootstrap/cache 775)

403 Unauthorized

Unmatched route token with DEPLOY_TOKEN

Final Thoughts

Shared hosting is not ideal for Laravel, but it's still very common for:

Client projects
MVPs
Budget-constrained deployments

With proper preparation and a secure workflow, Laravel applications can run reliably even without SSH access.

💡 Pro Tip: The Safer Database Alternative

If you are uncomfortable running migrations via a web route (which carries security risks), you can use the Export/Import method:

Run migrations on your local machine.
Export your local database as an .sql file using your local tool.
Go to cPanel > phpMyAdmin on the server.
Import the .sql file directly.

This is safer because it doesn't require executable logic in your production routes.

🔗 Stay Connected

Follow me for more Laravel tutorials, dev tips, deployment workflows and solving real-world production headaches.

Follow me on LinkedIn
Follow me here on Medium and join my mailing list for more in-depth content and tutorials!

Found this article useful?

🙏 Show your support by clapping 👏, subscribing 🔔, sharing to social networks

Forem: HoudaifaDevBS

From Slow Requests to Scalable Background Jobs with Laravel Queues & Horizon

Part 1 — The Problem (The Real One)

Part 2 — How Laravel Queues Work

Part 3 — Setting Up Redis & Queue Config

Install Redis

Install the Laravel Redis Package

Configure Your .env

Quick Sanity Check

Part 4 — Your First Real Job

Dispatch It From Your Controller

Part 5 — Real World Scenarios

Scenario A — Calling a Third-Party API (Slack, SMS, Webhooks)

Scenario B — Generating a PDF or Report on Demand

Scenario C — Processing a Bulk CSV Import

Part 6 — Handling Failures Like a Pro

Set Up the Failed Jobs Table

Retries, Timeouts & Backoff

The failed() Method

Managing Failed Jobs via CLI

ShouldBeUnique — Prevent Duplicate Jobs

Part 7 — Laravel Horizon

Install Horizon

Basic Configuration

Protect the Dashboard

Reading the Dashboard

Keep Horizon Running with Supervisor

Part 8 — Production Checklist

Redis

Jobs

Horizon

Supervisor

Sanity Check

Part 9 — Conclusion

To recap what we covered:

What's Next?

🔗 Stay Connected

From Polling to Real-Time: Building a Laravel 12 Chat with WebSockets & Reverb

1. Why Polling Fails at Scale

2. The WebSocket Solution: From Asking to Listening

3. Laravel Real-Time Options

4. Setting Up Reverb and Broadcasting

5. Building the Chat System & Firing Events

The Data Layer

The Broadcast Event

Securing Private Channels

Firing the Event

6. Catching the Event & Updating the UI in Real-Time

Configuring Echo

Listening to the Private Channel

Updating the UI

7. Real Metrics: Before vs After

8. Real-World Use Cases Beyond Chat

9. Final Thoughts

🔗 Stay Connected

DeepTrack CLI: Gamify Your Learning with AI 🎯 | GitHub Copilot CLI Challenge

What I Built

Demo

My Experience with GitHub Copilot CLI

I wrote a step-by-step tutorial, sharing my solution for ZERO-DOWNTIME deployment of a Laravel app in a VPS / EC2 environment with Github Actions https://dev.to/houdaifa360/deploy-laravel-to-vps-with-github-actions-zero-downtime-cicd-f3

Deploy Laravel to VPS with GitHub Actions (Zero Downtime CI/CD) - DEV Community

Deploy Laravel to VPS with GitHub Actions (Zero Downtime CI/CD)

Stack Used

Step 1 — Installing Server Requirements

Step 2 — Configuring Nginx for Laravel

Step 3 — Set up MySQL server and create a database

Step 4 — Initializing the Application on the Server

Step 5 — CI/CD Strategy with GitHub Actions

Why build in CI instead of the server?

Step 6 — Release-Based Deployment Flow

Troubleshooting Common Issues

500 Internal Server Error

Blank Page After Deployment

SSH Action Fails

Final Thoughts

🔗 Stay Connected

Step 1 — Installing Server Requirements

Step 2 — Configuring Nginx for Laravel

Step 3 — Set up MySQL server and create a database

Step 4 — Initializing the Application on the Server

Configure Your `.env`

The `failed()` Method

`ShouldBeUnique` — Prevent Duplicate Jobs