Laravel Vapor to Cloud Migration Guide

Step-by-step guide for migrating Laravel projects from Vapor to Cloud. For Cloud-specific configuration patterns and known gotchas, see the Configuration Reference in the Laravel Cloud overview.

Migration Checklist

1. Initial Setup

• Create app in Laravel Cloud (connect GitLab repo)
• Set environment name (staging/production)
• Configure branch (Cloud defaults to "master")
• Copy env vars from Vapor equivalent environment

  APP_KEY, APP_DEBUG, DB_*, etc.

• Deploy and verify on .laravel.cloud domain

2. Code Changes

Remove Vapor:

• Delete vapor.yml, vapor.staging.yml, vapor.production.yml
• Delete vapor.sh, deploy.sh, vapor-base.Dockerfile, post-deploy scripts
• Remove laravel/vapor-cli and laravel/vapor-core from composer
• Clean up .gitignore (remove Vapor, Homestead, Vagrant entries)
• Remove orphaned vapor-ui public assets if present

Update CI/CD:

• Replace Vapor deploy with Laravel Cloud deploy hooks (see How We Deploy)
• Remove post-deploy health checks (hooks are async - see Deploy Hooks Are Async)
• Add LARAVEL_CLOUD_STAGING_DEPLOY_HOOK and LARAVEL_CLOUD_PRODUCTION_DEPLOY_HOOK CI variables

Configure Build/Deploy Commands (in Laravel Cloud dashboard):

• Build commands (typical):

  composer install --no-dev --optimize-autoloader
  php artisan event:cache
  php artisan config:cache
  php artisan route:cache

• Deploy commands:

  php artisan migrate --force
  php artisan optimize

3. Optimizations

• Configure faster CPU (if needed for workload)
• Enable persistent DB connections - disable in test environment
• Add php artisan optimize to deploy commands (see artisan optimize)
• Replace Sentry with Nightwatch (server-side PHP only)
  • Remove sentry/sentry-laravel package
  • Install laravel/nightwatch
  • Remove Sentry config and logging channel
  • Remove Sentry deploy notifications from CI
  • Note: Nightwatch env vars are auto-injected by Cloud
  • Keep Sentry JS SDK if project has frontend (e.g., Farfalla)

4. Queue/Horizon Setup (if applicable)

See Horizon, Queue Connection, and Valkey in the Configuration Reference.

• Move laravel/horizon from require-dev to require (if dev-only)
• Add QUEUE_CONNECTION=redis to env vars (not auto-set by Cloud!)
• Add REDIS_USERNAME to env vars (Cloud uses Valkey ACL)
• Configure Horizon supervisors for each environment in config/horizon.php
• Enable horizon:snapshot for non-local environments
• Add HTTP Basic Auth middleware for Horizon (Cloud doesn't auto-protect)
• Create Worker Cluster in Laravel Cloud dashboard
  • Add background process: php artisan horizon
  • Configure compute size for queue workload

5. Domain Swap

• Add custom domain in Laravel Cloud
• Create CNAME in Cloudflare pointing to Laravel Cloud (proxy ON)
• Wait for DNS propagation
• Test custom domain
• Disable the .laravel.cloud domain

6. Final Cleanup

• Monitor for issues in Nightwatch
• Remove any unused health check commands
• Update documentation:
  • Laravel Cloud Overview - mark service as Cloud in the services table
  • AWS Infrastructure Overview - says infra is orchestrated through Vapor
  • File Storage Architecture - S3 bucket naming references Vapor
  • Caddy HTTPS Servers - links to Vapor custom domains article

---

Resources

• Laravel Cloud Docs
• Vapor to Cloud Migration Guide
• Latency Benchmarks - Performance comparison data