DEV Community

HoudaifaDevBS
HoudaifaDevBS

Posted on • Edited on • Originally published at Medium

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

#laravel #vps #githubactions #cicd

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.

deploy laravel to vps with github actions

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
Enter fullscreen mode Exit fullscreen mode

⚠️ 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
Enter fullscreen mode Exit fullscreen mode 
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;  
    }  
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

⚠️ 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
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. GitHub Actions installs PHP and Node
  2. Composer dependencies are installed
  3. Frontend assets are built
  4. A clean release artifact is generated
  5. The artifact is deployed to the server via SSH
  6. A new release directory is created
  7. 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!"
Enter fullscreen mode Exit fullscreen mode

In your GitHub repository:

  1. Go to Settings → Secrets and variables → Actions
  2. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

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
Enter fullscreen mode Exit fullscreen mode

⚠️ 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
Enter fullscreen mode Exit fullscreen mode 
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;  
    }  
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

⚠️ 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
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. GitHub Actions installs PHP and Node
  2. Composer dependencies are installed
  3. Frontend assets are built
  4. A clean release artifact is generated
  5. The artifact is deployed to the server via SSH
  6. A new release directory is created
  7. 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!"
Enter fullscreen mode Exit fullscreen mode

In your GitHub repository:

  1. Go to Settings → Secrets and variables → Actions
  2. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

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
Enter fullscreen mode Exit fullscreen mode

⚠️ 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
Enter fullscreen mode Exit fullscreen mode 
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;  
    }  
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

⚠️ 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
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. GitHub Actions installs PHP and Node
  2. Composer dependencies are installed
  3. Frontend assets are built
  4. A clean release artifact is generated
  5. The artifact is deployed to the server via SSH
  6. A new release directory is created
  7. 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!"
Enter fullscreen mode Exit fullscreen mode

In your GitHub repository:

  1. Go to Settings → Secrets and variables → Actions
  2. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Found this article useful?

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

Top comments (2)

Collapse
 
melezhik profile image
Alexey Melezhik • • Edited

Nice post. I have a suggestion on improvement of your setup.

Why not reverse logic - keep your source code on forgejo instance self hosted on vps and mirror it on GitHub , and then trigger builds on GH and then pull when image is ready back to your host - dead simple ci may help with that, check it out - deadsimpleci.sparrowhub.io/doc/README

On self hosted forgejo side dsci pipeline you just need to run this code in the loop till it succeeds:


gh api repos/{owner}/{repo}/actions/artifacts \
  --jq ".artifacts[] | select(.workflow_run.head_sha == \"21e6188608352ac2ed8e2d4c65e11ae2dbe20291\")"
Enter fullscreen mode Exit fullscreen mode

Pros:

Your vps instance is not exposed ssh/scp publicly

You still use free gh cycles to build heavy things

Your internal stuff is kept privately , you don’t need to add any keys, secrets to your gh account , as in that case you just pull artifacts from public gh api and deploy them in localhost mode

Collapse
 
houdaifadev profile image
HoudaifaDevBS •

That’s a really interesting approach.

Using a 'pull' model to avoid exposing SSH ports or storing keys in GitHub Secrets is definitely safer from a security perspective. While maintaining a self-hosted Forgejo instance might be a bit challenging.

I'll check it out! Thanks for the suggestion!