craft-cloud

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, or bare metal. For Servd, see the servd 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
• Plugin development: https://craftcms.com/docs/cloud/plugin-development
• Cloud extension source: https://github.com/craftcms/cloud-extension-yii2

Per-claim URLs appear in each reference file. Last verified against the docs and craftcms/cloud-extension-yii2@main on 2026-05-28.

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 | | 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-based auto-invalidation | | Dynamic islands in cached pages | Per-cache-driver workaround | First-class cloud.esi(...) Twig helper | | Logs | Files in storage/logs/ | Craft::info/warning/error() only — no file-tailing UI; Console command output is the de-facto surface | | Mail | sendmail or any adapter | No built-in mail — bring your own SMTP/Postmark/SES/Resend | | SSH | ssh user@server | None — Console command runner only (255-char cap, 15-min cap) | | Server rewrites | .htaccess / nginx config | redirects: and rewrites: keys in craft-cloud.yaml | | Custom domains | DNS provider + cert | DNS + ownership TXT + CNAME to edge.craft.cloud; auto SSL via Cloudflare | | Preview environments | Your CI | Per-branch only — no per-PR previews documented |

Common Pitfalls (Cross-Cutting)

• Writing to disk without an App::isEphemeral() guard. Lambda's filesystem is ephemeral and writes are lost between requests. Plugins, services, and migrations all need to check and use the Path service (Craft::$app->getPath()->getTempPath()/getStoragePath()/getCachePath()) for transient writes. See references/extension.md (App::isEphemeral) and references/plugin-development.md.
• **Configuring db.php or setting CRAFT_DB_* env vars.** Cloud auto-wires the database connection through the extension; manual config can break it. See references/database.md.
• Using tablePrefix. Unsupported on Cloud. Run php craft db/drop-table-prefix before migrating. See references/migration.md.
• Choosing MariaDB. Cloud only supports MySQL 8.0 and Postgres 15.
• Scheduling your own queue runner. Cloud auto-processes queue jobs — adding a scheduled command for the queue runner is redundant and may conflict.
• Trying to schedule cron more often than hourly. Cloud's UI enforces a one-hour minimum. Design recurring tasks around this floor or move the work into queue jobs triggered by other events.
• {{ csrfInput() }} in cacheable templates. Forces a cookie, busts edge static caching. Use the csrfInput() function instead, which renders an async input compatible with asyncCsrfInputs (force-enabled on Cloud).
• .htaccess rules or nginx config in the repo. Won't be honored — move to redirects: / rewrites: in craft-cloud.yaml. See references/config-file.md.
• Writing to log files. No persistent filesystem. Use Craft::info/warning/error() and the logger routes to Cloud's log target automatically. See references/extension.md.
• Assuming SSH access. There is none. The Console command runner is the only way to execute commands, with a 255-character argument cap and 15-minute timeout.
• Forked Git repos. Cloud can't deploy from forks — must be the upstream repository.
• Expecting per-PR preview environments. Cloud supports per-branch environments only; no automatic ephemeral environment per pull request.
• Default sendmail adapter. Will not deliver mail. Configure SMTP/Postmark/SES/Resend explicitly. See references/limitations.md (Mail).
• Using ImageOptimize on Cloud. Cloud handles transforms at the edge via Cloudflare Images — ImageOptimize duplicates the work and can conflict. See references/assets-and-transforms.md.

Reference Files

Read the relevant reference file(s) for your task. Multiple files often apply.

Task examples:

• "Set up a new Craft project on Cloud" → config-file.md + deploy-pipeline.md + extension.md
• "Configure craft-cloud.yaml for PHP and Node versions" → config-file.md
• "Add redirects in craft-cloud.yaml" → config-file.md (Redirects and Rewrites)
• "What happens during deploy?" → deploy-pipeline.md
• "Set build-time env vars" → deploy-pipeline.md (Build-time vs runtime variables)
• "What does php craft cloud/up do?" → extension.md (cloud/up internals)
• "Add an ESI island inside a cached page" → caching-and-edge.md
• "Edge static caching rules" → caching-and-edge.md
• "Migrate user assets from self-hosted to Cloud" → assets-and-transforms.md + migration.md
• "Make this plugin Cloud-compatible" → plugin-development.md
• "Why does my plugin's file write silently fail on Cloud?" → plugin-development.md (Ephemeral filesystem) + extension.md (App::isEphemeral)
• "Set up a custom domain" → domains.md
• "Schedule a recurring command" → commands-and-cron.md (hourly minimum)
• "Run a one-off command on Cloud" → commands-and-cron.md (Console command runner)
• "C