Installation

The prevalence of modern, mature PHP development tools and infrastructure makes Craft easy to install, run, upgrade, and deploy.

This quick-start guide focuses solely on setting up a local Craft development environment. If you’re ready to launch, jump to the hosting or deployment section.

If at any point you feel stuck, the Tutorial is a comprehensive guide for anyone who wants to get set up with a fast, reliable development environment.

Downloading or installing Craft by any means binds you to its license (opens new window).

# Quick-Start

Your journey with Craft begins on your local machine, using DDEV (opens new window). DDEV is a Docker-based PHP development environment that streamlines the creation and management of resources required by a Craft project.

While we strongly recommend DDEV for new Craft projects, alternate installation methods are available for anyone with a preexisting environment or preferred workflow that meets its requirements.

Install or update DDEV (opens new window), then follow these steps:

  1. Create a project directory and move into it:

    mkdir my-craft-project
    cd my-craft-project/
    
  2. Create DDEV configuration files:

    ddev config --project-type=craftcms --docroot=web --php-version=8.2
    
  3. Scaffold the project from the official starter project (opens new window):

    ddev composer create -y --no-scripts "craftcms/craft"
    
  4. Run the Craft setup wizard, and accept all defaults (in [square brackets]):

    ddev craft install
    

    Our First-Time Setup (opens new window) guide in the Knowledge Base has more information about what to expect during setup.

Congratulations! You now have a fully-functional Craft application installed and configured. Run ddev launch to view the starter project’s welcome screen:

my-craft-project.ddev.site
A new Craft installation’s welcome screen
1

# Next Steps

Ready to dive in? Sign in to the control panel by clicking Go to your control panel from the welcome screen, or running ddev launch admin. The username and password you provided during setup (opens new window) were used to create the first admin user.

You’re welcome to explore things at your own pace—but here are some great starting points:

Done for the day? ddev stop (opens new window) will spin down any containers for the project and free up system resources. ddev start (opens new window) boots everything back up, right where you left off.

# Workflow + Collaboration

We believe that starting with a local development environment (rather than directly on a remote server) fosters a workflow that will support the reliability and longevity of your project.

Defining a Workflow
Recommendations for hosting and deploying a Craft application.

To get a collaborator set up, commit your working folder to git (including the .ddev/ directory) and create a database backup. Have them clone the project and run:

ddev start
ddev import-db path/to/backup.sql

# Further Reading

# Why DDEV?

DDEV is our recommended development environment because it isolates software required to run Craft from your local machine—and from your other projects. Each of your sites can be spun up with its own database and PHP version, without the need to manage or switch between specific software packages.

The environment for each project is defined as YAML files (opens new window), meaning ddev start is usually the only thing required to start working on a project on a new machine—or with a collaborator.

The Docker requirement is not taken lightly! We believe that this one-time installation is much more sustainable for new and returning Craft developers than managing a bare-metal development environment—locally or on a remote server.

# Alternative Installation Methods

Depending on your experience and preferred development environment, you may find one of these platform-agnostic installation processes more comfortable:

Pre-built starter project ZIPs should only be used for evaluating Craft in limited circumstances.

# Hosting

Selecting a Host
Know your options when looking for a good hosting solution.

Craft’s own footprint is relatively light, but it’s important to choose a platform that matches your traffic, storage, and redundancy needs. We maintain a list of Craft-friendly providers (opens new window) for projects of varying scale.

# Deployment

Hosting & Deployment
Recommendations for hosting and deploying a Craft application.

There is no one-size-fits-all deployment strategy for a Craft project, but we’ve collected our most salient advice in the Deployment Best Practices (opens new window) Knowledge Base article.

Regardless of your target infrastructure, it’s important to define a workflow for yourself and your collaborators. Starting a project from a local environment sets a precedent for the flow of code and configuration; while it is possible to scaffold a project directly on a remote host, maintaining a single source of truth for the site will become difficult with changes being made in multiple places, by multiple parties, or without a means of testing those changes in isolation.

# Troubleshooting

Having trouble with DDEV? Make sure your Docker (opens new window) installation is working properly, then head to their troubleshooting (opens new window) page for specific issues.

See the Troubleshooting a Failed Craft Installation (opens new window) Knowledge Base article for more common installation hang-ups.