Craft Cloud Articles

Welcome to Craft Cloud, our new hosting platform tailor-made for Craft CMS!

Craft Cloud projects are always created via Craft Console. You can start projects with your personal account, or within an organization. We generally recommend organizations for Cloud projects, as they support delegated access and other features that underpin safe collaboration. Creating a Project Log in to your Craft Console account, then click Cloud in the main navigation. If this is your first project, you’ll see a welcome screen and a New project button; existing Cloud users will see a list of current projects. Use the menu in the upper-right corner to switch between your personal account and the organizations you are a member of. You must have a payment method on file (in the current account context) to start a Cloud trial. Within an organization, only owners and administrators can create projects. If you don’t have adequate permissions, get in touch with the person who created the organization. Project Ownership + Collaboration Projects owned by a personal account can only be managed via that account. You cannot transfer a project to an organization after it is created. If you suspect that a project will ever be supported by someone other than you, create an organization for it. Organizations are free, and provide a perfect place to consolidate a client or firm’s projects and licenses.

Craft Cloud looks for a craft-cloud.yaml file in the root of the connected repository. This file has a specific syntax (YAML) and schema that determines a few things about how your project is built, deployed, and served. If there are problems with your config file, the deployment will fail with an error describing the issue.

Craft Cloud allows you to define any number of custom redirect and rewrite rules via your craft-cloud.yml config file. Both features use the flexible URLPattern API to match request URLs. These rules are evaluated on our gateway, before we pass the request to your Craft application. Redirects Redirection rules live in your craft-cloud.yml file, under a redirects key: `yml php-version: '8.2' ... redirects: - pattern: hostname: 'legacy-domain.com' destination: 'https://new-domain.com/{request.uri}' status: 301 ` Each rule’s pattern can be a string or an object; either way, it is passed verbatim to the new URLPattern(input) constructor. In effect, you can match based on parts of a URL, without using complex regular expressions. A pattern (or each of its components) can be a simple string, or include wildcards and capture groups. The destination is a pseudo-template used to build a complete URL. It can be a static string or contain substitute information about the original request (request) or pattern (matches). Additionally, these variables are available to simplify constructing URLs to other Craft Cloud resources: cdnBaseUrl — The Craft Cloud CDN domain, plus the requested environment’s identifier. Example: https://cdn.craft.cloud/4eca7d1f-8976-45e9-89fb-6b2e864d9407/ assetBaseUrl — Same as above, but pointing to the assets/ subdirectory of the requested environment. Example: https://cdn.craft.cloud/4eca7d1f-8976-45e9-89fb-6b2e864d9407/assets/ artifactBaseUrl — The full URL to the current build’s artifacts directory. Example: https://cdn.craft.cloud/4eca7d1f-8976-45e9-89fb-6b2e864d9407/builds/current/artifacts/ The matches object is the return value of URLPattern.exec() for the requested URL. It contains all URL components with any captured groups from the supplied pattern. The request object contains these properties: url — A URL object wrapping the original request’s full URL. uri — Shorthand for everything after the origin in the original request, and similar to $_SERVER['REQUEST_URI'] in PHP. It is equivalent to {request.url.pathname}{request.url.search}{request.url.hash}. method — The request’s HTTP verb. headers — A map of request headers and values. (Headers with dashes can be used in destination substitutions like any other property, e.g: {request.headers.Content-Type}) HTTP Status Codes An optional status key in each rule determines what HTTP status code is sent with the redirection. If none is specified, we default to 302 Found for a “temporary” redirection. Use 301 Moved Permanently with caution! Some infrastructure and tools aggressively cache 301 responses, or completely replace records with the new URL, meaning it can be difficult or impossible to undo. Examples A common problem solved with HTTP servers (or PHP itself) is normalization of “www” or “non-www” URLs. `yml redirects: - pattern: hostname: 'www.mydomain.com' destination: 'https://mydomain.com/{request.uri}' ` The opposite is also possible: `yml redirects: - pattern: hostname: 'mydomain.com' destination: 'https://www.mydomain.com/{request.uri}' ` For these rules to work, you must have both domains pointed to the same Craft Cloud environment. Wildcards and/or regular expressions (including negative lookaheads) are required to create generic rules that match any domain. Enforcing (or trimming) trailing slashes is another common normalization—Craft even has a config setting (addTrailingSlashesToUrls) that handles it at the application level. An equivalent rule would look like this: `yml redirects: - pattern: pathname: '/:noSlashes+' destination: '/{matches.pathname.groups.noSlashes}/' status: 301 ` While this pattern appears to have only a single path segment, the + modifies the capture group, allowing it to repeat one or more times. Effectively this rule captures all path segments, regardless of depth—from /top-level to /a/deeply/nested/page. The destination template simply appends a slash to that template.

