Laravel Envoy for Zero-Downtime Deployment

In the dynamic world of web development, deploying updates and new features efficiently and without disrupting the user experience is paramount. Laravel Envoy, an elegant task runner and deployment tool, stands out as an indispensable asset for developers. Its simplicity and robustness make it a favored choice, especially when aiming for the holy grail of deployment strategies: zero downtime. This article delves into how Laravel Envoy can be utilized to achieve zero-downtime deployments, ensuring that your application remains highly available and responsive, even as you roll out updates and improvements.

Understanding Zero-Downtime Deployment

Zero-downtime deployment is a deployment strategy that allows you to update your application without any service interruption or downtime. In traditional deployment methods, updating an application often requires a period of unavailability, which can lead to a poor user experience and potential loss of revenue or user trust. Zero-downtime deployment addresses this issue by ensuring that there is always a live version of your application serving user requests, even as you push out new code or configurations.

Overview of Laravel Envoy

Laravel Envoy is a task runner and deployment tool crafted by Taylor Otwell, the creator of Laravel. Envoy allows developers to define common tasks they run on their remote servers as 'Blade' style PHP scripts, offering a clean and minimal syntax. With Envoy, you can easily run repetitive tasks, such as migrations, artisan commands, or even complex deployment workflows. The tool's simplicity and direct approach make it an excellent choice for teams looking to streamline their deployment process and minimize downtime.

Setting Up Laravel Envoy

Integrating Laravel Envoy into your workflow starts with its setup and configuration. Here's a more detailed approach:

Install Envoy: Begin by globally installing Laravel Envoy through Composer:

composer global require laravel/envoy

Configure Envoy: Create an Envoy.blade.php file at the root of your project. This file is where you'll define your deployment tasks.

Write Basic Tasks: In your Envoy.blade.php, you can define various tasks. Here's an enhanced example where we define a deployment task that includes pulling the latest code and running migrations:

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

@setup
    $repository = 'git@github.com:your/repo.git';
    $app_dir = '/path/to/your/project';
    $release_dir = $app_dir . '/releases/' . date('YmdHis');
@endsetup

@task('deploy')
    mkdir -p {{ $release_dir }}

    @if ($branch)
        git clone --depth 1 -b {{ $branch }} "{{ $repository }}" {{ $release_dir }}
        cd {{ $release_dir }}
    @endif

    echo 'Repository cloned'
    echo 'Running composer install'
    composer install --no-interaction --prefer-dist --optimize-autoloader

    echo 'Running migrations'
    php artisan migrate --force

    echo 'Updating symlinks'
    ln -nfs {{ $release_dir }} {{ $app_dir }}/current
@endtask

Run Tasks: Execute your tasks via the command line using the “envoy run taskName” command. Based on the above setup, deploy your application by running:

envoy run deploy --branch=master

Implementing Zero-Downtime Deployment with Laravel Envoy

The essence of zero-downtime deployment lies in ensuring that the new version of your application is fully prepared and ready to receive traffic before making it live. The following steps and code snippets offer a detailed guide:

Prepare the New Release: Securely clone the repository into a new 'release' directory. This step ensures that the new codebase is set up and ready but not yet serving live traffic.


@task('clone_repository')
    [ -d {{ $release_dir }} ] || git clone --depth 1 -b {{ $branch }} "{{ $repository }}" {{ $release_dir }}
    cd {{ $release_dir }}
    git reset --hard
    git clean -df
    git pull origin {{ $branch }}
    echo "Repository cloned"
@endtask

Install Dependencies: Inside the release directory, ensure all Composer dependencies are up-to-date. This step is crucial for the new release's functionality.

@task('composer_install')
    cd {{ $release_dir }}
    composer install --no-interaction --no-dev --prefer-dist
    echo "Composer dependencies installed"
@endtask

Environment Configuration: Link or copy your .env file to ensure the release directory is configured with the correct environment settings.

@task('link_env')
    ln -nfs {{ $env_file }} {{ $release_dir }}/.env
    echo ".env file linked"
@endtask

Run Artisan Commands: Execute necessary Laravel artisan commands, such as migrations. These should be done within the release directory to prepare the application before going live.

@task('run_migrations')
    php {{ $release_dir }}/artisan migrate --force
    echo "Migrations run"
@endtask

Swap Symlinks: This crucial step changes the 'current' directory to point to the new 'release' directory, effectively bringing the new version live.

