​
Introduction

Laravel Cloud applications can be made up of many environments, such as “production”, “staging”, or even short-lived environments used for trialing new features you’re developing for your application. Compute infrastructure, resources, and deployment settings are unique to each environment, allowing you to fine-tune each environment based on its purpose. For example, you might wish to assign small, hibernating compute instances to your staging environment, while larger, non-hibernating compute instances are assigned to your production environment.

​
Build and Deploy Commands

You may define how both the frontend and backend of your application are built during deployment from the “Deployments” section of your environment settings.

​
Build Commands

Build commands allow you to customize the build process for your application. Typically, this will involve customizing how you want Composer and NPM dependencies to be installed. In addition, you may add any custom build scripts or commands that are specific to your Laravel application.

​
Private Composer Packages

To allow the installation of private Composer packages, you will need to configure your application’s Composer HTTP authentication credentials for each package using the composer config command. You should add this command to your build commands prior to invoking composer install: 
composer config http-basic.composer.fluxui.dev your-username your-license-key

composer install --no-dev
Build commands must complete within 15 minutes or they will timeout.

​
Dynamic Environment Variables

If you dynamically add any environment variables during your build process, you must run php artisan config:cache or php artisan optimize afterwards to ensure the configuration is properly cached: 
# Adding a dynamic environment variable
echo "MY_DYNAMIC_VAR=value" >> .env

# Then cache the configuration
LARAVEL_CLOUD=1 php artisan config:cache
Running php artisan optimize or php artisan config:cache is only necessary if you’re dynamically adding environment variables during the build process.
When you need to run php artisan optimize or php artisan config:cache (for example, after adding dynamic environment variables), you must prefix these commands with LARAVEL_CLOUD=1 to ensure all Laravel Cloud configurations are properly loaded: 
LARAVEL_CLOUD=1 php artisan optimize

# Or
LARAVEL_CLOUD=1 php artisan config:cache
The LARAVEL_CLOUD=1 environment variable ensures that all Laravel Cloud-specific configurations are in place during the build process.

​
Deploy Commands

Your environment’s “Deploy Commands” are run on your Laravel Cloud infrastructure just before a new deployment goes “live”. Typically, these commands will be used to migrate your environment’s database. Unlike build commands, changes made to the filesystem by deploy commands will not be persisted to your application.
Deploy commands must complete within 15 minutes or they will timeout.

​
Unnecessary Build and Deploy Commands

The following commands are either automatically handled by Laravel Cloud or should not be run during deployment:
  • php artisan queue:restart - Queue workers are automatically restarted after each deployment
  • php artisan horizon:terminate - Horizon processes are automatically managed during deployments
  • php artisan optimize - This command has no effect during the deploy phase as optimizations should be done during build
  • php artisan optimize:clear - This clears the cache and can cause unexpected behavior, especially related to the queue
  • php artisan storage:link - The symbolic link won’t persist as changes made during deploy commands are not saved. Use Laravel Object Storage for persistent file storage instead.
Typically, your deploy commands should only include database migrations and other essential post-deployment tasks.

​
Environment Settings

​
Environment Variables

Within your environment’s settings, the environment variables section allows you to customize the .env variables available to your environment.
In addition to injecting your custom environment variables, Laravel Cloud will automatically inject a variety of environment variables into your environment on your behalf, including any credentials necessary to connect to Laravel Cloud resources like databases, key-value storage, or object storage.
Custom environment variables take priority and will override any automatically injected environment variables.
After changing an environment’s variables, a re-deployment is required in order for the changes to take effect.

​
PHP Version

Currently, Laravel Cloud supports PHP 8.2, 8.3, and 8.4. You may select the PHP version that should be used by an environment on the environment’s General Settings page. After changing the PHP version, a re-deployment is required in order for the changes to take effect.

​
PHP Extensions

