PHPackages                             4msar/laravel-deployer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. 4msar/laravel-deployer

ActiveProject[CLI & Console](/categories/cli)

4msar/laravel-deployer
======================

Zero-downtime deployment tool for Laravel applications from GitHub releases

v1.0.3(3mo ago)02MITPHPPHP ^8.2CI passing

Since Feb 4Pushed 3mo agoCompare

[ Source](https://github.com/4msar/laravel-deployer)[ Packagist](https://packagist.org/packages/4msar/laravel-deployer)[ Docs](https://github.com/4msar/laravel-deployer)[ RSS](/packages/4msar-laravel-deployer/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (7)Versions (5)Used By (0)

Laravel Deployer
================

[](#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
--------

[](#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
------------

[](#installation)

### Via Composer (Recommended)

[](#via-composer-recommended)

```
composer global require 4msar/laravel-deployer
```

### Via Download

[](#via-download)

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

```
wget https://github.com/4msar/laravel-deployer/raw/main/builds/laravel-deployer -O laravel-deployer
chmod +x laravel-deployer
sudo mv laravel-deployer /usr/local/bin/laravel-deployer
```

#### One click install script

[](#one-click-install-script)

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

### Build from Source

[](#build-from-source)

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

Configuration
-------------

[](#configuration)

### Using .env File

[](#using-env-file)

Copy the example configuration:

```
cp .env.example .env
```

Edit `.env` with your settings:

```
DEPLOY_GITHUB_REPO=your-username/your-repo
DEPLOY_APP_NAME=your-app
DEPLOY_INSTALL_DIR=/var/www
DEPLOY_WEB_USER=www-data
DEPLOY_GITHUB_TOKEN=your-github-token
DEPLOY_KEEP_RELEASES=2
```

### Using Command Options

[](#using-command-options)

You can override configuration using command-line options:

```
laravel-deployer deploy \
    --repo=your-username/your-repo \
    --app-name=your-app \
    --install-dir=/var/www \
    --web-user=www-data \
    --keep-releases=2
```

Usage
-----

[](#usage)

### Basic Deployment

[](#basic-deployment)

```
# Interactive mode (prompts for configuration)
laravel-deployer deploy

# With options
laravel-deployer deploy --repo=username/repo --install-dir=/var/www
```

### Advanced Options

[](#advanced-options)

```
# Force deployment even if same version
laravel-deployer deploy --force

# Skip database migrations
laravel-deployer deploy --skip-migrations

# Auto cleanup old releases without prompting
laravel-deployer deploy --auto-cleanup

# Use GitHub token for private repos
laravel-deployer deploy --github-token=your_token_here

# Keep specific number of old releases
laravel-deployer deploy --keep-releases=5
```

### Full Example

[](#full-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
```

How It Works
------------

[](#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
-------------------

[](#directory-structure)

After deployment, your directory structure will look like:

```
/var/www/
├── your-app -> your-app-v1.2.0  (symlink to current release)
├── your-app-v1.2.0/              (current release)
├── your-app-v1.1.0/              (previous release)
└── backups/                      (backup directory)

```

Requirements
------------

[](#requirements)

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

GitHub Token
------------

[](#github-token)

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

1. Go to
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
-------------------------

[](#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
---------------

[](#troubleshooting)

### Permission Denied

[](#permission-denied)

Run with sudo or ensure your user has write permissions:

```
sudo laravel-deployer deploy
```

### GitHub Rate Limiting

[](#github-rate-limiting)

Use a GitHub token to increase rate limits:

```
laravel-deployer deploy --github-token=your_token
```

### Migration Failures

[](#migration-failures)

Skip migrations and run them manually:

```
laravel-deployer deploy --skip-migrations
cd /var/www/your-app
php artisan migrate
```

### Rollback Manually

[](#rollback-manually)

If automatic rollback fails:

```
cd /var/www
ln -sfn your-app-v1.1.0 your-app
```

Self Update
-----------

[](#self-update)

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

```
laravel-deployer self-update
```

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

License
-------

[](#license)

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

Credits
-------

[](#credits)

Built with [Laravel Zero](https://laravel-zero.com) - The PHP framework for console applications.

###  Health Score

38

—

LowBetter than 84% of packages

Maintenance87

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

4

Last Release

93d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/40a496cd0ac1bbb7885d5c6e2b9b8d2d1414e532629ff2892a566c28aa88c9aa?d=identicon)[msar](/maintainers/msar)

---

Top Contributors

[![4msar](https://avatars.githubusercontent.com/u/17962782?v=4)](https://github.com/4msar "4msar (12 commits)")

---

Tags

github-releaseslaravellaravel-clilaravel-deploylaravel-deployerlaravel-deploymentlaravel-zeroclilaravelgithubdeploymentdeployerzero-downtimereleases

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/4msar-laravel-deployer/health.svg)

```
[![Health](https://phpackages.com/badges/4msar-laravel-deployer/health.svg)](https://phpackages.com/packages/4msar-laravel-deployer)
```

###  Alternatives

[innocenzi/deployer-recipe-forge

Seamless zero-downtime deployment on Forge with Deployer

1916.6k](/packages/innocenzi-deployer-recipe-forge)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)