Laravel Deployer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require omaralalwi/laravel-deployer
   

   Publish the config file:

   php artisan vendor:publish --provider="OmarAlalwi\Deployer\DeployerServiceProvider"
   

2. Configure .env: Add your SSH credentials and server details to .env:

   DEPLOYER_SSH_HOST=your_server_ip
   DEPLOYER_SSH_USER=your_ssh_user
   DEPLOYER_SSH_KEY_PATH=~/.ssh/id_rsa
   DEPLOYER_REPO_URL=git@github.com:your/repo.git
   DEPLOYER_REPO_BRANCH=main
   

3. First Deployment: Run the deploy command:

   php artisan deployer:deploy
   

   Verify the deployment via the web UI (if enabled) or SSH.

First Use Case: Zero-Downtime Deployment

1. Configure Zero-Downtime: In config/deployer.php, set:

   'zero_downtime' => true,
   'deploy_path' => '/var/www/your-app/releases',
   'shared_path' => '/var/www/your-app/shared',
   'current_path' => '/var/www/your-app/current',
   

2. Deploy:

   php artisan deployer:deploy --zero-downtime
   

   The package handles symlink swapping and PHP-FPM/Nginx restarts (if configured).

Implementation Patterns

Workflow: CI/CD Integration

1. GitHub Actions Example:

   name: Deploy Laravel
   on:
     push:
       branches: [ main ]
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - uses: actions/setup-php@v2
           with:
             php-version: '8.2'
         - run: composer install -o --no-dev
         - run: php artisan deployer:deploy
           env:
             DEPLOYER_SSH_HOST: ${{ secrets.SSH_HOST }}
             DEPLOYER_SSH_KEY: ${{ secrets.SSH_KEY }}
   

2. Environment-Specific Deployments: Use --env flag or environment variables:

   php artisan deployer:deploy --env=staging
   

   Configure environments in config/deployer.php:

   'environments' => [
       'staging' => [
           'branch' => 'staging',
           'deploy_path' => '/var/www/staging-app',
       ],
       'production' => [
           'branch' => 'main',
           'deploy_path' => '/var/www/prod-app',
       ],
   ],
   

Integration Tips

1. Custom Commands: Extend deployment with custom scripts in config/deployer.php:

   'extra_commands' => [
       'post_deploy' => [
           'php artisan cache:clear',
           'php artisan config:clear',
       ],
       'post_rollback' => [
           'php artisan cache:clear',
       ],
   ],
   

2. Node.js Support: Configure Node.js dependencies in config/deployer.php:

   'nodejs' => [
       'install' => true,
       'version' => '18',
       'commands' => [
           'npm install',
           'npm run build',
       ],
   ],
   

3. PHP Restart: Add custom PHP restart logic (e.g., for PHP-FPM):

   'php_restart' => [
       'command' => 'sudo systemctl restart php8.2-fpm',
       'enabled' => true,
   ],
   

Gotchas and Tips

Pitfalls

1. SSH Key Issues:

   • Ensure DEPLOYER_SSH_KEY_PATH points to a valid key with proper permissions (chmod 600 ~/.ssh/id_rsa).
   • If SSH fails, debug with:

     ssh -T -i ~/.ssh/id_rsa your_ssh_user@your_server_ip
     

2. Permission Errors:

   • Avoid running as root unless necessary (disable php_restart if using sudo is restricted).
   • Set correct permissions for deploy_path and shared_path:

     sudo chown -R your_ssh_user:www-data /var/www/your-app
     

3. Zero-Downtime Quirks:

   • Ensure current_path symlink is writable.
   • If using Nginx, verify try_files directives in your server block point to the correct current_path.

Debugging

1. Verbose Output: Enable debug mode in .env:

   DEPLOYER_DEBUG=true
   

   Or use the --verbose flag:

   php artisan deployer:deploy --verbose
   

2. Dry Run: Test deployment without changes:

   php artisan deployer:deploy --dry-run
   

3. Logs: Check server logs for errors:

   tail -f /var/www/your-app/releases/*/storage/logs/laravel.log
   

Extension Points

1. Custom Deployment Scripts: Override default behavior by publishing and modifying:

   php artisan vendor:publish --tag=deployer-scripts
   

   Edit resources/views/deployer/scripts.blade.php for custom logic.

2. Web UI (Future Feature): Monitor deployments via the planned UI (check TODO in the repo). For now, use:

   php artisan deployer:list-releases
   

3. Branch-Specific Deployments: Dynamically set branches via environment variables or CLI:

   php artisan deployer:deploy --branch=feature/x
   

Configuration Quirks

1. Shared Paths: Ensure shared_path includes files like .env and storage/logs:

   'shared' => [
       'storage/logs',
       'storage/framework/sessions',
       'storage/framework/cache',
       'public/storage',
       '.env',
   ],
   

2. PHP Version Mismatch: If using multiple PHP versions, specify the correct path in config/deployer.php:

   'php_path' => '/usr/bin/php8.2',
   

3. Composer Cache: Clear Composer cache on the server if deployments fail:

   'extra_commands' => [
       'pre_deploy' => [
           'composer clear-cache',
       ],
   ],