Download the PHP package 4msar/laravel-deployer without Composer

Laravel Deployer

A powerful zero-downtime deployment tool for Laravel applications built with Laravel Zero. Deploy your Laravel applications from GitHub releases with confidence using an easy-to-use CLI tool.

Features

• 🚀 Zero Downtime Deployment - Symlink-based deployments ensure your application stays online
• 📦 GitHub Releases Integration - Automatically fetch and deploy from GitHub releases
• 🔄 Automatic Rollback - Rolls back to previous version if deployment fails
• 🗂️ Release Management - Keep multiple releases and easily cleanup old ones
• 🔐 Preserve Important Files - Automatically preserves .env, storage, and other critical files
• ⚡ Laravel Optimization - Runs cache optimization commands automatically
• 🔍 Health Checks - Verifies deployment success before finalizing
• 🎨 Beautiful CLI - Clean, colored output with progress indicators
• ⚙️ Highly Configurable - Configure via .env, config file, or command options

Installation

Via Composer (Recommended)

Via Download

Download the latest laravel-deployer PHAR file from the releases page:

One click install script

Build from Source

Configuration

Using .env File

Copy the example configuration:

Edit .env with your settings:

Using Command Options

You can override configuration using command-line options:

Usage

Basic Deployment

Advanced Options

Full Example

Rollback

Overview

The rollback command allows you to revert to the previous release if something goes wrong. It automatically switches the symlink to point to the previous version and runs health checks.

Basic Usage

How Rollback Works

The rollback process is straightforward and safe:

1. Validates Installation - Checks if installation exists and is properly set up
2. Reads Current Version - Gets the current version from version.txt
3. Finds Releases - Discovers all available releases and identifies the previous one
4. Displays Options - Shows all releases with their status (Current/Previous)
5. User Confirmation - Asks for confirmation before rolling back
6. Switch Release - Updates symlink to point to the previous release
7. Optimize - Runs Laravel cache clearing and caching commands
8. Update Version - Updates version.txt with the previous version
9. Health Check - Verifies the application is working after rollback

Example Rollback Scenario

Release Requirements

• Minimum Releases: At least 2 releases must exist to perform a rollback
• Release Directory: Release directories must follow the naming pattern: {app-name}-v*
• Symlink: The install directory must be a symlink pointing to the current release

How It Works

1. Fetch Release: Downloads the latest release from GitHub
2. Prepare: Extracts the release to a temporary directory
3. Preserve Files: Copies important files from current installation (.env, storage, etc.)
4. Deploy: Creates a new release directory and copies files
5. Optimize: Runs Laravel optimization commands (config, route, view cache)
6. Migrate: Optionally runs database migrations
7. Switch: Updates symlink to point to new release
8. Health Check: Verifies the application is working
9. Cleanup: Removes old releases (optional)
10. Rollback: Automatically rolls back on failure

Directory Structure

After deployment, your directory structure will look like:

Requirements

• PHP ^8.4
• Composer
• Git
• curl, unzip command-line tools
• Proper file permissions on target server

GitHub Token

For private repositories or to avoid rate limiting, create a GitHub Personal Access Token:

1. Go to https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Select scopes: repo (for private repos) or public_repo (for public repos)
4. Copy the token and use it with --github-token option or in .env

Deployment Best Practices

1. Test Locally: Always test your release locally before deploying
2. Backup Database: Backup your database before running migrations
3. Use Releases: Tag your code with semantic versioning (v1.0.0, v1.1.0, etc.)
4. Preserve Files: Ensure all important files are listed in config
5. Health Checks: Verify your application after deployment
6. Keep Releases: Keep at least 2 previous releases for quick rollback

Troubleshooting

Permission Denied

Run with sudo or ensure your user has write permissions:

GitHub Rate Limiting

Use a GitHub token to increase rate limits:

Migration Failures

Skip migrations and run them manually:

Rollback Manually

Use the built-in rollback command:

Or manually create the symlink (requires knowing the previous release name):

Self Update

To update laravel-deployer to the latest version, run:

It will download and replace the current PHAR with the latest release.

License

This project is open-sourced software licensed under the MIT license.

Credits

Built with Laravel Zero - The PHP framework for console applications.