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 automat