Every Craft Cloud project is protected by Cloudflare’s enterprise-grade global WAF or web application firewall. For most sites and apps, our default policies (in combination with an envolving set of custom rules) will be enough to thwart inorganic and malicious traffic—but occasionally, customers will need access to deeper customization. As part of launching a site on Cloud, you’ll connect a domain by adding a few DNS records with your provider. If you or your client are already users of Cloudflare’s proxy (colloquially, “orange cloud”), you may encounter validation errors unless you follow a specific “Orange-to-Orange” setup process.

On April 7, 2025, we received a report of a Craft CMS vulnerability that was based on a vulnerability in the Yii framework. Yii fixed that vulnerability in Yii 2.0.52. We confirmed the vulnerability as valid and released Craft CMS versions 3.9.15, 4.14.15, and 5.6.17 on April 10th with an application-level fix. We marked those releases as critical so affected sites would display a banner to control panel users, urging them to update. On April 17, 2025, we discovered evidence to suggest the vulnerability was being exploited in the wild, so we emailed all potentially affected license holders, encouraging them to update or install the Craft CMS Security Patches library as a stop-gap. Triage If you check your firewall logs or web server logs and find suspicious POST requests to the actions/assets/generate-transform Craft controller endpoint, specifically with the string __class in the body, then your site has at least been scanned for this vulnerability. This is not a confirmation that your site has been compromised; it has only been probed.

On December 19, 2024, we were made aware of reports that a Craft CMS vulnerability was being actively exploited. The vulnerability was patched on November 19, 2024 in Craft CMS versions 3.9.14, 4.13.2, and 5.5.2. We retroactively marked those releases as critical, after the disclosure and subsequent exploitation; affected sites will display a banner to control panel users, urging them to update. Triage If your web PHP configuration has register_argc_argv Off, no further action is required. You can view this setting in the Craft control panel by navigating to Utilities → PHP Info, and searching for register_argc_argv:

In addition to running one-off commands in a Craft Cloud environment, you can set up recurring commands using standard cron syntax. Each environment is allowed {globalset:productVitals:custom_cloudScheduledCommandsMax} scheduled commands.

Craft Cloud’s serverless architecture means that traditional access via SSH is not possible. However, the Craft CLI is still an essential part of many developers’ workflows! Each environment in your Cloud project has a Commands screen, from which you can run one-off Craft commands, or manage scheduled commands.

Craft allows you to customize the control panel and login screens by providing a Site Icon and Login Page Logo via Settings → General. However, these artifacts are not stored in Craft’s asset system—instead, they’re kept on-disk in your project’s “rebrand” directory. By default, that path is dependent on CRAFT_STORAGE_PATH, but can be set directly using the CRAFT_REBRAND_PATH bootstrap variable. Any image file in an icon/ or logo/ subdirectory of your rebrand path will be used for the Site Icon and Login Page Logo, respectively—the existence of the file is enough for Craft to discover and display them. On Craft Cloud, we recommend explicitly setting CRAFT_REBRAND_PATH to a path within your project…

Here are the top questions we get asked about Craft Cloud, our first-party hosting platform.

You can view current and historical status for Craft Cloud (and our other web services) at status.craftcms.com. Downtime + Outages Cloud’s infrastructure isolates each environment’s compute resources, and uses highly-available database clusters to ensure uninterrupted service. Your projects are hosted independently from our management layer, and are not subject to the availability of our web services like Craft Console or the Plugin Store. Maintenance Any time we perform maintenance on live services, we post a bulletin on the status page. You can subscribe to notifications via email, or as an RSS feed. Routine updates to our web services are typically not shared here, as they do not impact the availability of customers’ projects. Project Health Individual projects report each deployment’s status to its owners. Failed deployments are never released (say, if some part of the build doesn’t work), but a “successful” deployment doesn't mean that the new code is free from regressions! We recommend setting up a tool like Oh Dear or BetterStack to monitor specific conditions appropriate for your project.

