DEV Community: Youssef Ahmed

How I Automated My Laravel Deployments to a VPS with GitHub Actions and SSH

Youssef Ahmed — Wed, 23 Sep 2026 15:17:26 +0000

Running a Laravel application on a VPS usually means repeating the same routine: connecting via SSH, pulling latest changes, running composer updates, migrating the database, and clearing caches manually.

It works, but it's repetitive and prone to human error.

So I automated the boring part.

In this guide, I'll walk through setting up a lightweight Continuous Deployment (CD) pipeline using:

GitHub & GitHub Actions
SSH Key Authentication
A Linux VPS (Ubuntu)
Laravel & Composer

The Core Flow

git push origin main
        ↓
     GitHub
        ↓
 GitHub Actions Runner
        ↓ (SSH)
       VPS
        ↓
 Pull Code & Run Artisan Commands

Every time code is pushed or merged into main, GitHub Actions connects to the VPS and deploys the latest version automatically.

This isn't a replacement for a complex multi-stage CI/CD system, but it is a dependable, lightweight pipeline that works great for small to medium VPS-hosted applications.

1. The Setup & Prerequisites

My Laravel project lives on the VPS at:

/var/www/html/paltform-api

The source code is stored on GitHub:

github.com/youssef-ahmed-cs/laracast

The deployment branch is:

main

Before touching GitHub Actions, make sure the local project is linked to GitHub:

git remote -v
# origin  git@github.com:youssef-ahmed-cs/laracast.git (fetch)
# origin  git@github.com:youssef-ahmed-cs/laracast.git (push)

And verify the standard Laravel folder structure on the server (app, bootstrap, config, database, public, routes, storage, etc.):

2. Solving Git's "Dubious Ownership" Error

While setting up automated deployments, Git can throw a security error:

fatal: detected dubious ownership in repository at '/var/www/html/paltform-api'

This happens when the user running the Git commands (your SSH user) doesn't match the user who owns the repository directory (often www-data or root).

To allow Git to safely run inside the repository:

git config --global --add safe.directory /var/www/html/paltform-api

Test it by checking the status:

cd /var/www/html/paltform-api
git status

3. Configure GitHub Secrets for SSH

Instead of hardcoding server credentials into workflow files, store them securely in GitHub under Settings > Secrets and variables > Actions.

Add the following repository secrets:

Secret Name	Description
`SSH_HOST`	Your server's public IP address or domain
`SSH_USERNAME`	The SSH user account on your VPS
`SSH_PORT`	The SSH port (typically `22`)
`SSH_PRIVATE_KEY`	The private SSH key matching the public key in `~/.ssh/authorized_keys`

4. Create the GitHub Actions Workflow

Create the deployment workflow file at .github/workflows/deploy.yml:

name: SSH into VPS and deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-24.04
    name: Deploy over SSH

    steps:
      - name: Deploy project over SSH
        uses: appleboy/ssh-action@v1.2.0
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USERNAME }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          port: ${{ secrets.SSH_PORT }}

          script: |
            set -e

            # 1. Trust repository directory
            git config --global --add safe.directory /var/www/html/paltform-api

            cd /var/www/html/paltform-api

            # 2. Put application into maintenance mode
            php artisan down || true

            # 3. Pull latest changes from main
            git fetch origin main
            git reset --hard origin/main
            git clean -fd

            # 4. Install production dependencies
            composer install --no-dev --prefer-dist --optimize-autoloader --no-interaction

            # 5. Run database migrations
            php artisan migrate --force

            # 6. Clear and cache configuration, routes, and views
            php artisan optimize:clear
            php artisan optimize
            php artisan view:cache

            # 7. Bring application back online
            php artisan up

            echo "Deployment completed successfully."

5. Deconstructing the Deployment Commands

Here is what happens during the deployment step:

set -e: Instructs Bash to exit immediately if any command encounters an error, preventing broken or partial deployments.
php artisan down: Puts the app in maintenance mode so users do not hit 500 errors while files, composer packages, and database tables are updating.
git fetch origin main & git reset --hard origin/main: Rather than a standard git pull (which can fail with merge conflicts), this ensures the VPS working tree strictly mirrors the GitHub main branch.
git clean -fd: Removes any untracked files or directories. (Make sure .env and user uploads are defined in .gitignore so they are not deleted).
composer install --no-dev --optimize-autoloader: Installs production dependencies without dev tools (like PHPUnit or Faker) and builds an optimized autoloader map.
php artisan migrate --force: Executes any pending database migrations in production without prompting for manual confirmation.
php artisan optimize: Generates cached files for configuration, events, and routes in a single optimized command.
php artisan up: Disables maintenance mode and restores user traffic.