Laravel Cloud currently supports the following PHP extensions: 
apcu, bcmath, calendar, Core, ctype, curl, date, dom, ev, excimer, exif,
fileinfo, filter, ftp, gd, gettext, gmp, hash, iconv, igbinary, imagick,
imap, intl, json, ldap, libxml, mbstring, mongodb, msgpack, mysqli,
mysqlnd, openssl, pcntl, pcre, PDO, pdo_mysql, pdo_pgsql, pdo_sqlite, pdo_sqlsrv,
Phar, posix, pspell, random, readline, redis, Reflection, session, shmop,
SimpleXML, soap, sockets, sodium, SPL, sqlite3, sqlsrv, standard, tokenizer, xml,
xmlreader, xmlwriter, xsl, Zend OPcache, zip, zlib.
You can also list the currently loaded extensions by running php -m using Laravel Cloud’s “Command” feature in your environment dashboard.

​
PHP Memory Limit

Laravel Cloud allocates PHP memory dynamically based on a percentage of your instance’s total memory. If your application requires a specific amount, you can override this by defining a new memory_limit. You can override the default memory limit by adding configuration directly in your application code. The most common method is to update your public/index.php and your artisan file: 
<?php

// Set memory limit to 512 MB...
ini_set('memory_limit', '512M');

// Or, remove memory limits entirely...
ini_set('memory_limit', -1);
Or, you can set the memory limit via build commands to avoid modifying your project’s source code: 
# Add memory_limit to the top of the public/index.php file...
sed -i 's/<?php/<?php\nini_set('\''memory_limit'\'', '\''512M'\'');/g' public/index.php

# Add memory_limit to the top of the artisan file...
sed -i 's/<?php/<?php\nini_set('\''memory_limit'\'', '\''512M'\'');/g' artisan
Memory adjustments should be made early in your application’s lifecycle to ensure optimal performance. Excessive memory usage can negatively impact overall application efficiency. While setting the memory limit to -1 removes all memory restrictions, this option should be used with caution, especially in production environments, as it can lead to unpredictable behavior. For more information regarding PHP memory configuration, consult the official PHP documentation.

​
Node Version

From your environment’s General Settings page, you may select the Node version that should be available to the build commands used to build your application during a deployment. After changing the Node version, a re-deployment is required in order for the changes to take effect.

​
Cloud Domains

Each Laravel Cloud environment is assigned a free laravel.cloud domain the first time it is deployed successfully. This makes it easy to test and build your application before attaching a custom domain. Laravel Cloud domains are constructed using a combination of your application and environment name. If either of these names are changed, the Laravel Cloud domain will be updated to reflect the changes. A redeployment is required for this change to take effect.

​
Custom Domains

Of course, before shipping your application to the world, you will likely want to assign your own custom domain name to your production environment. To get started, click “Add domain” on your environment’s infrastructure canvas dashboard. From the domain settings page, you will be able to add a custom domain to the environment. When adding the domain, Laravel Cloud will guide you through the steps necessary to verify your ownership of the domain being added. The domain verification process will require you to add several DNS records to your domain registrar or DNS provider’s DNS settings. Once your custom domain has been verified, you will be able to access the corresponding environment via the domain. You may detach the custom domain from an environment or re-assign the custom domain to another environment at any time from your environment’s domain settings page.
Adding a custom domain to an environment requires the organization that owns the environment to be subscribed to the Production billing plan.

​
Wildcard Domains

If you require wildcard subdomain support on your custom domain, you must carry out pre-verification in order to prove ownership of the entire domain. Therefore, you should make sure you add the DCV delegation record provided to you in the Laravel Cloud dashboard to ensure the wildcard SSL certificates continue to be issued. When configuring wildcard domains (e.g., *.example.com), you must also add and point the root domain (e.g., example.com) to Laravel Cloud. Both the wildcard domain and the root domain must be properly configured with the appropriate DNS records pointing to your Laravel Cloud environment. Finally, if your domain / DNS is managed by Cloudflare, you should disable the Cloudflare proxy (Orange Cloud) to allow the domain to be verified.

​
Troubleshooting Domain Verification

