🚀 Laravel Deployer

Zero Downtime Deployment Tool for Laravel Applications

✨ Zero Downtime
🔄 Auto Rollback
📦 GitHub Releases
⚡ Optimized

Quick Installation

📦 Via Composer

Recommended for most users 

composer global require 4msar/laravel-deployer

⬇️ Download PHAR

Standalone executable

curl -sS https://raw.githubusercontent.com/4msar/laravel-deployer/main/install.sh | bash

🔗 Manual Setup

Download and install manually 

wget https://github.com/4msar\
/laravel-deployer/releases\
/download/laravel-deployer
chmod +x laravel-deployer
sudo mv laravel-deployer \
  /usr/local/bin/

🔨 Build from Source

For developers

git clone https://github.com\
/4msar/laravel-deployer.git
cd laravel-deployer
composer install
php laravel-deployer app:build

Ready to deploy? Start with:

laravel-deployer deploy

Deploy Command

Overview

The deploy command fetches the latest release from GitHub and deploys it with zero downtime using symlink-based switching. It handles everything from downloading to health checks and cleanup.

Basic Usage

laravel-deployer deploy

This enters interactive mode and prompts for configuration.

With Options

laravel-deployer deploy --repo=owner/repo --app-name=myapp --install-dir=/var/www

Available Options

Option Description Default
--repo GitHub repository (owner/repo) Interactive prompt
--app-name Application name repo basename
--install-dir Installation directory Current working directory
--web-user Web server user for permissions www-data
--github-token GitHub token for private repos None
--keep-releases Number of old releases to keep 2
--skip-migrations Skip database migrations false
--auto-cleanup Auto cleanup old releases false

Complete Example 

laravel-deployer deploy \
    --repo=4msar/bill-organizer \
    --app-name=bill-organizer \
    --install-dir=/var/www \
    --web-user=www-data \
    --github-token=ghp_xxxxxxxxxxxx \
    --keep-releases=3 \
    --auto-cleanup

Deployment Process

  1. Fetches latest release information from GitHub
  2. Checks current installed version
  3. Downloads the release archive
  4. Extracts to temporary directory
  5. Preserves important files (.env, storage, etc.)
  6. Creates new release directory
  7. Runs Laravel optimization commands
  8. Runs database migrations (if applicable)
  9. Switches symlink to new release (zero downtime!)
  10. Performs health checks
  11. Cleans up old releases
💡 Tip

Keep at least 2 releases so you can quickly rollback if needed.

Rollback Command

Overview

The rollback command safely reverts to the previous release if something goes wrong with the current deployment. It switches the symlink back and runs health checks to ensure everything is working.

Basic Usage

laravel-deployer rollback

With Options

laravel-deployer rollback --app-name=myapp --install-dir=/var/www

Rollback Process

  1. Validates installation exists and is properly configured
  2. Reads current version from version.txt
  3. Discovers all available releases
  4. Identifies the previous release
  5. Displays all releases with their status
  6. Asks for confirmation before proceeding
  7. Switches symlink to previous release
  8. Runs Laravel optimization commands
  9. Updates version file
  10. Performs health checks
⚠️ Requirements

At least 2 releases must exist to perform a rollback. The install directory must be a symlink.

How It Works

Zero Downtime Deployment

Laravel Deployer uses symlink-based deployment to achieve zero downtime. Instead of modifying the current application, it:

📦 Traditional Deployment

Stops the app → Deploys new code → Restarts app = Downtime

⚡ Laravel Deployer

Creates new release → Switches symlink → App keeps running = No downtime

Directory Structure 

/var/www/
├── myapp -> myapp-v1.2.0          (symlink to current release)
├── myapp-v1.2.0/                  (current release)
│   ├── app/
│   ├── config/
│   ├── storage/                   (preserved from old install)
│   ├── .env                       (preserved from old install)
│   └── public/
├── myapp-v1.1.0/                  (previous release - kept for rollback)
└── backups/                       (backup directory)

Requirements

System Requirements

For Private Repositories

Create a GitHub Personal Access Token to avoid rate limiting and access private repositories:

  1. Go to GitHub Settings → Tokens
  2. Click "Generate new token (classic)"
  3. Select scopes: repo (for private repos) or public_repo (for public repos)
  4. Copy and use with --github-token option or in .env
🔒 Security

Never commit your GitHub token to version control. Use environment variables or command-line options only.