Vapor Cli Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/vapor-cli --dev
   

   Ensure the package is autoloaded in composer.json under require-dev.

2. Authentication:

   • Configure AWS credentials via:
     • Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY).
     • ~/.aws/credentials file.
     • IAM roles (if running on AWS infrastructure).
   • Verify credentials with:

     vapor auth:verify
     

3. First Use Case: Deploy a Laravel app to Vapor:

   vapor deploy production --yes
   

   • Prerequisite: A Vapor project must exist (created via vapor new in the Laravel Vapor dashboard).

Where to Look First

• Official Docs: Vapor Documentation (covers CLI, architecture, and AWS integrations).
• CLI Commands: Run vapor or vapor list to see available commands.
• Project Structure: After deploying, inspect the generated vapor/ directory in your Laravel app for configuration files (e.g., vapor.yml, queue.yml).

Implementation Patterns

Core Workflows

1. Deployment Pipeline:

   • Local Testing: Use vapor serve to test Lambda functions locally.
   • Staged Deployments:

     vapor deploy staging --yes
     vapor deploy production --yes
     

   • Rollbacks:

     vapor rollback production
     

2. Infrastructure Management:

   • Update Vapor Configuration: Edit vapor.yml and redeploy:

     vapor deploy production --yes
     

   • Add/Remove Resources: Modify vapor.yml to include new queues, databases, or Redis clusters, then deploy.

3. Queue Management:

   • Queue Configuration: Define queues in queue.yml (e.g., SQS, Redis).
   • Scaling: Adjust concurrency in vapor.yml under queue:

     queue:
       worker:
         concurrency: 25
     

4. Environment Variables:

   • Use vapor env to manage environment variables across stages:

     vapor env:add production KEY=VALUE
     

Integration Tips

• CI/CD Integration:

  • Use vapor deploy in GitHub Actions/GitLab CI with AWS credentials as secrets.
  • Example GitHub Actions workflow:

    - name: Deploy to Vapor
      run: vendor/bin/vapor deploy production --yes
      env:
        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
    

• Local Development:

  • Mock AWS services locally using tools like LocalStack or SAM CLI.
  • Test Lambda functions with vapor serve --function=YourFunction.

• Monitoring:

  • Use vapor logs to stream Lambda logs:

    vapor logs production --function=YourFunction
    

  • Integrate with AWS CloudWatch for deeper insights.

Gotchas and Tips

Pitfalls

1. AWS Credentials:

   • Issue: vapor commands fail with AccessDenied errors.
   • Fix: Ensure IAM roles have permissions for vapor, lambda, dynamodb, sqs, etc. Use the Vapor IAM Policy as a reference.
   • Tip: Use temporary credentials (e.g., via aws sts assume-role) for CI/CD to avoid hardcoding keys.

2. Configuration Mismatches:

   • Issue: Deployments fail due to mismatched vapor.yml between local and Vapor dashboard.
   • Fix: Always sync vapor.yml with the dashboard after manual changes. Use vapor config:pull to fetch the latest configuration from Vapor.

3. Cold Starts:

   • Issue: Lambda functions experience latency on first invocation.
   • Fix:
     • Increase memory in vapor.yml (e.g., memory: 1024).
     • Use Provisioned Concurrency for critical functions.
     • Configure reserved concurrency in vapor.yml:

       functions:
         your-function:
           reserved: 1
       

4. Queue Timeouts:

   • Issue: Long-running jobs fail with Task timed out after X seconds.
   • Fix: Adjust timeout in queue.yml (default: 900 seconds):

     queues:
       default:
         timeout: 1800
     

Debugging

• Lambda Logs:

  • Use vapor logs to debug runtime errors. Filter by function:

    vapor logs production --function=YourFunction --tail=50
    

  • Check CloudWatch Logs directly in the AWS Console for historical logs.

• Local Testing:

  • Test Lambda functions locally with vapor serve and simulate events:

    vapor serve --function=YourFunction --event='{"key":"value"}'
    

• Dependency Issues:

  • Issue: Deployments fail due to missing or incompatible dependencies.
  • Fix:
    • Ensure composer.json is up-to-date.
    • Use vapor deploy --no-warm to skip warm-up (useful for debugging).
    • Check vapor/storage/logs for deployment logs.

Extension Points

1. Custom Commands:

   • Extend the CLI by publishing a custom command:

     // app/Console/Commands/CustomVaporCommand.php
     namespace App\Console\Commands;
     use Illuminate\Console\Command;
     use Laravel\Vapor\Vapor;
     
     class CustomVaporCommand extends Command
     {
         protected $signature = 'vapor:custom {action}';
         public function handle(Vapor $vapor)
         {
             // Custom logic using $vapor->client
         }
     }
     

   • Register the command in app/Console/Kernel.php.

2. Pre/Post-Deploy Hooks:

   • Use Laravel’s deploy event to run scripts before/after deployment:

     // app/Providers/EventServiceProvider.php
     public function boot()
     {
         event(new \Laravel\Vapor\Events\Deploying);
         // Add listeners for Deploying/Deployed events
     }
     

3. Environment-Specific Configs:

   • Override vapor.yml per environment using vapor.yml.{stage} (e.g., vapor.yml.staging).
   • Example:

     # vapor.yml.staging
     functions:
       your-function:
         memory: 512
     

4. WebSockets:

   • For WebSocket-heavy apps, configure vapor.yml to use API Gateway with WebSocket support:

     websockets:
       enabled: true
       routes:
         - '/app/{channel}'