If your domain fails verification or seems to be taking a long time to verify, there are a few things you should check:
  • If you are carrying out pre-verification, ensure you have added the records correctly. Some DNS providers require you to add the domain when setting the name of the DNS records, while others do not. This can result in an invalid record. For example, if the DNS provider adds the domain portion of the record name on your behalf, but you also add it when creating the record, you may end up with a record that contains a duplicate domain e.g. _cf-custom-hostname.example.com.example.com vs. _cf-custom-hostname.example.com
  • If you are carrying out real-time verification, ensure the domain is pointed correctly at Laravel Cloud’s A record provided to you in the UI. You can also try making a request to the domain to allow us to pick up the traffic flowing into our network.

​
Limitations

There are no limitations on the number of Cloud environments that can have a custom domain assigned to them. However, there are some limitations on assigning multiple custom domains to a single environment that are determined by your plan:
  • Starter: 1 custom domain per environment
  • Growth: Up to 5 custom domains per environment
  • Business: Up to 20 custom domains per environment
  • Enterprise: Custom
Most users are not impacted by these limits, but if you have a special use case for assigning many domains to a single environment (e.g. multi-tenant applications), please contact us to discuss raising your limits.

​
Stop and Restart

To stop an environment, click the ”…” button next to the environment’s “Deploy” button. Then, click “Stop”. When you stop an environment, all App and Worker clusters within the environment will be shutdown. This means all web traffic, background processes, and scheduled tasks will stop processing. You will not be charged for the environment’s compute, but you will still be charged for any attached resources. You can restart the environment using the same dropdown menu. A full deployment is required to restart an environment.

​
Replicate

It is common for environments in the same application to have similar or identical resource and settings configurations. Therefore, when creating new environments, it is often more convenient to clone an existing environment and make changes rather than creating a new environment from scratch. To replicate an environment, click the ”…” button next to the environment’s “Deploy” button. Then, click “Replicate”. Confirm you are replicating the correct environment and git branch, then enter a name for your new environment. By default, all General, Environment, and Deployment settings will be duplicated. You can optionally edit the default replication settings for compute and resources. The default replication behavior is:
  • Compute: duplicate all clusters (including size, autoscaling, hibernation, scheduler, Octane, Inertia, and background process settings)
  • Database: use the same database compute / storage cluster, but create a new logical database schema
  • Cache: use the same KV Store instance, but add a unique CACHE_PREFIX environment variable to your application
  • Object storage: no replication
Review and edit the “Replication options” as needed before deploying your new environment. The defaults provided are a sensible balance between cost and performance, but may not be right for your application’s specific use case. Use extra care when replicating a production environment to avoid reusing resources in a way that will impact performance or interfere with queued jobs, sessions, or other application data.

​
Commands

Laravel Cloud allows you to execute commands directly in your environment. Navigate to your environment’s “Commands” tab to run one-time commands such as php artisan cache:clear.
Commands should be non-interactive and may not run for more than 15 minutes.
Commands will be executed on any available instance in your environment.

​
Preview Environments

Preview Environments let you automatically spin up fully isolated environments for every pull request. This allows you to safely test changes, share previews with your team, and catch issues before merging, all without impacting your main application environments. Preview Environment automations are configured at the application level. Each app in your organization can have its own automation rules and preview workflows.
Preview Environments are available for Growth and Business plan customers.

​
How Preview Environments Work

When you configure a Preview Environment automation on your app:
  1. Laravel Cloud listens for pull requests or new branch events on your linked repository.
  2. When triggered, a new preview environment is created.
  3. The environment is based on a specified existing environment (e.g. main), including compute, resources, and environment variables.
  4. The environment can be deployed automatically or manually, depending on your deployment settings.
  5. The preview environment lives independently until the branch or pull request is closed. If auto-destroy is enabled, the environment will be automatically removed; otherwise, manual cleanup is required.

​
Configuring Preview Environments

To configure a Preview Environment automation:
  1. Go to your Laravel Cloud organization.
  2. Select the app you want to configure.
  3. Navigate to Settings → Preview environments.
  4. Click + New automation to create a new preview environment rule.

