Cloud Services and Compatibility

Craft Cloud was designed to be compatible with a wide variety of projects—but for security and performance, we did have to make some decisions about what versions of Craft (and the software it depends on) we would officially support. This article covers those limitations, as well as some common features and configurations that may require special attention when moving a project to Cloud.

Craft #

Your project must be updated to at least 4.6.0 to be able to install the Cloud extension, which provides essential functionality like automatic configuration and the Cloud filesystem. Version 1.16.5 of the extension is required to deploy your project.

PHP #

PHP 8.1 and newer are supported on Cloud. Pick a major and minor version via your project’s craft-cloud.yaml config file.

Node #

Versions 16 and newer of Node are supported in our builder via the node-version key in your Cloud config file. We plan to add all LTS releases, moving forward.

We recommend declaring only a major version (i.e. 20) to receive security and stability updates, but minor releases (i.e. 18.6) are supported.

Database Engines #

See our article on working with databases for up-to-date information on supported MySQL and Postgres versions. MariaDB is not supported on Craft Cloud, and we no longer recommended it for Craft 5.

Mailers #

Craft Cloud does not have a built-in mail service. You must configure your own adapter in Craft, as the default sendmail adapter will not work.

Filesystems #

Local filesystems will not work on Craft Cloud, and must be converted to the Cloud filesystem provided by the extension. Remote filesystems provided by plugins that have not received updates from their maintainers to be compatible with Cloud may not be fully functional.

Configuration #

Some Craft settings behave differently when running on Cloud.

General Config #

The resourceBasePath and resourceBaseUrl have no effect when running on Cloud. Asset bundles and anything that ends up in your web root are published to our CDN.

We automatically enable Craft’s asyncCsrfInputs setting to support static caching.

Application Config #

Changes made via app.php may not be honored when deployed to Cloud. Specifically, the Cloud extension overrides these system components to guarantee they work in a Cloud-compatible way:

• assetManager
• cache
• mutex
• queue
• session

In addition, we automatically set properties on the db component via environment overrides to ensure Craft can connect to the current environment’s database. You may have connectivity issues if you use a db.php file, or add any other CRAFT_DB_* variables to an environment.

Project Structure #

If your project has a different directory structure than our official starter project, you may need to set some additional keys in your Cloud config file. This includes the webroot and other *-path settings.

Workflow #

Cloud was built with teams in mind, so it reflects our recommendations for maintaining a healthy development and deployment workflow. This means that…

• …we require your code to be pushed to a Git provider;
• …direct access to the server/function filesystem is not allowed;
• …Project Config and changes that would alter composer.json (like running system updates) are discouraged;

We believe these limitations will not affect most developers, but understand that they may involve some adjustment to processes.

While devMode and allowAdminChanges are possible to enable in Cloud environments, we strongly advise against it. Making changes to your project’s schema on Cloud can result in your database and Project Config files diverging, as well as data loss.

Whenever possible, we recommend adopting one-way flows for code and content: code changes are made and tested locally, pushed to Git, then deployed; content changes are made in a live environment, backed up, and imported into your local environment.

Special Considerations #

Headers #

Our infrastructure flattens duplicate HTTP response headers into a single, comma-separated one. If you are using the {% header … %} tag in your templates or manipulating the response object’s HeaderCollection directly, you may see slightly different output from a Cloud response than you would in other environments. Rest assured, they are functionally equivalent in the HTTP spec!