/craft-cloud

name: craft-cloud
description: "Craft Cloud — Pixel & Tonic's serverless hosting platform for Craft CMS. Covers craft-cloud.yaml configuration, the Build → Migrate → Release deploy pipeline, the craftcms/cloud extension package, edge image transforms via Cloudflare, edge static caching with cache.rules + ESI, Cloud-managed S3 filesystem, MySQL 8 / Postgres 15 databases (no MariaDB, no tablePrefix), Console-based command runner and scheduled cron (once-per-hour minimum), auto-handled queue jobs, custom domains and SSL, preview environments per branch, Cloud limitations (ephemeral filesystem, no SSH, no .htaccess, no built-in mail), plugin development requirements for Cloud compatibility, and self-hosted → Cloud migration."
when_to_use: "Triggers on: craft-cloud.yaml, craftcms/cloud package, cloud.esi(), php craft cloud/up, php craft cloud/setup, App::isEphemeral(), CRAFT_EPHEMERAL, edge.craft.cloud, preview.craft.cloud, CRAFT_CLOUD_PROJECT_ID, CRAFT_CLOUD_ENVIRONMENT_ID, CRAFT_CLOUD_CDN_BASE_URL, Build → Migrate → Release, Cloud filesystem, Cloud-compatible plugin, Cloudflare Images at edge, AssetsFs, static-caching rules, ESI islands, deploy to Craft Cloud, migrate to Craft Cloud, self-hosted to Cloud, Craft Cloud quotas, Craft Cloud regions, request signing (RFC 9421), CRAFT_CLOUD_SIGNING_KEY, headless 429/503, cloud.artifactUrl(), @artifactBaseUrl. Do NOT trigger for Servd (servd), fortrabbit (craft-fortrabbit) or generic Craft deployment on Forge/bare metal (craftcms/deployment.md). Do NOT trigger for general DDEV local dev unrelated to Cloud parity."

Craft Cloud — Serverless Hosting for Craft CMS

Reference for Craft Cloud, Pixel & Tonic's serverless hosting platform for Craft CMS. Covers the `craft-cloud.yaml` config file, the Build → Migrate → Release deploy pipeline, the `craftcms/cloud` extension, edge image transforms and static caching, the Cloud filesystem, plugin Cloud-compatibility requirements, and self-hosted → Cloud migration.

This skill is scoped to **Craft Cloud specifically** — what's different on Cloud vs running Craft yourself on Forge, Servd, fortrabbit, or bare metal. For **Servd**, see the `servd` skill; for **fortrabbit**, the `craft-fortrabbit` skill. For generic Craft deployment (build artifacts, project config sync, atomic deploys on traditional hosts), see the `craftcms` skill's `deployment.md`.

Companion Skills — Load When Needed

• **`craftcms`** — When the Cloud topic intersects plugin or module PHP work (e.g. `App::isEphemeral()` guards in services, asset-bundle constraints, queue job design for the 15-minute cap).
• **`craft-site`** — When Cloud intersects front-end templating (ESI islands inside cached pages, edge image transform usage, `{% expires %}` opt-outs for static caching).
• **`ddev`** — For the local-dev parity recipe (matching PHP/DB versions, simulating the ephemeral filesystem locally).
• **`craft-php-guidelines`** — When editing plugin PHP to add Cloud-compatibility checks.

Documentation

Authoritative sources used to write this skill:

• Craft Cloud docs landing: https://craftcms.com/docs/cloud/
• Configuration reference: https://craftcms.com/docs/cloud/config
• Deployment pipeline: https://craftcms.com/docs/cloud/deployment
• Builds: https://craftcms.com/docs/cloud/builds
• Compatibility & limitations: https://craftcms.com/docs/cloud/compatibility
• Assets & transforms: https://craftcms.com/docs/cloud/assets
• Static caching: https://craftcms.com/docs/cloud/static-caching
• Headless apps: https://craftcms.com/docs/cloud/headless-apps
• Request signing: https://craftcms.com/docs/cloud/request-signing
• Plugin development: https://craftcms.com/docs/cloud/plugin-development
• Cloud extension source: https://github.com/craftcms/cloud

Per-claim URLs appear in each reference file. Last verified against the docs and `craftcms/cloud-extension-yii2@main` on 2026-05-28; headless/request-signing, artifact URLs, environments, quotas, and backups content verified against `craftcms/docs@main` on 2026-09-02.

What's Different on Cloud vs Self-Hosted

A quick orientation table. Each row is a place self-hosted habits will mislead you.

| Concern | Self-hosted | Cloud | |---|---|---| | Config file | `.env`, `config/general.php`, `config/db.php`, your web-server config | **`craft-cloud.yaml`** at repo root for platform settings; runtime env vars set in Craft Console UI (not `.env`) | | Deploy | Whatever you've wired (Forge, GitHub Actions, rsync) | Git push → automatic **Build → Migrate → Release** (15-min build cap) | | Filesystem | Local disk or your own S3/R2 config | **Ephemeral** Lambda filesystem; use `App::isEphemeral()` to gate writes; user assets must use the Cloud-bundled S3-backed filesystem type | | Database | Whatever you've installed | **MySQL 8.0 or Postgres 15 only** — no MariaDB, no `tablePrefix`, no `db.php` touching, no `CRAFT_DB_*` overrides | | App / component config | Free to override components in `config/app.php` | The extension **owns several components** (`response`, `session`, `cache`, `mutex`, `queue`, `assetManager`) + the DB connection — overriding them in `app.*.php` breaks the wiring, and it's **not reproducible locally** (the extension only runs on Cloud) | | Headless / API consumers | Your GraphQL endpoint, your rate limits | Bot detection deprioritizes automated traffic — SSG builds/ISR get **429/503** unless requests are **signed** (RFC 9421, `$CRAFT_CLOUD_SIGNING_KEY`) and retried with backoff | | Queue jobs | You run a worker (systemd, supervisor, cron) | **Auto-processed** by Cloud — don't schedule the runner; cap each job at 15 minutes | | Cron | `crontab -e`, any frequency | Craft Console UI only; **once per hour minimum** | | Image transforms | ImageOptimize / Imager-X / native | **Edge transforms** via Cloudflare Images — no template changes needed, but ImageOptimize is incompatible | | Page caching | Blitz or similar | **Edge static caching** via `cache.rules` in `craft-cloud.yaml`; tag-ba