Getting Started with Craft Cloud
Welcome to Craft Cloud, our new hosting platform tailor-made for Craft CMS!
This article covers the critical path to deploying your first project to Cloud. For new projects, we still recommend starting with a local development environment; most existing projects can be moved to Cloud after a quick system update.
The process looks something like this:
- ✏️ Spin up a Craft project locally
- 🌩️ Push your code to a repository and connect it to a new Cloud project in Craft Console
- 🚀 Kick off your first deploy
Let’s get started!
Requirements #
In addition to a basic familiarity with Craft CMS, this guide will require…
- …a Craft Console account with a payment method on file;
- …a GitHub, BitBucket, or Gitlab account;
- …access to your domain’s DNS records (when you’re ready to go live);
You will be able to follow along using the seven-day free trial included with every Cloud project.
Preparing your Codebase #
Any Craft CMS site running version or later can be configured to run on Cloud. Plugins and custom modules must be compatible with at least PHP 8.1.
New Sites #
Cloud projects begin the same way as any other. Follow the standard installation instructions to get a new site running locally, then run this command to get it Cloud-ready:
ddev craft setup/cloud
Craft will install the craftcms/cloud extension, which handles all the necessary configuration, automatically. Your project will continue to work normally, in local development.
Commit and push the project files to a fresh Git repository.
Existing Sites #
Update your project to at least Craft 4.6.0, then run the command above. Most projects will run on Cloud without modification—but we recommend reviewing the compatibility guide if you’ve made any customizations via application config, custom modules, or private plugins. We also have a dedicated guide on moving projects to Craft Cloud from other hosts.
Does your project use the tablePrefix setting or CRAFT_DB_TABLE_PREFIX config variable? Run ddev craft db/drop-table-prefix before continuing.
Commit and push the changes to your Git provider. You’re ready!
Gathering Materials #
With your project running locally, it’s the perfect time to collect a few things we’ll need later:
- Capture a database backup and take note of the driver (Postgres or MySQL) and version;
- Download a copy of all your assets (if feasible);
- Document all your project-specific environment variables;
Your First Cloud Project #
If you haven’t already, create a Craft Console account and add a payment method.
Cloud projects can be created from your personal Console account, or within an organization, but we strongly recommend using organizations whenever possible—especially for businesses and agencies that can benefit from delegated access.
From the Cloud tab, click New Project. Select from the available git providers (or connect a new one), then choose the repository your Craft project was pushed to, in the previous step. Don’t see your repo? Try one of these troubleshooting tips.
Project Settings #
When creating a project, you will be asked for a Project Name and Handle, what Region it should be hosted in, and the Database Engine you’d like to use. The database engine should match whatever you are using locally—if you just started a new project with DDEV, that would be MySQL 8.
Billing + Terms #
You can pay for Cloud projects monthly or annually. Discounts are provided on annual plans, and to verified Partners. Learn more about how billing works.
All Cloud plans come with a free seven-day trial!
Deployment #
With your Cloud project connected to a Git repository, it’s time to set up an Environment. Environments allow you to configure and deploy multiple versions of your project, independently—like a live site and a staging site.
Create an Environment #
Each environment is associated with a Git branch, and gets its own database, asset storage, environment variables, logs, preview domain, and deployment strategy.
From your project’s dashboard, click Environments, then New environment. Give it a Name, and select your desired Deploy Trigger and Branch. Below the settings pane, you’ll have an opportunity to pre-populate the environment with project-specific variables that you would normally store in a .env file. You do not need to copy database connection details, URLs, or variables you would only set in a development environment—most configuration will be handled for you, automatically!
Click Save, and Cloud will create the environment’s resources.
If you selected “On Push” for your Deployment Trigger, Cloud will deploy this environment the next time you push a commit to the selected branch. Both “On Push” and “Manual” triggers allow you to visit the Deployments tab of the environment and click Deploy to build and deploy from the latest code.
Importing a Database #
See our article on working with Cloud databases to learn about the process of making and importing a database backup. The process will differ slightly for Postgres and MySQL users.
Importing Assets #
If you just started a new project, you can skip this section, and review our Assets on Craft Cloud article when you’re ready to set up your first asset volume.
Existing projects that use a Local asset filesystem will require an update to work on Cloud. See our article about migrating to Cloud asset storage for more information. While we do not impose limitations on the third-party services your app communicates with, their plugins may require updates to be fully compatible with Cloud.
Triggering a Deploy #
In your environment’s Deployments screen, click the Deploy button in the upper-right corner.
Cloud will begin a new build, and your changes will be available at your preview domain in a minute or two!
Preview Domains #
Every environment gets a preview domain so you can make sure everything is working as expected before pointing your real domain at it.
Not seeing your changes? Deployment status is reflected on the Deployments overview page, and more information is available when clicking the commit message of a single deploy.
Custom Domains #
When you’re ready to cut over, check out our guide on using custom domains. Your first custom domain (and any number subdomains thereof) are free with a Cloud project.