Craft Cloud is currently available in North America, Canada, Europe, and Asia/Pacific. You select a region when creating a new project. A project’s region determines where your database and compute resources are located, but not your assets. Choosing a Region Your project should live in the same region that your client (or your client’s audience) is in. Projects cannot be moved between regions, but you are welcome to deploy different projects in different regions. Cloud pricing is consistent across regions. Caching The primary incentive to select a region is a reduction in latency for your audience and administrators. This typically only impacts uncached or dynamic responses that reach your application (like control panel requests). Any request that can be served from our global edge cache or CDN (like statically-cached HTML documents, build artifacts, and assets) will generally not be impacted by your selection. Data Custodianship We encourage all customers to research their country’s data transfer laws. Craft Cloud’s management layer is deployed in the United States, but your project’s compute resources and database are always located in the chosen region. Assets uploaded to Cloud filesystems cannot be kept in a single region, by virtue of the underlying infrastructure’s geographic redundancy and delivery network. Datacenter Geography Our region-specific infrastructure lives in these countries: North America: United States Canada: Canada Europe: Germany Asia/Pacific: Australia Timezones Craft Cloud’s entire infrastructure uses UTC clocks. Select the appropriate timezone (in Settings → General) when setting up your Craft installation to display date information correctly for your region. Dates in the database are stored in the system’s timezone. Backups are captured nightly, respective of your chosen region.

Craft Cloud automatically captures nightly backups of your production environment’s database. These backups (and any manual backups you’ve captured) are stored for 30 days, unless deleted sooner. Backups are managed separately for each environment, and their format depends on your project’s database driver.

All of Craft’s default caching features work as you would expect on Craft Cloud. To supplement this, we provide a static caching system that automatically detects (and purges!) cacheable HTML responses. These static page caches are created and invalidated using the same mechanism as Craft’s own template caches—so any time an element is updated, Cloud knows exactly which pages to purge. By default, only 200-level GET responses are candidates for static caching; redirection and errors (300-level and higher) are not cached, unless you explicitly opt in. Static Cache vs. Template Caches Cloud’s static cache operates on full pages, which means that either the entire page is cached, or the entire page is served by your application. Whether you use additional caching strategies in your templates or back-end is up to you! Craft’s built-in {% cache %} tag can be combined with static caching—but because the caches are invalidated at the same time, they may be redundant. If you have a highly-dynamic front-end that isn’t possible to cache statically, the normal template cache system is still a great option for caching parts of a page. Most Craft features that rely on dynamic rendering are already set up to bypass the cache, including the entire control panel, live preview, any front-end pages that use the session or cookies. Asynchronous CSRF can be enabled in Craft to make most front-end forms cachable. Controlling the Cache The request’s entire URL (including query parameters) is used when determining whether to serve a page from the cache. In Craft versions 4.10 and 5.2, the expires Twig tag was introduced to simplify setting cache headers. Examples are provided below for this method as well as precise control of individual headers via the header tag. Force Caching If you suspect requests are missing the static cache (despite meeting the criteria above), and you know that a page should be cacheable, you can explicitly send cache headers: `twig {% expires in 30 minutes %} {# ...or prior to Craft 4.10 and 5.2... #} {% set halfHour = 60 * 30 %} {% do craft.app.response.setCacheHeaders(halfHour) %} ` Craft always sends the appropriate cache invalidation tags so that the page can be purged, later.

Craft Cloud is part of Craft Console, so features that support teams like multi-user organizations and access control are built in: As a developer or agency, you can create organizations and projects on behalf of clients; As a client, you can invite your development partner to an organization and let them configure a project; Either way, taking advantage of organizations is key to collaborating on Cloud.