6. Pushing Changes and Verifying Deployment

Trigger the pipeline with a push from your local machine:

git add .
git commit -m "Update application"
git push origin main

GitHub Actions will pick up the push, start the runner, and execute the remote script over SSH:

Once finished, check the action logs. The step will output:

Deployment completed successfully.

Process exited with status 0

Conclusion

The deployment pipeline is fully automated:

             Local Machine
                   │
                   │ git push origin main
                   ▼
                GitHub
                   │
                   ▼
            GitHub Actions
                   │
                   │ SSH
                   ▼
                  VPS
                   │
                   ▼
       /var/www/html/paltform-api
                   │
          ┌────────┴────────┐
          ▼                 ▼
     Update Git      Install Composer
          │                 │
          └────────┬────────┘
                   ▼
            Migrate Database
                   │
                   ▼
            Optimize Laravel
                   │
                   ▼
          Deployment Complete

Instead of logging into the server every time a feature is ready, a simple git push origin main handles code retrieval, dependency installation, database migration, and cache re-generation automatically.

How to connection between laravel and Azure Blob ?

Youssef Ahmed — Fri, 24 Jul 2026 14:35:42 +0000

Integrating Azure Blob Storage with Laravel allows you to store files in Microsoft's scalable cloud storage instead of your local server. This approach improves reliability, scalability, and storage management for production applications.

In this guide, you'll learn how to connect Laravel 11, 12, and 13 to Azure Blob Storage and upload files with just a few steps.

Prerequisites

Before getting started, make sure you have:

A Laravel 11, 12, or 13 application.
An Azure account.
An Azure Storage Account with a Blob Container created.
Composer installed.

Step 1: Install the Azure Storage Package

Install the Laravel Azure Storage package:

composer require matthewbdaly/laravel-azure-storage

Then, add a new disk inside config/filesystems.php:

'azure' => [
    'driver' => 'azure',
    'name' => env('AZURE_STORAGE_NAME'),
    'key' => env('AZURE_STORAGE_KEY'),
    'container' => env('AZURE_STORAGE_CONTAINER_NAME'),
    'url' => env('AZURE_STORAGE_URL'),
    'prefix' => null,
    'connection_string' => env('AZURE_STORAGE_CONNECTION_STRING'),
],

Configure your `.env`

Although several variables are available, the connection string alone is enough to establish the connection.

AZURE_STORAGE_CONNECTION_STRING="your-azure-storage-connection-string"

You can find the connection string in:

Storage Account => Security + networking => Access keys

Step 2: Create an Azure Blob Storage Service

Generate a service class or controller:

cd your-app-location

sudo mkdir Services

sudo touch AzureBlobStorageService.php

Create the following service:

<?php

namespace App\Services;

use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Str;

class AzureBlobStorageService
{
    public function uploadImage($file, $path)
    {
        $fileName = uniqid()
            . Str::random(5)
            . time()
            . '.'
            . $file->getClientOriginalExtension();

        $contentType = $file->getClientMimeType();

        $options = [
            'Content-Type' => $contentType,
        ];

        Storage::disk('azure')->putFileAs(
            $path,
            $file,
            $fileName,
            $options
        );

        return Storage::disk('azure')->url("$path/$fileName");
    }
}

Step 3: Upload Files

Now you can inject the service into a controller or simply test it with a route.

use App\Services\AzureBlobStorageService;

Route::post('/upload-on-azure', function (
    AzureBlobStorageService $azureService
) {
    $file = request()->file('file');

    if (!$file) {
        return response()->json([
            'error' => 'No file provided',
        ], 400);
    }

    $filePath = $azureService->uploadImage($file, 'devhub');

    if (!$filePath) {
        return response()->json([
            'error' => 'Failed to upload file.',
        ], 500);
    }

    return response()->json([
        'message' => 'File uploaded successfully!',
        'file_path' => $filePath,
    ]);
});

Step 4: Test the API

Use any API client to upload a file.

Examples:

Postman
HTTPie
cURL

Example using Postman:

Common Issue: 404 Resource Not Found

If the returned URL opens a 404 page or shows:

PublicAccessNotPermitted

don't worry this is expected.

Azure Storage blocks anonymous public access by default.

Why?

Your storage account or blob container doesn't allow public blob access.

Solution 1 (Development)

Enable public access for your Blob Container.

This is acceptable for testing, but not recommended for production.

Solution 2 (Recommended)

Generate Shared Access Signature (SAS) URLs instead of exposing blobs publicly.

This provides temporary, secure access to your files while keeping your storage account private.

Example error:

Azure Portal settings:

That's It!! Can open image!

Congratulations!