@task('update_symlinks')
    ln -nfs {{ $release_dir }} {{ $app_dir }}/current
    echo "Symlinks updated"
@endtask

Implementing Zero-Downtime Deployment with Laravel Envoy Using Stories

Using Laravel Envoy, you can define a series of deployment tasks and then organize these tasks into a story. This approach not only structures your deployment process but also makes it easy to manage and understand. Here's how you can modify your Envoy.blade.php to incorporate stories:

Define Individual Tasks: Start by defining all the necessary tasks. Each task should handle a specific part of the deployment process.

@task('clone_repository')
    echo "Cloning repository into {{ $release_dir }}";
    [ -d {{ $release_dir }} ] || git clone --depth 1 -b {{ $branch }} "{{ $repository }}" {{ $release_dir }}
    cd {{ $release_dir }}
    git reset --hard
    git clean -df
    git pull origin {{ $branch }}
@endtask

@task('composer_install')
    echo "Running composer install in {{ $release_dir }}";
    cd {{ $release_dir }}
    composer install --no-interaction --no-dev --prefer-dist
@endtask

@task('link_env')
    echo "Linking .env file for {{ $release_dir }}";
    ln -nfs {{ $env_file }} {{ $release_dir }}/.env
@endtask

@task('run_migrations')
    echo "Running migrations for {{ $release_dir }}";
    php {{ $release_dir }}/artisan migrate --force
@endtask

@task('update_symlinks')
    echo "Updating symlinks to point to {{ $release_dir }}";
    ln -nfs {{ $release_dir }} {{ $app_dir }}/current
@endtask

Define a Story for Deployment: After defining the tasks, group them into a story. A story is a higher-level abstraction that runs a series of tasks in the order you define.

@story('deploy')
    clone_repository
    composer_install
    link_env
    run_migrations
    update_symlinks
@endstory

In this story named deploy, we're executing tasks in a specific sequence to ensure each step of the deployment process is handled correctly.

Run the Deployment Story: With your tasks and story defined, you can now deploy your application by running the story through Envoy. Execute the following command in your terminal:

envoy run deploy --branch=master

This command will start the deployment process, executing each task defined in the “deploy” story in the order you've specified.

Adding Hooks to Laravel Envoy for Zero-Downtime Deployment

Hooks can be utilized to perform actions before and after your tasks or stories. Below is an example of how to integrate “before” and “after” hooks into your “Envoy.blade.php” file:

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

@setup
    $repository = 'git@github.com:your/repo.git';
    $app_dir = '/path/to/your/project';
    $release_dir = $app_dir . '/releases/' . date('YmdHis');
@endsetup

{{-- Hook to run before the deployment starts --}}
@before('deploy')
    @task('pre_deployment')
        echo "Pre-deployment steps...";
        // Add commands for pre-deployment steps like system checks or notifications
    @endtask
@endbefore

@story('deploy')
    clone_repository
    composer_install
    link_env
    run_migrations
    update_symlinks
@endstory

{{-- Define your tasks here --}}
@task('clone_repository')
    // Your task commands...
@endtask

{{-- ... other tasks ... --}}

{{-- Hook to run after the deployment finishes --}}
@after('deploy')
    @task('post_deployment')
        echo "Post-deployment steps...";
        // Add commands for post-deployment steps like cleaning up, cache clearing, or notifications
    @endtask
@endafter

{{-- Hook to run after a specific task --}}
@after('update_symlinks')
    @task('restart_queue')
        echo "Restarting queue worker...";
        cd {{ $app_dir }}/current
        php artisan queue:restart
    @endtask
@endafter

In this example:

The @before('deploy') hook is used to specify tasks that should run before the deployment process starts. This could be used for sending notifications to your team or performing last-minute system checks.
The @after('deploy') hook defines tasks that will run after the entire deployment process finishes. This is useful for cleanup operations or for sending notifications about the deployment status.
The @after('update_symlinks') hook is used to perform tasks right after the update_symlinks task is completed, such as restarting the queue worker to ensure that the latest code changes are picked up.

By utilizing these hooks, you can make your deployment process more robust and responsive to your application's needs, ensuring smooth transitions and better communication with your team.

In summary, leveraging Laravel Envoy for zero-downtime deployment ensures seamless updates, preserving user experience. This guide outlines essential steps and best practices, empowering developers to execute flawless, uninterrupted deployments. Adopting these strategies elevates your Laravel projects, merging stability with innovation.

Laravel Envoy for Zero-Downtime Deployment