Craft Cloud projects allow you to manage multiple distinct environments or “versions” of your site, each with their own resources and settings. Environments are perfect for testing changes before rolling them out to a live site. Team plans include two environments; Pro plans include three. Features Most of your work in Cloud will be in the context of an environment. Each environment’s landing page has a summary of actions that are available to you. Deployments View current and past deployments, or start a new one. Read more about deploying to Craft Cloud. Logs Review + search logs from your live app. Backups Create and download snapshots of your database. Backups are created nightly, and you can start a new one at-will—they’re retained for 30 days, either way. Variables Configure this’s environment variables. Adding, updating, or removing a variable requires a deployment to take effect—but you can make multiple changes, then trigger a deployment to keep related or dependent changes in sync. Cloud automatically sets a number of variables that are essential to your application. These are listed in the System Variables section, and they cannot be changed or overridden. Commands Run a Craft console command from your browser. History and logs for past commands are available here, as well. Every deploy also triggers a cloud/up command, so you’ll see those records among any commands you’ve manually run. Access Get credentials to this environment’s database and asset storage. Don’t share these details with anyone! Settings Rename the environment, or change the branch it’s associated with (and when it will be deployed). Resources Every environment gets its own database. Data is not automatically cloned from one environment to another, so you will need to manually restore a backup—that backup could come from another Cloud environment, or a local development database. All environments in a project share a single asset storage bucket, but they are separated into top-level directories named after their environment’s ID (or, more accurately, its UUID). Cloud generates a preview domain for each environment—or allows you to connect a custom domain or subdomain thereof. Environment Settings When you create an environment, you’ll give it a name, select a Git branch, and choose a deployment trigger. All three options can be changed any time from the environment’s Settings screen. Production Environment In your project’s main Settings screen, you can select a Production Environment. This setting has three effects: Warming The production environment’s function is kept “warm” by our infrastructure by periodically invoking it. To conserve compute resources (and therefore energy consumption), Cloud allows non-production environments’ functions to “sleep” after about 15 minutes. This means that—following a period of no activity—there may be a 1–2 second delay prior to the first request being served. These invocations do not fully bootstrap Craft, so they will be invisible to your application. Front-End URLs Craft Console uses the production environment’s preview domain (or a custom domain connected to it, once verified) when generating public URLs to the project. You may see these at the project level—but when you’re managing a single environment, those URLs will always link to that environment. robots.txt For any environment that is not marked as production, Craft Cloud will serve requests to robots.txt with this body: User-agent: * Disallow: / So they don’t get indexed by search engines. Production environments will allow the application to dictate the contents of robots.txt. Deleting an Environment Environments can be deleted at any time. Keep in mind that their resources will be destroyed, and they will immediately stop serving traffic. Everything below will be unrecoverable: Your database and everything in it will be deleted; Any assets uploaded to the environment will be deleted; We remove all system and custom variables belonging to the environment; The environment’s settings, deployment history, command history, logs, and temporary credentials are all deleted;

As long as your plugin’s design and implementation follows our established best practices, it should work on Craft Cloud without changes. All Craft features are available on Cloud, making the platform’s architectural differences inconsequential when using official, documented APIs. Plugins must be compatible with at least Craft 4.6 (the minimum version of Craft required to run on Cloud), but they may support earlier versions.

Every Cloud project starts with a free 7-day trial. At the end of the trial, you pay for the next month or a year of service. We currently do not support switching from monthly to yearly billing, or vice-versa. Like the Plugin Store and Developer Support plans, all Craft Cloud payments are processed with Stripe. Trials You must have a valid payment method on file to start a seven-day trial of Craft Cloud, but you will not be billed until the end of the trial. If you cancel prior to your first bill, you will not be charged for any services. Trials provide access to all Cloud features, except for custom domains. Connecting a custom domain will prompt you to skip the trial and immediately start a subscription. Either way, you always have access to a preview domain. Personal Accounts + Organizations Payment methods for personal accounts and organizations are separate. You will only be able to create Cloud projects in an account or organization that has a current payment method on file. All Cloud projects are billed to the primary payment method on the account or organization it was created in. Read more about managing payment methods on Craft Console. Billing History View the billing history for a Cloud project by navigating to its Settings screen. You can view all invoices for the current account or organization by clicking the gear icon in the toolbar at the top of any screen, then selecting Billing. Cancellation To cancel an active Cloud project subscription, navigate to the project’s Settings screen in Craft Console and click Cancel Project within the Danger Zone section. Reactivation Canceled projects can be reactivated until the end of the current billing period. Partial refunds are not issued for early cancellation or deletion of a project. Deletion Once a project is canceled, you may immediately delete it via the same Danger Zone. We do not provide refunds for projects deleted prior to the end of the final billing period.