Your Laravel application is now connected to Azure Blob Storage, and you can start uploading files to the cloud.

Azure Blob Storage is an excellent choice for production applications because it offers:

High availability
Scalability
Secure storage
Low maintenance
Integration with other Azure services

Happy coding! ❤️

If this article helped you, consider giving it a ❤️ and following me for more Laravel and Azure content.

Video Tutorial

Prefer watching a complete walkthrough?

I created a step-by-step video that covers the entire process, including:

Creating an Azure Storage Account
Creating a Blob Container
Getting the Storage Connection String
Configuring Laravel
Uploading files to Azure Blob Storage
Solving the PublicAccessNotPermitted issue
Testing the upload API

Watch the full tutorial here:

https://youtu.be/5XQP4Y4ZfRA?si=fMNLSfd2ViePO7i4

Storage Account Overview - Azure Storage | Microsoft Learn

Learn about the types of storage accounts in Azure Storage. Review account naming, tiers, redundancy, encryption, endpoints, and more.

learn.microsoft.com

Connect With Me

GitHub: https://github.com/YoussefAhmedCs
LinkedIn: https://linkedin.com/in/youssef-ahmed-cs

Deploying Laravel App to Ubuntu or Debian Server VM Azure

Youssef Ahmed — Sat, 18 Jul 2026 14:13:36 +0000

Deploying a Laravel application doesn't have to cost money. If you already have a VPS or an Azure Virtual Machine, you can deploy your Laravel project manually without paying for services like Laravel Forge or Laravel Cloud.

In this guide, I'll show you how to deploy a Laravel application step by step using Nginx, PHP, MySQL, and Composer on an Ubuntu VM. I'll also explain what each command does so you understand what's happening behind the scenes.

Don't have an Azure Virtual Machine yet?

Watch this video first:

https://youtu.be/Io34SbaYZmQ?si=a4btxewV0nFo0x_N

Prerequisites

Before getting started, make sure you have:

An Ubuntu or Debian server (this guide uses Ubuntu on Azure)
A GitHub repository containing your Laravel project
SSH access (or password access) to your server
Root or sudo privileges
A public IP address assigned to your VM

1. Update the Server

Before installing any packages, update your package index.

sudo apt update

Optionally, upgrade installed packages.

sudo apt upgrade -y

2. Install Nginx

Nginx is a high-performance web server used to serve websites efficiently. It can also act as a reverse proxy and load balancer.

Think of Nginx as a highly efficient post office. It receives incoming requests, processes them, and forwards them to the correct destination.

Install Nginx:

sudo apt install nginx -y

Verify that it is running:

sudo systemctl status nginx

3. Install MySQL

Laravel needs a database to store application data.

Install MySQL Server:

sudo apt install mysql-server -y

Verify the installation:

sudo systemctl status mysql

4. Install PHP

Nginx doesn't execute PHP files directly. Instead, it communicates with PHP-FPM (FastCGI Process Manager), which processes PHP requests.

Install PHP and the required extensions:

sudo apt install -y \
php \
php-fpm \
php-cli \
php-common \
php-curl \
php-mbstring \
php-xml \
php-soap \
php-gd \
php-bcmath \
php-zip \
php-mysql

Note

If you're using a specific PHP version (for example PHP 8.4), install the matching packages instead.

Check your PHP version:

php -v

5. Install Composer

Composer is the dependency manager for PHP.

Download and install Composer:

curl -sS https://getcomposer.org/installer | php

sudo mv composer.phar /usr/local/bin/composer

Verify the installation:

composer --version

6. Install Node.js & NPM

Laravel uses Node.js for compiling frontend assets with Vite.

Install Node.js and NPM:

sudo apt install -y nodejs npm

7. Clone Your GitHub Repository

Move to the web directory:

cd /var/www/html

Clone your project:

git clone YOUR_GITHUB_SSH_URL learn-vm

Move into the project directory:

cd learn-vm

8. Install Project Dependencies

Install Composer packages:

composer install --no-dev --optimize-autoloader

Install Node packages:

npm install

Build frontend assets if use front:

npm run build

9. Configure Environment Variables

Copy the environment file:

cp .env.example .env

Generate the application key:

php artisan key:generate

10. Create the MySQL Database

Open MySQL:

sudo mysql

Run the following SQL:

CREATE DATABASE learnvm;

CREATE USER 'learnuser'@'localhost'
IDENTIFIED BY 'YOUR_PASSWORD';

GRANT ALL PRIVILEGES ON learnvm.* TO 'learnuser'@'localhost';

FLUSH PRIVILEGES;

EXIT;

11. Configure Laravel

Open the .env file:

nano .env

