Laravel Docker Deploy Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require adacto-company/laravel-docker-deploy
   

   Publish the config file:

   php artisan vendor:publish --provider="Adacto\LaravelDockerDeploy\LaravelDockerDeployServiceProvider" --tag="config"
   

2. First Use Case: Basic Deployment Add a deploy.php file in your project root (or configure in config/laravel-docker-deploy.php):

   <?php
   return [
       'servers' => [
           'production' => [
               'host' => 'your-server.com',
               'user' => 'deploy-user',
               'port' => 22,
               'repository' => 'git@github.com:your/repo.git',
               'branch' => 'main',
               'deploy_path' => '/var/www/your-app',
           ],
       ],
       'shared_files' => ['.env'],
       'shared_dirs' => ['storage'],
       'writable_dirs' => ['bootstrap/cache', 'storage/framework'],
   ];
   

3. Run Deployment

   php artisan docker:deploy production
   

Key Files to Review

• Config: config/laravel-docker-deploy.php (default settings, hooks, and server definitions).
• Hooks: app/DeployHooks/ (custom logic for pre/post-deployment steps).
• Dockerfile: Ensure your Dockerfile is optimized for multi-stage builds if using Docker.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Trigger deployments from GitHub Actions, GitLab CI, or Jenkins:

   # Example GitHub Actions workflow
   - name: Deploy to Production
     run: php artisan docker:deploy production
     env:
       SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
   

2. Environment-Specific Configs Use environment variables or separate config files for different stages:

   // config/laravel-docker-deploy.php
   'servers' => env('DEPLOY_SERVERS', []),
   

3. Docker Compose Integration Extend the package to rebuild and restart containers post-deploy:

   // In deploy.php or hooks
   'post_deploy' => [
       'docker-compose down',
       'docker-compose up -d --build',
   ],
   

4. Zero-Downtime Deployments Use rolling updates with Docker:

   'post_deploy' => [
       'docker service update --force --image your-image:latest your-service',
   ],
   

Common Patterns

• Shared Assets: Leverage shared_files and shared_dirs to persist .env, storage, or public/uploads.
• Database Migrations: Run migrations post-deploy via hooks:

  'post_deploy' => [
      'php artisan migrate --force',
  ],
  

• Artisan Commands: Chain commands for optimization:

  php artisan docker:deploy production --optimize --no-interaction
  

Gotchas and Tips

Pitfalls

1. SSH Key Management

   • Ensure ~/.ssh/id_rsa is added to deploy_keys in GitHub/GitLab or configured via SSH_AUTH_SOCK.
   • Fix: Use SSH_PRIVATE_KEY env var or ~/.ssh/config:

     Host your-server.com
       IdentityFile ~/.ssh/deploy_key
       IdentitiesOnly yes
     

2. Permission Issues

   • Writable dirs (e.g., bootstrap/cache) may fail if permissions aren’t set.
   • Fix: Add chmod in hooks:

     'post_deploy' => [
         'chmod -R 775 ' . config('laravel-docker-deploy.writable_dirs'),
     ],
     

3. Docker-Specific Quirks

   • If using Docker, ensure the deploy user is in the docker group or use docker exec with sudo.
   • Fix: Configure deploy_path to match your Docker volume mount point.

4. Hook Execution Order

   • Hooks run in this order: pre_deploy, deploy, post_deploy, post_rollback.
   • Tip: Use return false; in hooks to abort deployment.

Debugging Tips

• Verbose Output: Enable debug mode in config:

  'debug' => true,
  

• Dry Runs: Test deployments without changes:

  php artisan docker:deploy production --dry-run
  

• Log Inspection: Check /tmp/laravel-docker-deploy.log for errors.

Extension Points

1. Custom Hooks Create reusable hooks in app/DeployHooks/:

   // app/DeployHooks/ExampleHook.php
   namespace App\DeployHooks;
   
   class ExampleHook {
       public function handle() {
           // Custom logic (e.g., purge cache)
           \Artisan::call('cache:clear');
       }
   }
   

   Register in config/laravel-docker-deploy.php:

   'hooks' => [
       'pre_deploy' => \App\DeployHooks\ExampleHook::class,
   ],
   

2. Event Listeners Listen to deployment events:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \Adacto\LaravelDockerDeploy\Events\DeploymentStarted::class => [
           \App\Listeners\LogDeployment::class,
       ],
   ];
   

3. Docker Compose Templates Use templates for dynamic docker-compose.yml generation:

   'post_deploy' => [
       'envsubst < docker-compose.template.yml > docker-compose.yml',
       'docker-compose up -d',
   ],