Every Craft Cloud project comes with generous resource quotas and simple, predictable pricing. Environments Projects are given three environments, one of which may be selected as the production environment. You cannot currently purchase additional environments, but you may delete and recreate them whenever you need. Storage We do have a couple of limits in place for storage to prevent platform abuse: Each environment in a Pro project gets 20GB of asset storage; Team project environments get 10GB. Individual files are limited to 200MB; There are no limits on page views, database size, inbound transfer, or the number of content types, plugins, users, entries, or assets you manage within Craft CMS itself, beyond what is allowed by your license. Bandwidth Outbound transfer from your application and asset storage bucket are metered. If a response can be served from our edge (like a statically-cached HTML document, an image transform, or any previously-requested asset or build artifact), it does not count toward your monthly bandwidth: Team projects get 250GB of transfer per month, shared between environments. Pro projects get 500GB of transfer per month, shared between environments. All transfer from our edge and CDN to your clients is free. Most projects will not need to do anything to take advantage of our edge cache, but you can optimize your cache-hit ratio by following our static caching guide, and limit asset egress by creating thoughtful named asset transforms. The following table shows some common resource sizes, and an approximation of the number of uncached requests that fit within the Team plan’s bandwidth quota: Media Type | Typical Size | Requests --- | --- | --- HTML Document | 30KB (Source) | 8,000,000 Image | 1MB (Source) | 250,000 Resized Image | 350KB | ~700,000 These numbers do not represent any actual enforced limits on file sizes or number of requests—they are provided strictly as a means to compare against current or forecasted usage.

Craft Cloud has very little impact on your local development stack. Any changes required to make your project infrastructure-agnostic are apt to be in code or configuration—not tooling! Our Moving to Craft Cloud article covers these changes in detail, but the bits and pieces relevant to local development are collected here.

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 Cloud supports private Composer packages with all the native authentication methods.

