Using the Starter Project

While DDEV is a quick, reliable way to get started with Craft, it’s not your only option! As long as your environment meets Craft’s requirements, you’ll be able to follow along.

We’ll start with the fundamentals shared by most installation methods, then discuss some tool-specific tips.

Please be aware that downloading or installing Craft binds you to its license.

Composer #

Composer is a PHP dependency manager that Craft uses internally to install and update plugins—but it can also be used to install and update Craft itself. If Composer is not available on your command line, follow the global installation instructions, or use a package manager like apt or Brew.

Use the create-project command to scaffold a new site from the official starter project package, in a folder named my-craft-project:

composer create-project craftcms/craft my-craft-project

This command automates a number of setup steps:

1. Creating the my-craft-project/ directory;
2. Downloading and extracting the latest starter project release;
3. Installing PHP dependencies;
4. Populating a basic .env configuration file for development;
5. Launching the Craft setup wizard;

Setup #

Up to this point, everyone’s experience of the starter project will be basically the same—once you enter setup, however, you will need to make choices that rely on the specifics of your development environment.

To get an idea of what to expect, check out our dedicated setup wizard article.

Directory Structure #

The starter project directory structure may feel a little foreign, if you are coming from other PHP-based web applications. Here are some things to keep in mind:

• Both composer.json and composer.lock should stay with your project. Together, they define exactly what versions of any PHP packages your site depends on—this means you can ignore the entire vendor/ directory, but still reconstruct the project in other environments;
• The web/ folder is your site’s “web root,” but it can be renamed to whatever you want (www/, public/, public_html/, etc.);
• The structure may not agree with all development or hosting environments. You can move Craft’s files below the web root if this becomes a problem;
• There are two “entry scripts” in every project—one for handling web requests (web/index.php) and one for handling console commands (craft);

Creating a Project from Scratch #

If you want to take a closer look at the structure of the starter project, check out our Setting up a Craft Project from Scratch guide.

Tool-Specific Variations #

Use of the starter project will always involve Composer’s create-project command—but how and when it’s run may depend on your chosen development environment.

DDEV #

See the official installation instructions.

Docker / Docker Compose #

Compose commands can be run in a one-off container on any system with Docker installed:

docker run \
  --rm \
  --volume $PWD:/app \
  composer \
  composer create-project craftcms/craft my-craft-project --ignore-platform-reqs

This will create the my-craft-project directory and bootstrap a new project in it. To set up a complete development environment, read our Local Development with Docker guide.

Homestead #

Create your project directory and add it as a shared folder. Then, SSH into the virtual machine, navigate to the mapped directory, and run composer create-project craftcms/craft . to initialize the current directory (denoted by the dot . character).

When setup is completed, add an nginx host pointing to the new web/ folder, within your project directory.

Valet #

No special steps are necessary, as Valet uses the software installed directly on your machine (usually via Brew) rather than within a virtual environment. Commands can be run verbatim.

Pay special attention to database connection details. If you are able to connect with a database GUI, the credentials should be the same. When running multiple versions of the same database engine, ports may differ.

MAMP, WAMP, XAMPP, etc. #

This family of tools generally comes with its own PHP and MySQL binaries. The most common issue when working with a new site is a mismatch between PHP versions used by the web server and command-line interface. Check what version of PHP is available in your terminal by running php -v, or which php.

If PHP 8.0.2+ is already available in your terminal, you can dive in with the generic instructions, above—otherwise, you may need to set or change the default version from your tool’s GUI, before using Composer.

Once you’ve run the normal composer create-project ... command to scaffold a new project, create a host. The host’s “web root” or “document root” should be the web/ directory inside your new project folder, like ~/Sites/my-craft-project.

MAMP only supports MySQL databases, so your .env file should look something like this:

CRAFT_DB_DRIVER="mysql"
CRAFT_DB_SERVER="localhost"
CRAFT_DB_PORT="3306"
CRAFT_DB_DATABASE="your_database_name"
CRAFT_DB_SCHEMA="public"
CRAFT_DB_TABLE_PREFIX=""

# The following two properties are MAMP defaults.
# They may differ if you’ve added or modified users!
CRAFT_DB_USER="root"
CRAFT_DB_PASSWORD="root"

More info on database connections can be found in the documentation.

Other Tools + Platforms #

Don’t see your favorite tool? Reach out and let us know about it. We want Craft to be accessible to everyone!

Community Starter Projects #

The official starter project is kept deliberately lean, to focus on Craft-specific concepts. We understand that some developers and teams will want to try out Craft with their favorite tools—and share what they’ve learned with the community!

Any other starter project can be used in place of the default one by substituting its package name for craftcms/craft when running composer create-project.