Update your database credentials:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=learnvm
DB_USERNAME=learnuser
DB_PASSWORD=YOUR_PASSWORD

12. Run Database Migrations

php artisan migrate

If your project includes seeders:

php artisan db:seed

13. Set File Permissions

Laravel needs write access to the storage and bootstrap/cache directories.

sudo chown -R www-data:www-data storage bootstrap/cache

sudo chmod -R 775 storage bootstrap/cache

14. Configure Nginx

Create a new virtual host configuration:

sudo nano /etc/nginx/sites-available/learn-vm

Paste the following configuration:

server {
    listen 80;
    server_name YOUR_VM_PUBLIC_IP;

    root /var/www/html/learn-vm/public;
    index index.php index.html;

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

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }

    location ~ /\.ht {
        deny all;
    }
}

Replace YOUR_VM_PUBLIC_IP with your server's public IP address.

15. Enable the Site

sudo ln -s /etc/nginx/sites-available/learn-vm /etc/nginx/sites-enabled/

16. Stop Apache (If Installed)

If Apache is already using port 80, stop it first.

sudo systemctl stop apache2

17. Test the Nginx Configuration

sudo nginx -t

If everything looks good, reload Nginx:

sudo systemctl reload nginx

Restart PHP-FPM:

sudo systemctl restart php8.3-fpm

18. Open Your Application

Visit your server's public IP address in your browser:

http://YOUR_VM_PUBLIC_IP

Your Laravel application should now be running successfully.

Azure Networking

If your application isn't accessible, make sure the required ports are open.

Go to:

Azure Portal → Virtual Machine → Networking → Add Inbound Port Rule

Allow the following ports:

HTTP (80)
HTTPS (443)

After saving the rules, refresh your browser.

Troubleshooting

If your application doesn't load, check the following:

Nginx is running.
PHP-FPM is running.
MySQL is running.
Port 80 is open.
Port 443 is open (if using HTTPS).
Laravel has the correct file permissions.
Your .env file contains the correct database credentials.
The Nginx configuration points to the correct public directory.
Run php artisan config:cache after updating your .env file.

Next Steps

Congratulations! Your Laravel application is now deployed successfully.

To make your server production ready, consider adding:

Add a custom domain name and point its DNS records to your server's public IP address.

Resources

Live Demo

http://51.107.72.82/

All Commands

https://user-cdn.hackclub-assets.com/019f68cc-736b-7627-b4cf-82f958d84b93/README.md

If this guide helped you, consider leaving a ❤️ on DEV and sharing it with other Laravel developers. Happy coding!!

From the River to the Sea, Palestine Will Be Free!🇵🇸

GitHub Campus Experts

Youssef Ahmed — Sat, 20 Jun 2026 05:27:40 +0000

This is a submission for the June Solstice Game Jam

What I Built

Video Demo

Code

How I Built It

Prize Category

git

Youssef Ahmed — Wed, 24 Dec 2025 23:14:06 +0000

git tool box

DEV Community: Youssef Ahmed

How I Automated My Laravel Deployments to a VPS with GitHub Actions and SSH

The Core Flow

1. The Setup & Prerequisites

2. Solving Git's "Dubious Ownership" Error

3. Configure GitHub Secrets for SSH

4. Create the GitHub Actions Workflow

5. Deconstructing the Deployment Commands

6. Pushing Changes and Verifying Deployment

Conclusion

How to connection between laravel and Azure Blob ?

Prerequisites

Step 1: Install the Azure Storage Package

Configure your .env

Step 2: Create an Azure Blob Storage Service

Step 3: Upload Files

Step 4: Test the API

Common Issue: 404 Resource Not Found

Why?

Solution 1 (Development)

Solution 2 (Recommended)

That's It!! Can open image!

Video Tutorial

Storage Account Overview - Azure Storage | Microsoft Learn

Connect With Me

Deploying Laravel App to Ubuntu or Debian Server VM Azure

Prerequisites

1. Update the Server

2. Install Nginx

3. Install MySQL

4. Install PHP

5. Install Composer

6. Install Node.js & NPM

7. Clone Your GitHub Repository

8. Install Project Dependencies

9. Configure Environment Variables

10. Create the MySQL Database

11. Configure Laravel

12. Run Database Migrations

13. Set File Permissions

14. Configure Nginx

15. Enable the Site

16. Stop Apache (If Installed)

17. Test the Nginx Configuration

18. Open Your Application

Azure Networking

Troubleshooting

Next Steps

Resources

https://user-cdn.hackclub-assets.com/019f68cc-736b-7627-b4cf-82f958d84b93/README.md

GitHub Campus Experts

What I Built

Video Demo

Code

How I Built It

Prize Category

git

Configure your `.env`