Why is my repository not showing up when starting a new project? When creating a project, we show you repositories you have access to through Git providers connected to your personal Craft Console account. If the repository is owned by someone else (even if they're a member of the same Craft Console organization), it may not be discoverable. Here are a few things to check: Was the repository forked from another repository? We can only deploy from “upstream” repositories (those that are not forks). Did you create or push code after reaching this screen? You may need to refresh the page, or wait a few minutes for the repository to be available in the API. Are you viewing the correct organization or context? Use the menu to the left of the search bar to switch providers and contexts. If none of the above work, you may need to reconnect the platform to Craft Console and grant additional permissions: Switch to your personal account with the menu in the upper-right corner; Go to Settings (the gear icon in the upper-right corner), then Integrations; Click Disconnect on the row with your Git provider; Log in to your Git provider, and remove the app or integration: On GitHub, Craft Cloud is registered as an “OAuth App,” and can be managed in your account’s Settings → Applications → Authorized OAuth Apps screen. Click the three dots in the Craft Cloud row, then select Revoke. Instructions for other providers will be added as we roll out support! Return to the Integrations screen in your personal Craft Console account, then click Connect. Carefully review the permissions, and ensure that the organization your repository lives in is properly authorized. On GitHub, this means that it will either either have a green check mark ✓ next to it, or that you've clicked Grant in that row. If the organization only displays a Request button, you may need to contact one of the administrators for access.

Craft Cloud’s infrastructure is always ready for an influx of traffic—but there are still things that you can do to make launch day go more smoothly! Preparation Make sure you have access to your domain’s DNS management tool well in advance of launch. We recommend using a DNS provider that supports CNAME flattening—but it’s not a requirement to connect a domain at Cloud. Domain Validation This is typically the most volatile part of connecting a domain to Cloud—so make sure you’ve started the process by adding the validation records to your DNS provider as soon as you know where the site will live. Don’t worry—validating a domain won't automatically send traffic to Cloud! TTL A few days before going live, consider lowering the TTL on key DNS records to ~300 seconds (five minutes). In most cases, that would be your root domain’s A records—but it could also be a subdomain’s CNAME record. Check out our domains article for more information about what you’ll be asked to update. This gives downstream providers’ caches time to expire, at which point they will re-fetch those records with the new (shorter) TTL—meaning subsequent updates will take less time to be picked up. Cutting Over When it’s time to flip the switch, you’ll need to do two things: Promote your environment to production by selecting it in the project’s Settings screen. This signals to Cloud that the function should be kept warm by the platform so there’s no delay when the first request comes in. Update your domains’ DNS records. Any domains (or subdomains) that should point to your production environment will require changes. Existing Cloudflare users may need to disable proxying on the apex domain. Deployments Chances are, you’ve been iterating and deploying changes frequently over the course of development. Now that the site is publicly accessible, make sure the deployment trigger in your environment’s Settings screen agrees with your team’s desired workflow. Staging Environment If you would like to continue testing and previewing changes with your team (before deploying them to production), consider setting up a second “staging” environment—your Cloud project subscription includes three environments to use however you like!

When you trigger a deployment (by pushing code or manually starting one from Craft Console), Craft Cloud is actually doing three things, in sequence: Build Migrate Release/Deploy This process reflects our general deployment and workflow recommendations laid out in the documentation—but it’s all handled for you! You can review an environment’s deployment history (and the status of any active deployments) by navigating to its Deployments screen. Deployment Triggers Each environment in Cloud defines its own Deploy Trigger, which determines when it is deployed. You may select from: On Push: Deploys whenever a new commit is pushed to the selected Branch, or someone with access to your Cloud project manually starts one (see below). Manual: Deploys are only started manually, from Craft Console. On Push is a great option for teams with a well-defined Git flow that ensures only production-ready changes are committed or merged into the selected branch. 1. Build Step The first thing Cloud does is assemble PHP and Node dependencies, and package them into a new function. This process is described in greater detail in our Build Process and Artifacts article. If your project uses Node (or has unique PHP requirements), we strongly recommend familiarizing yourself with this stage of the deployment! 2. Migrations On your new function, Cloud executes php craft cloud/up (a special version of php craft up), which applies project config changes and database migrations, and publishes all asset bundles. This must complete successfully for the deployment to continue—if a migration fails, the last-deployed version of your project will continue to serve requests. A record of this command (and its output) is added to the Commands section in that environment. 3. Deployment When Cloud determines that the previous two steps have run without issue, it will begin serving requests from the newly-built functions. You can observe the progress of a deployment from the Deployments screen of each environment. There are no limits to the number of times you deploy each month, or the total “build minutes” for those deployments—but each deployment must complete within 15 minutes.

Each of the environments in your Craft Cloud projects come with a generous storage quota. To take advantage of that storage (and other features, like the built-in CDN and image transform service), you must use the Cloud extension’s built-in filesystem type. New Filesystems New projects can start using it right away—new filesystems don’t require any special handling. You can create a new filesystem and volume the same way you would with any other filesystem type. Cloud filesystems do not require any credentials—they’re provided automatically by Cloud’s runtime. When you are ready to stage or launch the project, you can upload your local asset library to the equivalent subpath in the target Cloud environment’s storage bucket. Live assets can be referenced from a local development environment, in read-only mode. Converting a Filesystem Existing projects may require some additional work to ensure their filesystems are migrated properly. This process will differ based on the filesystem’s current type—and if multiple filesystem types are represented in your configuration, you may need to follow different steps for each one.

As part of every deployment, Craft Cloud assembles all the code and configuration required to run your PHP application and build front-end assets. Everything about the build process is dictated by your repository, and the craft-cloud.yaml config file. PHP Your project’s composer.json and composer.lock files determine what PHP packages are installed. By default, Cloud expects both files to be at the root of your repository—but your Composer root can be customized. If either file is missing, the build will fail. Cloud installs packages by running composer install. Node Similarly, Cloud looks for package.json and package-lock.json files at the root of your repository (or at a path set in your config file). Unlike the PHP build step, if package-lock.json is missing, this step is skipped and the deployment will continue. To enable the Node build step, you must set a node-version in your Cloud config file. Build Command Cloud executes the build script via npm run build after installing the listed packages with npm clean-install. You can change which script is run with the npm-script setting in craft-cloud.yaml—or the directory the command is run in with node-path. Special environment variables are exposed to your Node build process: CRAFT_CLOUD_PROJECT_ID: UUID of the project the build is running in. CRAFT_CLOUD_ENVIRONMENT_ID: UUID of the build’s target environment. CRAFT_CLOUD_BUILD_ID: This build’s UUID. You will receive a new build ID for each deployment—even if they have the same GIT_SHA. CRAFT_CLOUD_CDN_BASE_URL: The root URL of your environment’s storage bucket. CRAFT_CLOUD_ARTIFACT_BASE_URL: See Artifact URLs, below. GIT_SHA: The current commit hash being built. NODE_ENV: Always production, for Cloud builds (even in non-primary environments). Custom environment variables are currently not injected into the build container. Artifacts At the end of the build step, the contents of the project’s “artifact path” (the web root, by default) are copied to your storage bucket.

Sites hosted on Craft Cloud can serve traffic on any domain you own. To set up a domain on Cloud, you will need access to its DNS records, which are often managed via your registrar or existing host. Preview Domains Every environment in your Cloud project gets a unique preview domain. Preview domains always end in preview.craft.cloud, and will include your project handle and the first segment of the environment’s UUID. A complete preview domain looks something like this: `txt project-my-handle-environment-b62dec18.preview.craft.cloud ` To find your preview domain, click the globe icon next to any environment in the project navigation menu. If you don't see this icon, it’s likely because it hasn’t been deployed yet!

Craft Cloud supports MySQL and Postgres databases. You will pick a database engine when creating a new Cloud project: if you are starting a new project, we recommend MySQL 8.0; existing projects should use the same engine and version used by their current infrastructure. Both engines support automated and manual backups via Craft Console.

This guide collects information from multiple other articles about making an existing project compatible with Craft Cloud. Most projects will not need any special treatment, and will work with minimal configuration—just like a new project. Heavily-customized projects (including those with a non-standard directory structure) may require additional auditing or configuration. Projects based on our official Composer starter project tend to enjoy a minimally disruptive migration process, but it’s still a good idea to fully review this document and the resources it links to. Code + Configuration The first thing we’ll tackle is updates to your code and configuration. Key Requirements Your Craft project must already be running Craft {globalset:productVitals:vitalsCloudMinCraftVersion} or later to be compatible with Cloud. In addition, you will need to install the first-party Cloud extension. Cloud Config Cloud expects a craft-cloud.yaml file at the root of your repository. At a minimum, this file must contain a php-version key to tell Cloud what PHP runtime to use. It’s also where you’ll communicate to the builder where your Composer and Node “roots” are—if you have customized your project’s directory structure, you may need to provide additional keys in this config file. Read more about using the Cloud config file. Filesystems Craft Cloud does not have a persistent filesystem (it is ephemeral in nature), so Local filesystems must be migrated to use the Cloud filesystem provided by the Cloud extension. We have a dedicated article about working with assets on Cloud, and a section that specifically addresses this migration. Artifacts, Templates, and URLs When you deploy your site to Craft Cloud, an automated build process takes care of generating artifacts via NPM and uploading them to our CDN. This means that they are not directly accessible in the webroot of your site—via the filesystem or over HTTP. See our recommendations for handling references to those artifacts in your templates.

To run a project on Craft Cloud, it must require our first-party craftcms/cloud package. In technical terms, the Cloud extension is a self-bootstrapping Yii module. Practically, it provides… …a special filesystem type that interfaces seamlessly with Cloud’s storage solution; …automatic and reliable configuration of your project’s database connection, cache, queue, and other application components; …Twig helpers for generating special URLs; For most projects—and in local development—the extension will be largely undetectable. It only initializes functionality in environments that suggest (through the presence of special variables) it is necessary.