diff --git a/skills/deploying-laravel-cloud/SKILL.md b/skills/deploying-to-cloud/SKILL.md similarity index 50% rename from skills/deploying-laravel-cloud/SKILL.md rename to skills/deploying-to-cloud/SKILL.md index 50e017f3..4c75f3ad 100644 --- a/skills/deploying-laravel-cloud/SKILL.md +++ b/skills/deploying-to-cloud/SKILL.md @@ -1,19 +1,71 @@ --- -name: deploying-laravel-cloud -description: "Deploys and manages Laravel applications on Laravel Cloud using the `cloud` CLI. Use when the user wants to deploy an app, ship to cloud, create/manage environments, databases, caches, domains, instances, background processes, check billing/usage/spend, or any Laravel Cloud infrastructure. Triggers on deploy, ship, cloud management, environment setup, database provisioning, billing/usage queries, and similar cloud operations." +name: deploying-to-cloud +description: "Deploys and manages Laravel applications on Laravel Cloud using the `cloud` CLI. Use when the user wants to deploy an app, ship to cloud, create/manage applications, environments, databases, caches, object storage, queues, domains, instances, background processes, secrets, compute, scheduled tasks, check billing/usage/spend, or any Laravel Cloud infrastructure. Triggers on deploy, ship, cloud management, environment setup, database provisioning, billing/usage queries, the `cloud` CLI, and troubleshooting Laravel Cloud deployments." +license: MIT +metadata: + author: laravel --- -# Deploying with Laravel Cloud CLI +# Deploying with Laravel Cloud -## Setup +Use the [Laravel Cloud documentation](https://cloud.laravel.com/docs/llms.txt) for detailed and current feature behavior. Use the Cloud CLI for Cloud operations rather than guessing dashboard or API workflows. Install it in the project and invoke it as `./vendor/bin/cloud` by default; use a globally installed `cloud` command only as a fallback. Commands below are written as `cloud` for brevity — run them as `./vendor/bin/cloud` unless falling back to the global installation. -```sh -composer global require laravel/cloud-cli -cloud auth -n +## Application Setup + +- Laravel Cloud deploys from GitHub, GitLab, or Bitbucket. A new Laravel application requires PHP 8.2 or greater, Laravel 9 or greater, a connected Git provider, and a deployment region. +- Cloud creates environments for applications. Use separate production, staging, and preview environments; each environment has its own compute, resources, and deployment settings. +- Keep application compute and attached resources in the same region where possible. +- Cloud builds a Docker image using the selected PHP version, runs the configured build and deploy commands, and switches traffic to a successful deployment with zero downtime. Push-to-deploy is enabled by default, and manual deployments and deploy hooks are also available. + +## Build And Deploy + +- A typical Laravel build command is `composer install --no-dev && npm run build`. +- Run optimization and cache-building commands during the build, not the deploy. A typical deploy command is `php artisan migrate --force`. +- Build and deploy commands have a 15-minute timeout. Deploy commands run immediately before the release becomes live, and filesystem changes made by deploy commands are not persisted. +- Do not add `php artisan queue:restart`, `php artisan horizon:terminate`, `php artisan optimize:clear`, or `php artisan storage:link` to deploy commands. Cloud handles worker restarts and process management; deploy filesystem changes are not persistent. +- After changing environment settings, attached resources, or linked secrets, redeploy the environment for the changes to take effect. + +## Configuration And Resources + +- Attached databases, caches, and object storage inject their connection variables automatically. Custom environment variables take precedence over injected values. +- Use Secrets Manager for encrypted organization-level values shared across environments. Secret values cannot be read after creation; redeploy affected environments after creating, updating, linking, unlinking, or deleting a secret. +- Environment filesystems are ephemeral and are not shared between replicas. Use a database or Laravel Valkey for persistent cache and sessions, and Laravel Cloud Object Storage for persistent files. Do not rely on local files surviving a deployment. + +### Object Storage And File Visibility + +- Laravel Cloud Object Storage is backed by Cloudflare R2. R2 applies visibility at the bucket level; a bucket cannot contain a mix of private and public objects. +- For private files, always use `Storage::disk()` with no arguments, such as `Storage::disk()->put(...)`, so Laravel uses the environment's default disk. Do not pass a disk name for private/default storage. Attach a private Cloud bucket as the environment's default disk. +- For public files, use the named public disk: `Storage::disk('public')->put(...)`. Attach a second Cloud bucket configured as public and give it the `public` disk name. +- Applications that use both private and public files therefore need two Cloud Object Storage buckets attached to the environment: a private default bucket and a public bucket named `public`. +- Do not set per-file or Flysystem `visibility: 'public'` configuration for Cloud Object Storage. R2 does not support per-object ACL headers and rejects those requests; select the bucket visibility when creating the bucket. +- Private buckets are not internet-accessible, but Laravel can generate temporary public URLs with `Storage::temporaryUrl(...)`. Public buckets expose all objects through their Cloud-provided public URL. +- Install the S3 Flysystem adapter before using Cloud Object Storage: `composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependencies`. + +## Queues And Scheduling + +- Managed queues are the recommended queue option. They provision dedicated workers and autoscale based on queued work. +- Managed queues require a supported recent Laravel version and `aws/aws-sdk-php`; check the current Cloud documentation before changing dependencies. +- Enable the scheduler on an App or Worker cluster to run `php artisan schedule:run` every minute. When an environment has multiple replicas, use Laravel's `onOneServer` for tasks that must run once. +- Only Flex compute sizes can scale to zero. Scale-to-zero environments wake for Laravel scheduled tasks and queued jobs, but long-running jobs may be interrupted when the sleep timeout is reached. Use managed queues for workloads that must not be interrupted. + +## Domains And Storage + +- Each environment receives a `laravel.cloud` domain after its first successful deployment. Cloud automatically verifies custom domains and provisions SSL after the required DNS records are configured. +- Do not use the ephemeral filesystem for persistent uploads, generated files, cache, or session data. Use the appropriate Cloud resource instead. + +## Cloud CLI + +### Setup + +```shell +composer require --dev laravel/cloud-cli +./vendor/bin/cloud auth -n ``` +If a project-local installation is not available, install the CLI globally with `composer global require laravel/cloud-cli` and invoke it as `cloud`. + `cloud auth` opens a browser. Where that isn't possible, set `LARAVEL_CLOUD_TOKEN` in the environment — it overrides any saved token and writes nothing to disk. To save a token instead: `cloud auth:token --add --token= -n`, or pipe it: `echo "$TOKEN" | cloud auth:token --add -n`. -## Commands +### Commands Commands follow a CRUD pattern: `resource:list`, `resource:get`, `resource:create`, `resource:update`, `resource:delete`. @@ -23,7 +75,7 @@ Some resources have additional commands (e.g., `domain:verify`, `database:open`, Never hardcode command signatures. Always run `cloud -h` to discover options at runtime. -## CLI Flags +### CLI Flags Always add `-n` to every command — prevents the CLI from hanging. Never use `-q` or `--silent` — they suppress all output. @@ -36,14 +88,14 @@ Flag combos per operation: - Environment variables → `-n --force` - Deploy/ship → `-n` with all options passed explicitly (no `--json`) -## Deployment Workflow +### Deployment Workflow Determine the task and follow the matching path: -First deploy? → `cloud ship -n` (discover options via `cloud ship -h`) +First deploy? → inspect `cloud ship -h`, then run `cloud ship -n` with all required values Existing app? → -```sh +```shell cloud deploy {app_name} {environment} -n --open cloud deploy:monitor -n ``` @@ -58,21 +110,23 @@ Monorepo (app in a subdirectory)? → add `--root-directory=` to `cloud Custom domain? → `cloud domain:create --json -n` then `cloud domain:verify -n` +Repository defaults? → `cloud repo:config {application} -n` sets repository-local application and organization defaults. Pass `--organization=` when the user has multiple organizations. + For multi-step operations, see [reference/checklists.md](reference/checklists.md). Not sure what the user needs? → ask them before running anything. -## When a Command Fails +### When a Command Fails 1. Read the error output 2. Check resource status with `:list --json -n` or `:get --json -n` 3. Auth error? → `cloud auth -n` 4. Fix the issue, re-run the command -5. If the same error repeats after one fix, stop and ask the user +5. If the same error repeats after one fix, stop and ask the user rather than repeating the same operation -Always run `cloud deploy:monitor -n` after every deploy. If it fails, show the user what went wrong before attempting a fix. +Always run `cloud deploy:monitor -n` after every deploy. If it fails, inspect the deployment status and logs and show the user what went wrong before attempting a fix. -## Subagent Delegation +### Subagent Delegation Delegate high-output operations to subagents (using the Task tool) to keep the main context window small. Only the summary comes back — verbose output stays in the subagent's context. @@ -80,6 +134,8 @@ Delegate these to a subagent: - `cloud deploy:monitor -n` — deployment logs can be very long - `cloud deployment:get --json -n` — full deployment details - `cloud :list --json -n` — listing many resources produces large JSON +- `cloud command:run` — when output may be long +- `cloud usage --detailed --json -n` — the payload includes every database, cache, bucket, websocket, and application - Fetching docs from https://cloud.laravel.com/docs/llms.txt via `WebFetch` Keep in the main context: @@ -87,12 +143,12 @@ Keep in the main context: - `cloud deploy -n` — you need the deployment ID immediately - Any command where you need the result for the next step right away -## Rules +### Rules Follow exact steps: - Flag selection — always use the documented combos above - Deploy sequence — deploy then monitor, never skip monitoring -- Destructive commands — always confirm with user first, show the command and wait for approval +- Destructive commands — always confirm with the user first, show the command and wait for approval. This includes deleting applications, environments, databases, caches, buckets, domains, or secrets. - Error loop — diagnose, fix once, ask user if it fails again Use your judgment: @@ -101,11 +157,11 @@ Use your judgment: - Order of provisioning — no strict sequence required - How to present output — summarize, show raw, or extract fields based on context -## Secrets +### Secrets Encrypted values shared across the organization and attached to environments. The CLI encrypts the value locally, so plaintext never reaches the API. -```sh +```shell cloud secret:list --json -n echo "$VALUE" | cloud secret:create --name=STRIPE_KEY --json -n cloud environment-secret:attach {environment} {secretId} -n @@ -120,13 +176,15 @@ There is no `secret:get`, and no way to detach a secret from a single environmen Secrets need the `sodium` PHP extension. No other command does. -## Remote Access +Redeploy affected environments after creating, updating, attaching, or deleting a secret. -### Tinker (>= v0.2.0) +### Remote Access + +#### Tinker (>= v0.2.0) Run PHP code directly in a Cloud environment: -```sh +```shell cloud tinker {environment} --code='Your PHP code here' --timeout=60 -n ``` @@ -137,11 +195,11 @@ The code must explicitly output results using `echo`, `dump`, or similar — exp Always pass `--code` and `-n` to avoid interactive prompts. -### Remote Commands +#### Remote Commands Run shell commands on a Cloud environment: -```sh +```shell cloud command:run {environment} --cmd='your command here' -n ``` @@ -154,13 +212,11 @@ Review past commands: - `cloud command:list {environment} --json -n` — list command history - `cloud command:get {commandId} --json -n` — get details and output of a specific command -Delegate `command:run` to a subagent when output may be long. - -## Billing & Usage +### Billing & Usage View billing and usage for the current organization: -```sh +```shell cloud usage --json -n ``` @@ -177,9 +233,7 @@ Common queries: All amounts are in cents. Keys are camelCase at every level (e.g. `currentSpendCents`, `bandwidth.allowanceBytes`, `databases[].totalCents`, `applications[].totalCostCents`). -Delegate `--detailed --json` to a subagent — the payload includes every database, cache, bucket, websocket, and application and can get large. - -## Config +### Config 1. Environment: `LARAVEL_CLOUD_TOKEN` — an API token, taking precedence over any saved one (empty counts as unset) 2. Global: `~/.config/cloud/config.json` — auth tokens and preferences @@ -203,3 +257,10 @@ When the user asks how something works or needs an explanation of a Laravel Clou - Fetch https://cloud.laravel.com/docs/llms.txt for official documentation - Run `cloud -h` for any command's options - Run `cloud -h` to discover commands + +## Verification + +1. Confirm the target application and environment before changing or deploying anything. +2. Check staged environment changes and required resources before deployment. +3. Monitor every deployment to completion with `cloud deploy:monitor -n`. +4. For production changes, verify the application URL, logs, queues, scheduled tasks, and relevant resource health. diff --git a/skills/deploying-laravel-cloud/reference/checklists.md b/skills/deploying-to-cloud/reference/checklists.md similarity index 100% rename from skills/deploying-laravel-cloud/reference/checklists.md rename to skills/deploying-to-cloud/reference/checklists.md