Easy Deploy Bundle Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require dbh/easy-deploy-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Dbh\EasyDeployBundle\DbhEasyDeployBundle::class => ['all' => true],
   ];
   

2. Configure SSH Ensure SSH access is set up for your remote servers (see Local SSH Config Tutorial). Example ~/.ssh/config:

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

3. First Deployment Run the default deployer via CLI:

   php bin/console easy-deploy:deploy staging
   

   This triggers a zero-downtime deploy to the staging server.

First Use Case: Deploying to a Single Server

• Use the default deployer (DefaultDeployer) for basic workflows (clone, symlink, restart services).
• Verify the easy_deploy.yaml config (auto-generated in config/packages/dbh_easy_deploy.yaml) matches your server’s paths (e.g., deploy_path, release_path).

Implementation Patterns

Core Workflows

1. Multi-Stage Deployments Define stages in config/packages/dbh_easy_deploy.yaml:

   dbh_easy_deploy:
       servers:
           staging:
               host: staging
               deploy_path: /var/www/staging
           production:
               host: production
               deploy_path: /var/www/prod
   

   Deploy to multiple stages sequentially:

   php bin/console easy-deploy:deploy staging production
   

2. Custom Deployer Integration Extend DefaultDeployer for project-specific logic (e.g., database migrations, asset compilation):

   // src/Deployer/CustomDeployer.php
   namespace App\Deployer;
   
   use Dbh\EasyDeployBundle\Deployer\AbstractDeployer;
   
   class CustomDeployer extends AbstractDeployer {
       protected function deploy(): void {
           $this->run('php bin/console doctrine:migrations:migrate --no-interaction');
           parent::deploy();
       }
   }
   

   Register in config/packages/dbh_easy_deploy.yaml:

   dbh_easy_deploy:
       deployer: App\Deployer\CustomDeployer
   

3. Git Hooks & Pre/Post Actions Use pre_deploy and post_deploy hooks in the config:

   dbh_easy_deploy:
       servers:
           staging:
               pre_deploy: ['php bin/console cache:clear']
               post_deploy: ['systemctl restart php-fpm']
   

Integration Tips

• Symfony Flex Recipes: Use the bundle’s recipe to auto-configure paths during composer install.
• Environment Variables: Pass server-specific vars via deploy_vars in the config:

  servers:
      production:
          deploy_vars:
              APP_ENV: prod
              DATABASE_URL: "mysql://user:pass@localhost/db"
  

• Docker (Non-Containerized): Use deploy_path pointing to a bind-mounted volume for shared storage.

Gotchas and Tips

Pitfalls

1. SSH Key Permissions

   • Ensure ~/.ssh/id_rsa has 600 permissions (chmod 600 ~/.ssh/id_rsa).
   • Debug connection issues with:

     ssh -vT staging
     

2. File Ownership

   • Remote deploy_path must be writable by the SSH user (e.g., chown -R deploy:deploy /var/www/staging).

3. Git Shallow Clone

   • The bundle uses --depth 1 by default. Disable with:

     dbh_easy_deploy:
         git_depth: false
     

4. Symlink Conflicts

   • Avoid symlinking to directories with spaces or special characters. Use absolute paths in symlinks config:

     symlinks:
         - { from: '{{ release_path }}/var/log', to: '{{ deploy_path }}/var/log' }
     

Debugging

• Verbose Mode: Enable for detailed logs:

  php bin/console easy-deploy:deploy staging --verbose
  

• Dry Run: Test without changes:

  php bin/console easy-deploy:deploy staging --dry-run
  

• Custom Logging: Override AbstractDeployer::log() for project-specific logging.

Extension Points

1. Custom Commands Add new commands by extending AbstractDeployer and registering them in services.yaml:

   services:
       App\Deployer\CustomCommand:
           tags: ['console.command']
           arguments: ['@dbh_easy_deploy.deployer']
   

2. Remote Script Execution Use run() in custom deployers to execute arbitrary commands:

   $this->run('composer install --optimize-autoloader --no-dev');
   

3. Post-Deploy Validation Implement postDeploy() to validate the release (e.g., check file integrity):

   protected function postDeploy(): void {
       $this->assertFileExists('{{ release_path }}/vendor/autoload.php');
   }
   

Config Quirks

• Dynamic Paths: Use Twig-like syntax ({{ release_path }}) for dynamic paths in symlinks or deploy_vars.
• Default Values: The bundle auto-generates easy_deploy.yaml with sensible defaults. Override only what’s necessary.
• Git Repository: Ensure the remote server has Git installed and the SSH user has access to the repo. For private repos, configure deploy keys on the server.