Deployment is one of the messiest things if not done correctly. This can cause downtime which in turn can cause significant damage to businesses. There are so many checks to make sure all goes well. And even after that sometimes shit happens. And yes I am speaking from personal experience.

Installing Deployer

you can install deployer with the help if following command

composer require --dev deployer/deployer

Using Deployer

To use deployer we will use the deployer CLI. The executable binary can be located in ./vendor/bin/dep. I have added it to the Shell RS file (zshrc) as an alias dep

you can do the same by adding the following line to .zshrc or .bashrc

alias dep='vendor/bin/dep'

once you have added this update shell by

source ~/.zshrc

You can also use ./vendor/bin/dep if you prefer.

Now, we have all our binaries in place, we initiate the project by

dep init

Deployer will ask you a few questions, and after finishing you will have a deploy.php or deploy.yaml file. This is a deployment recipe. It contains hosts, tasks, and other required steps for deployment. My personal preference is .php file

Add the following content to your deploy.php file if not already there.

namespace Deployer;

require 'recipe/laravel.php';

// Config

set('repository', 'path-to-your-repository');

add('shared_files', []);
add('shared_dirs', []);
add('writable_dirs', []);

// Hosts

    ->set('remote_user', 'your-host-user')
    ->set('deploy_path', 'your-deployment-path');

desc('Build the assets');
task('build', function () {
    run('npm install');
    run('npm run build');

task('optimize', function () {
    run('php artisan optimize');

after('deploy:update_code', 'build');
after('deploy:symlink', 'optimize');

// Hooks

after('deploy:failed', 'deploy:unlock');

To deploy

dep deploy

You can add your preferred tasks in the sequence. Like optimize

task('optimize', function () {
    run('php artisan optimize');

after('deploy:symlink', 'optimize'); // runs the optimization task after deploy:symlink

Directory Structure on Host

Directory Structure of deployer

You have 3 directories in the root of your host

  • current: Holds the current release
  • releases: Hold your past releases, so that you can roll back to any release.
  • shared: Holds all the data shared among all the releases.

Two things are important here.

First, since the latest release always lives in the current directory, your application root is /current/public

second, the .env file will be stored in the shared directory as the environment is shared among all the releases.

Additional Advantages

you can directly login to your SSH with deployer too with

dep ssh

or you can run a task on the server directly from your machine.

task('clearCache', function () {
    run('php artisan cache:clear');

dep clearCache // will run the clear cache task on server.

You can find more details about the deployer here.

Feel free to suggest and feedback in the comments section.