Laravel Deploy Guide: Prepare Your App for Cloud

A Laravel deploy guide for Laravel Cloud starts with connecting your code repository, checking your build and deploy commands, and attaching the production resources your app needs. Cloud builds a new release and switches traffic after deployment checks pass, while you remain responsible for app settings, data, and testing.

Use this practical checklist to prepare a Laravel app, deploy it, and verify the result without putting secrets in your code.

Key takeaways

• Connect a GitHub, GitLab, or Bitbucket repository and choose the right branch and region.
• Confirm your PHP version, build steps, and production environment values.
• Attach a database and other managed resources through the environment’s infrastructure canvas.
• Run database migrations as deploy commands, not as part of the build.
• Test the live app, queues, scheduled tasks, uploads, and health checks after deployment.

Before you deploy your Laravel app

Start with a working application in a Git repository. Check that its tests pass locally and that its dependencies are declared in composer.json and, if needed, package.json. Keep environment-specific values out of committed code.

Laravel Cloud requires Laravel 9 or later, with minimum framework patch levels for some older release lines. Check the current Laravel Cloud deployment requirements before choosing a runtime. Using the latest compatible minor release helps you avoid deployment issues tied to outdated framework versions.

Make a list of what the production application needs: a database, file storage, a cache, a queue, or scheduled tasks. Not every app needs every service. Knowing the requirements first helps you attach the correct resources and test them deliberately.

If you are planning a larger application or need help adapting an existing project, see Herby Design’s Laravel development services. The principles in this guide still apply when you manage deployment yourself.

Connect your repository and create an environment

In the Laravel Cloud dashboard, create a new application and connect your Git provider. Authorise access, select the repository, then choose the branch you want Cloud to deploy. Use a branch that represents the code intended for that environment.

Choose an application name and a region that suits your users and resources. Keep your database in the same region as the environment, as the official guide recommends. This makes your resource setup consistent and avoids unnecessary distance between the app and its database.

Once the environment is created, review its runtime settings. Confirm that it uses PHP and select a version supported by your application and dependencies. Do not assume the version used on your laptop is automatically the best production choice; check compatibility and test the app with the selected runtime.

Cloud can deploy automatically when you push to the configured branch. Before relying on that workflow, verify the branch and environment carefully. A development branch should not accidentally deploy to production.

Set build commands and production variables

Build commands run when Cloud prepares a new deployment. They commonly install production dependencies, compile frontend assets, and cache Laravel’s configuration. Cloud may suggest defaults when it detects Laravel, but review them against your project’s actual scripts.

A typical set of build steps may look like this:

composer install --no-dev
npm ci --audit false
npm run build
php artisan optimize

Use only the steps your application needs. For example, a project without frontend assets may not need the npm commands. Check that any build script exists in your repository and that it completes successfully in the deployment environment.

Set production configuration in the environment settings, not in a committed .env file. Laravel Cloud writes environment values to a .env file before the app starts. Treat secrets such as passwords and API keys as sensitive, and avoid printing them in logs.

Cloud can generate and inject an APP_KEY on the first deploy. If you provide your own key, use a securely generated value and keep it private. Never replace a production key casually: encrypted application data may depend on it.

Attach a database and run migrations safely

Add a database from the environment’s infrastructure canvas. Laravel Cloud provides Laravel MySQL or Serverless Postgres options, and injects the connection values into the environment. After adding or changing resources, redeploy so the application receives the updated settings.

Set migrations as deploy commands. Cloud runs deploy commands before the new release goes live, so the database schema can be updated before the new code serves traffic. A common command is:

php artisan migrate --force

The --force option confirms that migrations may run in production. Review migrations before release, and take a backup when the data or change warrants it. Aim for changes that remain compatible with the previous app version during a gradual deployment—for example, add a new nullable column before making code depend on it.

Deploy commands must finish within 15 minutes, according to the Laravel Cloud Laravel deploy guide. If migrations take too long or fail, inspect the deployment logs and database connection settings before trying again. Do not repeatedly trigger a failing migration without understanding its state.

Configure storage, queues, and scheduled tasks

For uploads or other files that must persist, attach a storage bucket. Cloud provides S3-compatible credentials and sets FILESYSTEM_DISK, allowing Laravel’s Storage facade to work with the configured disk. Test both uploads and downloads using the deployed app.

Do not rely on a local application filesystem for user files that must survive deployment or be shared across instances. Use the attached bucket and confirm that access rules match your needs. Avoid making private files publicly accessible unless that is intentional.

If your app uses background jobs, attach a queue resource and check the worker configuration. Queue jobs should be safe to retry: a job may run again after a failure. Test a real job and verify how failures appear in the Cloud dashboard.

For Laravel scheduled tasks, enable the Scheduler on the app cluster or a worker cluster. Cloud invokes schedule:run every minute. Confirm that scheduled commands use the expected timezone and avoid overlapping or duplicate work.

Applications with several connected services may benefit from a clear resource plan. Herby Design also provides custom web application development for projects with specific workflows or integrations.

Deploy, check health, and verify the release

Before deploying, review pending environment changes and confirm the target branch, runtime, variables, resources, and commands. Then start the deployment from the dashboard or push a commit if push-to-deploy is enabled.

Cloud builds the application, runs the configured commands, and brings the new release online. Its deployment process is designed to switch traffic after the new deployment is ready, while allowing the previous release to wind down. Watch the deployment status and logs rather than assuming a successful build means every feature works.

Check the health-check configuration under deployment settings. Laravel Cloud supports startup, readiness, and liveness checks. A health endpoint such as /up can be used when it returns an accepted status, but ensure the endpoint is available in your app and does not depend on fragile external services.

After deployment, open the production URL and test core user journeys. Check sign-in, forms, database reads and writes, uploads, queued work, and scheduled tasks where relevant. Review application logs for errors and confirm that key environment values are present without exposing their contents.

If a health check fails, the app may not receive traffic or an instance may restart. Use the Laravel Cloud health-check documentation to review endpoint, port, timeout, and retry settings. Fix the underlying app issue before loosening checks just to make a deployment pass.

Common deployment problems and fixes

• Build fails: Check the runtime version, Composer dependencies, npm scripts, and build logs. Run the same commands locally where possible.
• Database connection fails: Confirm the database is attached to the right environment and region, then redeploy after resource changes.
• Migration error: Inspect the migration and production schema. Check whether a prior attempt partially completed before retrying.
• Uploads disappear: Store persistent files in the attached bucket, not on an instance’s local filesystem.
• Jobs do not run: Confirm the queue resource and worker setup, then test a job and inspect failed-job details.
• Health checks fail: Verify the endpoint path and response, then review timing and port settings in deployment settings.

Keep a repeatable release checklist. Note which branch is deployed, what migrations run, and which features require a manual smoke test. For ongoing operational help, consider website maintenance and technical support.

Frequently asked questions

Does Laravel Cloud need a committed .env file?

No. Add production values in environment settings. Cloud writes them to a .env file before the app starts.

Where should I run Laravel migrations?

Configure migrations as deploy commands, such as php artisan migrate --force, and review schema changes before release.

Do I need to run npm build commands?

Only if your project needs frontend assets. Check your package scripts and include the commands that your application uses.

How do I keep user uploads between deployments?

Attach a storage bucket and use Laravel’s storage tools with the configured disk. Avoid depending on local instance files for persistent uploads.

A reliable Laravel Cloud release comes from matching the runtime, commands, environment, and resources to your app, then testing the live result. Use the official Laravel deploy guide as the source of truth for platform details. Need help building or deploying a Laravel application? Contact Herby Design to discuss your project.