​
Automation Settings

  • Automation name: Enter a descriptive name for your automation.
  • Environment to replicate: Select which existing environment (e.g. main) to use as a base. This environment’s configuration (compute, resources, environment variables, etc.) will be used for each preview environment.
  • Automation triggers on:
    • New pull requests: Automatically create a preview environment when a pull request is opened against a target branch.
    • New branches: Automatically create a preview environment when a new branch is pushed.
  • Target branch: If using pull request triggers, select which branch to listen for pull requests against (e.g. main).
  • Filter by branch name (optional): Only run automation if the branch name matches a specific pattern.

​
Replication Options

Choose which resources to duplicate, reuse, or ignore for preview environments:
  • Compute clusters: Use default or custom compute settings.
  • Database: Optionally attach a database instance.
  • Cache: Optionally attach a cache resource.
  • Object storage: Optionally attach object storage.
  • Custom environment variables: Specify variables to override or add for preview environments.

​
Deployment Options

  • Auto deploy on trigger: Enable to automatically deploy the preview environment upon creation. When disabled, environments are created but require manual deployment.
  • Auto destroy environment and resources: Enable to automatically destroy the preview environment and its resources when the pull request is merged or closed. When disabled, environments must be manually deleted.
  • Initial deploy commands: Optionally specify shell commands to run after the first deploy (e.g. php artisan migrate --force). These commands are useful for setting up preview-specific data or configurations.

​
Managing Preview Environments

  • Active preview environments appear under your app’s Environments tab.
  • Preview environments are named after the pull request or branch.
  • When you push new commits to a pull request, the associated preview environment will automatically rebuild and redeploy.

​
Best Practices

  • Keep preview environments lightweight by limiting attached resources.
  • Use seeded test data rather than copying production data.
  • Use feature flags or environment variables to control preview-only behavior.
  • Monitor resource usage when running multiple previews concurrently.
Preview Environments reuse the APP_KEY from the replicated environment. Avoid connecting preview environments to production databases, caches, or other sensitive resources. We recommend against replicating a production environment for previews. If you share a database cluster or schema across environments, be aware that running migrations or making breaking changes can impact other environments.

​
Filesystem

Environment filesystems are ephemeral, meaning files may not persist across requests or jobs. New deployments or re-deployments will reset the filesystem. In addition, each replica of your compute cluster has its own filesystem. Thus, you should treat the filesystem as temporary, unshared disk space that is only consistent during a single request or job. The total disk space available on each replica is proportional to the compute / RAM of the cluster. Every 1GB of RAM is equal to 512MB of disk space. For example, a cluster with 2GB of RAM will have 1GB of ephemeral disk space available to it. If you exceed the available disk space, your application may crash and the deployment may need to restart. We recommend using redis or database drivers for a persistent cache and session via a KV Store or database resource. For persistent file storage, use the s3 driver via Laravel Object Storage.

​
Nightwatch Integration

Laravel Cloud environments have built-in support for Laravel Nightwatch monitoring. Nightwatch provides deep insights into your application environment’s performance, exceptions, logs, and overall health.
1

Install Nightwatch package

Install the Laravel Nightwatch package in your application locally using Composer:
composer require laravel/nightwatch
Run composer require laravel/nightwatch on your local machine to update your composer.json and composer.lock files before deploying.
2

Connect Nightwatch

Click the Connect Nightwatch button in your environment dashboard.
3

Enable monitoring

Toggle Enable monitoring to activate Nightwatch for your environment.
4

Enter your Nightwatch token

Enter your Nightwatch token, which you can find in your Nightwatch application settings.
Enabling Nightwatch will automatically run the agent across all the App compute and Worker clusters in the environment. You can setup Nightwatch manually if you want the agent to run on specific instances.
When enabled, Laravel Cloud will automatically inject the following environment variables into your environment: 
NIGHTWATCH_TOKEN=
NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1
LOG_CHANNEL=stack
LOG_STACK=laravel-cloud-socket,nightwatch
You can override these variables in your environment variable settings if needed.
If you have previously configured Nightwatch manually with a background process, you must remove that process from every cluster before enabling the built-in integration to avoid issues with your environment.