Deployer Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bugbyte/deployer
   

   Add the package to your composer.json under require.

2. Basic Configuration Create a deploy.php file in your project root with a minimal setup:

   <?php
   require __DIR__.'/vendor/autoload.php';
   
   use Bugbyte\Deployer\Deployer;
   
   $deployer = new Deployer([
       'local' => [
           'path' => __DIR__,
       ],
       'remote' => [
           'host' => 'your-server.com',
           'user' => 'deploy-user',
           'path' => '/var/www/your-project',
       ],
   ]);
   
   $deployer->deploy();
   

3. First Deployment Run the deployer via CLI:

   php deploy.php
   

   The package will:

   • Upload files via rsync (excluding data_dirs by default).
   • Move user-generated content (e.g., storage, uploads) outside the project root.
   • Create a symlink named production pointing to the new deployment directory.

First Use Case: Deploying a Laravel App

1. Define data_dirs in your deploy.php:

   $deployer = new Deployer([
       'local' => [
           'path' => __DIR__,
           'data_dirs' => ['storage', 'public/uploads'],
       ],
       // ... rest of config
   ]);
   

2. Run deployment:

   php deploy.php
   

   The package handles:
   • Moving storage and uploads to /var/www/your-project/data/ on the server.
   • Creating symlinks in their original locations (e.g., public/uploads → symlink to /var/www/your-project/data/uploads).

Implementation Patterns

Workflow Integration

1. Pre-Deployment Hooks Use preDeploy() to run migrations or build assets:

   $deployer->setPreDeploy(function () {
       shell_exec('php artisan migrate --force');
       shell_exec('npm run production');
   });
   

2. Post-Deployment Tasks Use postDeploy() to clear caches or send notifications:

   $deployer->setPostDeploy(function () {
       shell_exec('php artisan cache:clear');
       shell_exec('php artisan config:clear');
   });
   

3. Rollback Strategy Automate rollbacks in CI/CD pipelines:

   $deployer->setPostRollback(function () {
       shell_exec('php artisan optimize:clear');
   });
   

Laravel-Specific Patterns

1. Environment Configuration Override .env during deployment:

   $deployer->setPreDeploy(function () {
       file_put_contents(
           __DIR__.'/remote/.env',
           str_replace('APP_ENV=local', 'APP_ENV=production', file_get_contents(__DIR__.'/remote/.env'))
       );
   });
   

2. Artisan Commands Chain Laravel commands with deployment steps:

   $deployer->setPreActivate(function () {
       shell_exec('php artisan queue:work --daemon');
   });
   

3. Storage Symlinks Ensure storage/link runs post-deploy:

   $deployer->setPostDeploy(function () {
       shell_exec('php artisan storage:link');
   });
   

SSH and RSync Optimization

1. SSH Config Use ~/.ssh/config to avoid password prompts:

   Host your-server.com
       User deploy-user
       IdentityFile ~/.ssh/id_rsa
   

2. Rsync Excludes Customize excludes in deploy.php:

   $deployer->setRsyncExcludes(['node_modules', '.git', 'vendor']);
   

3. Incremental Deploys Leverage --copy-dest for faster subsequent deploys (handled automatically by the package).

Gotchas and Tips

Common Pitfalls

1. Symlink Permissions

   • Issue: Apache/Nginx fails to follow symlinks (e.g., public/uploads).
   • Fix: Ensure FollowSymLinks is enabled in Apache or symlinks are allowed in Nginx:

     <Directory /var/www/your-project>
         Options FollowSymLinks
     </Directory>
     

2. Data Directory Ownership

   • Issue: Newly moved data_dirs (e.g., storage) have incorrect permissions.
   • Fix: Run chown -R www-data:www-data /var/www/your-project/data post-deploy.

3. Rsync Overwriting

   • Issue: Custom files (e.g., .env) are overwritten during deploy.
   • Fix: Exclude them in deploy.php:

     $deployer->setRsyncExcludes(['.env']);
     

4. Rollback Failures

   • Issue: Rollback fails if production symlink is broken.
   • Fix: Verify the symlink exists before rolling back:

     $deployer->setPreRollback(function () {
         if (!file_exists('/var/www/your-project/production')) {
             throw new Exception('Symlink missing!');
         }
     });
     

Debugging Tips

1. Dry Runs Test deployments without uploading:

   php deploy.php --dry-run
   

2. Verbose Output Enable debug mode:

   $deployer = new Deployer([...], ['debug' => true]);
   

3. SSH Debugging Use -vvv with rsync:

   $deployer->setRsyncOptions(['-vvv']);
   

Extension Points

1. Custom Remote Commands Extend the deployer with SSH commands:

   $deployer->addRemoteCommand('composer install --no-dev --optimize-autoloader');
   

2. Database Migrations Integrate with LemonWeb/dbpatcher:

   $deployer->setPreActivate(function () {
       shell_exec('php vendor/bin/dbpatcher patch');
   });
   

3. Slack/Email Notifications Hook into postDeploy/postRollback:

   $deployer->setPostDeploy(function () {
       shell_exec('curl -X POST -H "Content-type: application/json" --data \'{"text":"Deployed successfully!"}\' YOUR_SLACK_WEBHOOK');
   });
   

Configuration Quirks

1. Path Handling

   • Use absolute paths for remote.path to avoid issues with rsync.
   • Example: /var/www/your-project instead of ~/projects/your-project.

2. PHP CLI Version

   • Ensure both local and remote servers use PHP 5.2+ (preferably 7.4+ for Laravel).
   • Check with:

     php -v
     

3. Case Sensitivity

   • Remote paths are case-sensitive on Linux. Match data_dirs exactly (e.g., Storage vs storage).

Pro Tips for Laravel Devs

1. Optimized Deployment Workflow Combine with Laravel Forge/Envoyer for zero-downtime deploys:

   $deployer->setPreActivate(function () {
       shell_exec('php artisan down');
   });
   $deployer->setPostActivate(function () {
       shell_exec('php artisan up');
   });
   

2. Queue Workers Restart queue workers post-deploy:

   $deployer->setPostDeploy(function () {
       shell_exec('pkill -f "php artisan queue:work" && php artisan queue:work --daemon');
   });
   

3. Horizon Integration For Laravel Horizon, include:

   $deployer->setPostDeploy(function () {
       shell_exec('php artisan horizon:terminate');
       shell_exec('php artisan horizon:start');
   });