> ## Documentation Index > Fetch the complete documentation index at: https://cloud.laravel.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Environments > Manage Laravel Cloud environments, deployment settings, variables, domains, commands, and runtime configuration. ## Introduction A Laravel Cloud application can have many environments, such as "production", "staging", or even short-lived environments for trying out new features you're developing. Each environment has its own compute infrastructure, resources, and deployment settings, so you can tune each environment for its purpose. For example, you might give your staging environment small Flex compute instances that scale to zero, and give your production environment larger, always-on compute instances. ## Build and deploy commands You may define how your application is built during deployment from the **Deployments** section of your environment settings. ### Build commands Build commands let you customize how Laravel Cloud builds your application during deployment. **Laravel** Typically, your Laravel build command will install your Composer and npm dependencies and compile your application's assets: ```shell theme={null} composer install --no-dev && npm run build ``` > [!TIP] > > Run `php artisan optimize` or `php artisan config:cache` during the build process, not during the deploy process. #### Private Composer packages To install private Composer packages, configure your application's Composer HTTP authentication credentials for each package using the `composer config` command. Add this command to your build commands before `composer install`: ```shell theme={null} composer config http-basic.composer.fluxui.dev your-username your-license-key composer install --no-dev ``` **Symfony** Typically, your Symfony build command will install Composer dependencies and compile your application's assets: ```shell theme={null} composer install --no-dev && php bin/console asset-map:compile ``` #### Private Composer packages To install private Composer packages, configure your application's Composer HTTP authentication credentials for each package using the `composer config` command. Add this command to your build commands before `composer install`: ```shell theme={null} composer config http-basic.example.com your-username your-license-key composer install --no-dev ``` **Next.js** Typically, your Next.js build command will install Node dependencies and compile your application: ```shell theme={null} npm ci && npm run build ``` **Nuxt** Typically, your Nuxt build command will install Node dependencies and compile your application: ```shell theme={null} npm ci && npm run build ``` **JavaScript** Typically, your Node.js build command will install dependencies and compile your application: ```shell theme={null} npm ci && npm run build ``` **Go** Laravel Cloud pre-fills your Go build command for the detected entrypoint. An application with its `main` package at the repository root and no detected cgo requirements uses: ```shell theme={null} CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o app . ``` Cloud adjusts the package path for entrypoints such as `cmd/server` and sets `CGO_ENABLED=1` when it detects cgo requirements. The default start command, `./app`, runs the resulting binary. If you change the output path or binary name, update the start command to match. **Python** Laravel Cloud installs Python dependencies automatically, using `uv.lock`, `poetry.lock`, `Pipfile.lock`, `requirements.txt`, or `pyproject.toml`, in that order. Lockfile tools export dependencies for pip to install into the shared Python user directory. Cloud pre-fills additional build steps when needed. Django projects with a `STATIC_ROOT` setting or WhiteNoise dependency receive `python manage.py collectstatic --noinput`. Projects missing a compatible application server receive `pip install --user gunicorn` for WSGI or `pip install --user uvicorn` for ASGI. You may edit or remove these commands to suit your project. See the [Python deploy guide](/docs/deploy-guides/python) for server and static-file configuration. **Ruby and Rails** Laravel Cloud installs gems automatically using `Gemfile.lock`. Rails applications with detected assets receive an asset compilation command, preceded by JavaScript dependency installation when needed: ```shell theme={null} SECRET_KEY_BASE_DUMMY=1 bundle exec rails assets:precompile ``` Review your asset pipeline and any additional build steps in the [Ruby and Rails deploy guide](/docs/deploy-guides/ruby#build-and-serve-assets). Generic Ruby and API-only Rails applications do not receive this default asset build. **Rust** Laravel Cloud downloads your crates automatically and pre-fills the following build command: ```shell theme={null} cargo build --release ``` Cloud copies the executables from your release output to `/var/www/bin`, which is on your `PATH`, and detects which binary the default start command should run. See the [Rust deploy guide](/docs/deploy-guides/rust#compile-during-the-build) to learn how Cloud chooses between several binaries. > [!WARNING] > > Build commands time out if they do not complete within 15 minutes. #### Dynamic environment variables For Laravel and Symfony applications, Laravel Cloud writes your environment's variables to a `.env` file in the build context. You may append a derived value for your application to read: ```shell theme={null} # Adding a dynamic environment variable echo "MY_DYNAMIC_VAR=value" >> .env ``` > [!NOTE] > > JavaScript, Go, Python, Ruby, and Rust applications receive variables through the process environment during builds and at runtime. Appending to a `.env` file does not configure their runtime variables. Add persistent values under your environment's [environment variables](#environment-variables) instead. ### Deploy commands Laravel Cloud runs your environment's "Deploy Commands" on your infrastructure just before a new deployment goes "live". Typically, you use these commands to migrate your environment's database. Unlike build commands, deploy commands do not persist their filesystem changes to your application. ![](https://mintcdn.com/cloud/MkfTsQSKGENWqY-2/images/deploy-commands.webp?fit=max\&auto=format\&n=MkfTsQSKGENWqY-2\&q=85\&s=42a3479f7de4f82f8a0b72ce9e8e3baf) > [!WARNING] > > Deploy commands time out if they do not complete within 15 minutes. For Rails applications using a database, run `bin/rails db:prepare` as a deploy command. If you have kept the default deploy command, attaching a database uncomments it. See [Rails database preparation](/docs/deploy-guides/ruby#prepare-the-databases). #### Unnecessary build and deploy commands > [!NOTE] > > This section applies to Laravel applications. Laravel Cloud either handles the following commands automatically, or they should not run during deployment: * `php artisan queue:restart`: Laravel Cloud restarts queue workers automatically after each deployment. * `php artisan horizon:terminate`: Laravel Cloud manages Horizon processes automatically during deployments. * `php artisan optimize:clear`: This command clears the cache and can cause unexpected behavior, especially with the queue. * `php artisan storage:link`: The symbolic link won't persist, because Laravel Cloud does not save changes that deploy commands make. Use [Laravel Object Storage](/docs/resources/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 The environment variables section of your environment's settings lets you customize the variables available to your environment. ![](https://mintcdn.com/cloud/83RcCEaWR6PzmMFO/images/custom-environment-variables.png?fit=max\&auto=format\&n=83RcCEaWR6PzmMFO\&q=85\&s=62161346aded8584e85fb043f9cbfd1f) In addition to your custom environment variables, Laravel Cloud automatically injects a variety of environment variables for you. These include any credentials needed to connect to Laravel Cloud resources like databases, key-value storage, or object storage. ![](https://mintcdn.com/cloud/MkfTsQSKGENWqY-2/images/injected-environment-variables.png?fit=max\&auto=format\&n=MkfTsQSKGENWqY-2\&q=85\&s=259838afa702d1fa3ffd33c1e04e51f7) For sensitive values that should be shared across multiple environments, use [Secrets Manager](/docs/secrets) to create encrypted organization-level secrets and link them to the environments that need them. > [!NOTE] > > Custom environment variables take priority and override any automatically injected environment variables. After you change an environment's variables, redeploy the environment for the changes to take effect. #### How variables reach your application Laravel Cloud delivers your environment's variables differently depending on the runtime: **Laravel, Symfony** Laravel Cloud writes your variables to a `.env` file in your application's root directory before your application starts, so the framework reads them the same way it does locally. **JavaScript** Laravel Cloud sets your variables on the application process, the way `export` does in a shell. Read them from `process.env`. **Go** Laravel Cloud sets your variables on the application process, the way `export` does in a shell. Read them with `os.Getenv`. No `.env` file is written at runtime, so your application does not need a loader such as `godotenv`. **Python** Laravel Cloud sets your variables on the application process, the way `export` does in a shell. Read them from `os.environ`, or, in a Django application, through your settings module as usual. No `.env` file is written at runtime, so your application does not need a loader such as `python-dotenv`. **Ruby and Rails** Laravel Cloud sets variables on your application process. Read them from `ENV`. Rails reads `DATABASE_URL` automatically, while custom application settings require you to read the corresponding variables in your configuration. **Rust** Laravel Cloud sets your variables on the application process, the way `export` does in a shell. Read them with `std::env::var`. No `.env` file is written at runtime, so your application does not need a loader such as `dotenvy`. Laravel Cloud also makes your environment's variables available during builds. Laravel and Symfony builds include a `.env` file for the framework to read. JavaScript, Go, Python, Ruby, and Rust build commands receive exported process variables. ### HTTP basic authentication HTTP basic authentication lets you protect an environment with a username and password before traffic reaches your application. Basic authentication is useful for staging environments, private demos, preview environments, or sleeping environments that should not wake up because of unauthorized requests or automated bot traffic. You may enable HTTP basic authentication in the Security section of your environment's General Settings page. Once you enable it, users can access the environment with the username `admin` and the password you set. Passwords must be between 5 and 32 characters and cannot contain the `:` character. ![](https://mintcdn.com/cloud/MkfTsQSKGENWqY-2/images/http-basic-auth.png?fit=max\&auto=format\&n=MkfTsQSKGENWqY-2\&q=85\&s=b5fff1f73b4da57b30eec9112c33573a) HTTP basic authentication is available on the [Growth plan](/docs/pricing) or higher. After you enable it, disable it, or change the password, redeploy the environment for the changes to take effect. ### Runtime #### PHP runtime You may select an environment's PHP version on the environment's General Settings page. After you change the PHP version, redeploy the environment for the change to take effect. See [Runtimes](/docs/runtimes#php) for the supported PHP versions. ![](https://mintcdn.com/cloud/MkfTsQSKGENWqY-2/images/php-version.png?fit=max\&auto=format\&n=MkfTsQSKGENWqY-2\&q=85\&s=b666d97f5dbd253b90a8954de0c04ace) #### Node.js, Bun, and Deno runtimes Next.js, Nuxt, TanStack Start, Express, and Hono applications run on the Node.js, Bun, or Deno runtime. Laravel Cloud detects the runtime automatically from the configuration files in your repository. See [Runtimes](/docs/runtimes#node-js-bun-and-deno) for detection rules and supported versions. You may select the Node.js, Bun, or Deno version on the environment's General Settings page. After you change it, redeploy the environment for the change to take effect. ![](https://mintcdn.com/cloud/MkfTsQSKGENWqY-2/images/node-version.png?fit=max\&auto=format\&n=MkfTsQSKGENWqY-2\&q=85\&s=2421aa964bdb265b8286d1b8286b9260) #### Go and Python runtimes Laravel Cloud detects Go and Python applications automatically from your repository: a `go.mod` file for Go, or a `pyproject.toml`, `requirements.txt`, `Pipfile`, or `setup.py` file for Python. Rather than using a dashboard setting, Laravel Cloud reads the language version straight from your repository. For Go, it reads the `go` directive in `go.mod`. For Python, it reads a `.python-version` file or the `requires-python` constraint in `pyproject.toml`. See [Runtimes](/docs/runtimes) for supported versions and what happens when a detected version isn't one Laravel Cloud publishes. #### Ruby runtime Laravel Cloud reads Ruby version declarations from your deployment's commit. When the repository does not declare a version, you may select one in **General Settings**. See [Ruby versions](/docs/runtimes#ruby) for the supported release lines and declaration order. #### Rust runtime Laravel Cloud detects Rust applications automatically from a `Cargo.toml` file at the root of your repository. Rather than using a dashboard setting, Laravel Cloud builds with a recent stable Rust release, or with the toolchain pinned by your `rust-toolchain.toml` file. See [Rust versions](/docs/runtimes#rust) for details. ### PHP extensions > [!NOTE] > > PHP extensions are only available for PHP runtime environments (Laravel and Symfony). 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, grpc, 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 loaded extensions by running `php -m` with Laravel Cloud's "Command" feature in your environment dashboard. ### PHP memory limit > [!NOTE] > > This section applies to PHP runtime environments (Laravel and Symfony). Laravel Cloud allocates PHP memory dynamically based on a percentage of your instance's total memory. If your application needs a specific amount, you can override the default 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 theme={null} [!TIP] > > If your domain verification is taking longer than expected, check out our docs on [verifying domains](/docs/knowledge-base/domain-verification). ## 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, Laravel Cloud shuts down all App and Worker clusters in the environment. All web traffic, background processes, and scheduled tasks stop. You are not charged for the environment's compute, but you are still charged for any attached resources. You can restart the environment from the same dropdown menu. Restarting an environment runs a full deployment. ![](https://mintcdn.com/cloud/MkfTsQSKGENWqY-2/images/stop-environment.png?fit=max\&auto=format\&n=MkfTsQSKGENWqY-2\&q=85\&s=c05c33016eb9a8701b5ac15277b39c2c) ## Replicate Environments in the same application often have similar or identical resources and settings. So when you create a new environment, it is often more convenient to clone an existing one and make changes than to start 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, Laravel Cloud duplicates all General, Environment, and Deployment settings. You can optionally edit the default replication settings for compute and resources. The default replication behavior is: * Compute: duplicate all clusters at a smaller size, with Scale-to-Zero enabled * Database: create a new database cluster that scales to zero, or a new database within the same cluster if your database does not support scale-to-zero replication * Cache: create a new cache that scales to zero, or a new cache at the smallest available size if your cache does not support scale to zero * Object storage: create a new bucket * WebSockets: create a new WebSocket server If you choose to share the cache instead, Cloud adds a `REDIS_PREFIX` environment variable set to `application:environment:` so each environment's keys stay separate. If the environment runs Laravel Horizon, Cloud also sets `HORIZON_PREFIX`. ![](https://mintcdn.com/cloud/MkfTsQSKGENWqY-2/images/replicate-modal.png?fit=max\&auto=format\&n=MkfTsQSKGENWqY-2\&q=85\&s=2af102de2d1c19b127e337fde75cec00) > [!WARNING] > > Review and edit the "Replication options" as needed **before** deploying your new environment. The defaults balance cost and performance, but they may not be right for your application. Take extra care when you replicate a production environment. Reusing its resources can hurt performance or interfere with queued jobs, sessions, or other application data. To generate an isolated environment automatically for every pull request, use [preview environments](/docs/preview-environments) instead. ## Commands Laravel Cloud lets you run arbitrary shell commands directly in your environment. Navigate to your environment's **Commands** tab to run one-time commands for any supported framework or runtime. For example, `php artisan cache:clear` in a Laravel application, `php bin/console cache:clear` in a Symfony application, `node script.js` in a Node.js application, `./app migrate` in a Go application, `migrate` in a Rust application, or `python manage.py shell` in a Django application. > [!WARNING] > > Commands must be non-interactive and may not run for more than 30 minutes. Laravel Cloud runs commands on any available instance in your environment. ## Filesystem Environment filesystems are **ephemeral**, meaning files may not persist across requests or jobs. New deployments and redeployments reset the filesystem. In addition, each replica of your compute cluster has its own filesystem. Treat the filesystem as temporary, unshared disk space that stays consistent only during a single request or job. The total disk space available on each replica is proportional to the cluster's RAM. Every 1GB of RAM gives 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. For persistent cache and session storage, PHP applications should use the `redis` or `database` drivers with a [cache](./resources/caches) or [database](./resources/databases/laravel-mysql) resource. JavaScript applications should use their framework's equivalent persistent session and cache adapter backed by one of these resources. Go, Python, and Rust applications should connect directly to a cache or database resource using the injected `REDIS_URL` or `DATABASE_URL` connection string. For persistent file storage, use [Laravel Cloud Object Storage](./resources/object-storage). ## Nightwatch integration > [!NOTE] > > Nightwatch integration is currently available for Laravel applications only. Laravel Cloud environments have built-in support for [Laravel Nightwatch](https://nightwatch.laravel.com) monitoring. Nightwatch shows your environment's performance, exceptions, logs, and overall health. ![](https://mintcdn.com/cloud/MkfTsQSKGENWqY-2/images/environment-nightwatch.png?fit=max\&auto=format\&n=MkfTsQSKGENWqY-2\&q=85\&s=decdfff34b947ee7ced9ae7dffd5a060) **1. Install Nightwatch package** Install the Laravel Nightwatch package in your application locally using [Composer](https://packagist.org/packages/laravel/nightwatch): ```bash theme={null} composer require laravel/nightwatch ``` > [!NOTE] > > 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. > [!NOTE] > > When you enable Nightwatch, Laravel Cloud runs the agent on all App and Worker clusters in the environment. You can [set up Nightwatch manually](/docs/knowledge-base/nightwatch-on-cloud) if you want the agent to run on specific instances. When you enable Nightwatch, Laravel Cloud automatically injects 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. > [!WARNING] > > If you have previously [configured Nightwatch manually](/docs/knowledge-base/nightwatch-on-cloud) with a background process, remove that process from every cluster before you enable the built-in integration. Otherwise, your environment may run into issues.