Laravel Zero Downtime Deployments with Envoy

Introduction

Introduce the topic by explaining what Laravel Envoy is, its purpose, and why developers should consider using it for deployment automation. Highlight benefits like simplicity, SSH-based execution, and reusable scripts.

Example Introduction:

"Deploying Laravel projects manually can be repetitive and error-prone. With Laravel Envoy, you can automate your deployment process using simple and readable syntax. In this guide, I'll show you how to set up and use Laravel Envoy for seamless deployments."

Advantages of Zero Downtime Deployment

No Downtime: Users always interact with a live application during deployment.
Safe Rollback: If deployment fails, the previous release remains active.
Organized Releases: Each deployment is stored in a timestamped directory.

Step 1: Install Laravel Envoy

Explain how to install Laravel Envoy globally using Composer.

composer global require laravel/envoy

Ensure readers add Composer's global binaries to their system PATH if not already done.

export PATH="$PATH:$HOME/.composer/vendor/bin"

Or Install to your project dir

composer require laravel/envoy --dev

Step 2: Set Up SSH Access to Your Server

Explain how to set up SSH access to the server. Include steps for generating an SSH key and adding it to the server for password-less access.

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
ssh-copy-id username@your-server-ip

Test the connection:

ssh username@your-server-ip

Step 3: Create the Envoy Configuration File

Show how to create an envoy.blade.php file in the root of the Laravel project and explain its structure.

Example Configuration:

@servers(['web' => 'username@your-server-ip'])

@setup
    $repository = 'git@github.com:your-username/your-repo.git';
    $releases_dir = '/var/www/your-project/releases';
    $app_dir = '/var/www/your-project';
    $release = date('YmdHis');
    $new_release_dir = $releases_dir . '/' . $release;
@endsetup

@story('deploy')
    clone_repository
    run_composer
    update_symlinks
@endstory

@task('clone_repository', ['on' => 'web'])
    [ -d {{ $releases_dir }} ] || mkdir -p {{ $releases_dir }};
    git clone --branch=main {{ $repository }} {{ $new_release_dir }};
@endtask

@task('run_composer', ['on' => 'web'])
    cd {{ $new_release_dir }};
    composer install --optimize-autoloader --no-dev;
@endtask

@task('update_symlinks', ['on' => 'web'])
    ln -nfs {{ $new_release_dir }} {{ $app_dir }}/current;
    ln -nfs {{ $app_dir }}/shared/.env {{ $new_release_dir }}/.env;
@endtask

Explain each section:

@servers: Define remote servers.
@setup: Initialize variables for the deployment process.
@story: Sequence of tasks to execute.
@task: Individual steps like cloning the repository or running Composer.

Step 4: Deploy the Laravel Project

Explain how to run the deployment command using Envoy:

envoy run deploy

Highlight how Envoy connects via SSH and executes tasks in sequence.

Step 5: Test the Deployment

Guide readers on verifying the deployment:

Check the project directory on the server.
Ensure the symlinks are correctly pointing to the latest release.
Test the application in the browser.

Step 6: Add Cache Clearing and Maintenance Mode

Show how to enhance the script with cache clearing and maintenance mode commands.

Example Addition:

@task('clear_cache', ['on' => 'web'])
    php {{ $app_dir }}/current/artisan config:cache;
    php {{ $app_dir }}/current/artisan route:cache;
    php {{ $app_dir }}/current/artisan view:cache;
@endtask

@task('maintenance_mode', ['on' => 'web'])
    php {{ $app_dir }}/current/artisan down --message="Deployment in progress";
@endtask

Bonus: Rollback to Previous Release

Include an optional feature for rolling back to the previous release in case of failure.

Example Rollback Task:

@task('rollback', ['on' => 'web'])
    ln -nfs {{ $releases_dir }}/$(ls -t {{ $releases_dir }} | tail -n 2 | head -n 1) {{ $app_dir }}/current;
@endtask

Common Issues and Debugging Tips

Provide solutions to common problems like:

SSH authentication errors.
Missing permissions on the server.
Envoy not being recognized as a command.

"I hope this guide helps you simplify your Laravel deployments with Envoy. Let me know your thoughts or questions below! Don’t forget to follow for more Laravel tutorials."

References

Conclusion

Wrap up by emphasizing the power of automation in modern development workflows and inviting readers to share feedback or ask questions in the comments.