Install Drupal locally with DDEV

Published

Updated

Set up Drupal 12 on the local machine with DDEV and Drush, prepare settings.php for fortrabbit, and put the project on GitHub.

Install and deploy run down

  1. Install Drupal locally ← you are here
  2. Deploy Drupal to fortrabbit
  3. Database syncing
  4. Files syncing

Get ready

  • DDEV installed and running. Another local setup works too. Drop the ddev prefix from the commands then.
  • The frbit CLI installed and signed in, for the database and files syncing later on. Each step also shows the way without it.
  • Drupal 12 requires PHP 8.5, locally and on fortrabbit.

Create the project

Configure DDEV for Drupal 12, then let Composer create the project and add Drush:

mkdir my-drupal-site && cd my-drupal-site
ddev config --project-type=drupal12 --docroot=web --php-version=8.5
ddev start
ddev composer create-project drupal/recommended-project:^12
ddev composer require drush/drush:^14
shell

Drupal 12 needs Drush 14. Drush 13 does not install with it.

Until Drush 14.0.0 is released, Composer needs to accept the development version: run ddev composer config minimum-stability dev and ddev composer config prefer-stable true before requiring drush/drush:14.x-dev.

Drupal CMS

Drupal CMS is Drupal core plus site templates and recipes, installed through the browser. It runs on Drupal 11 until it moves to 12.

mkdir my-drupal-site && cd my-drupal-site
ddev config --project-type=drupal11 --docroot=web --php-version=8.5
ddev start
ddev composer create-project drupal/cms
ddev composer require drush/drush
ddev launch
shell

Drupal CMS ships Drush as a dev dependency only, and the fortrabbit build leaves those out. composer require drush/drush moves it to require.

Drush and dr

Drupal core ships its own command line tool, vendor/bin/dr. It installs sites, rebuilds caches and creates login links, and is meant to replace Drush over time. It cannot import configuration or run database updates yet, so deployments on fortrabbit use drush deploy.

settings.php

Edit web/sites/default/settings.php before installing Drupal. Add this block above the DDEV include near the end of the file:

$settings['config_sync_directory'] = '../config/sync';

if (getenv('DB_HOST')) {
  $databases['default']['default'] = [
    'driver' => 'mysql',
    'database' => getenv('DB_DATABASE'),
    'username' => getenv('DB_USERNAME'),
    'password' => getenv('DB_PASSWORD'),
    'host' => getenv('DB_HOST'),
    'port' => getenv('DB_PORT') ?: '3306',
    'prefix' => '',
    'collation' => 'utf8mb4_general_ci',
  ];
  $settings['hash_salt'] = getenv('DRUPAL_HASH_SALT');
}
php
  • The first line puts the config sync folder outside the web root, into Git. Without it, DDEV puts it into web/sites/default/files/sync, which is neither committed nor deployed.
  • Drupal does not read ENV vars on its own: the database connection and the hash salt come from settings.php only. The if block maps the DB_* and DRUPAL_HASH_SALT variables of the Drupal software template. They exist on fortrabbit only; locally, DDEV's own settings.ddev.php connects the database.

Install Drupal

Install the site with Drush or the browser installer, then export the configuration:

ddev drush site:install standard --account-name=admin -y
ddev drush config:export -y
shell

A fresh Drupal 12 site greets visitors with "Access denied". Not a bug: the front page is an admin page. Log in with ddev launch $(ddev drush user:login) and set a front page under Basic site settings.

Git ignores

drupal/recommended-project ships no .gitignore. Create one in the project root:

/vendor/
/web/core/
/web/modules/contrib/
/web/themes/contrib/
/web/profiles/contrib/
/web/libraries/
/web/sites/*/files/
/web/sites/*/settings.local.php
/web/sites/*/settings.ddev.php
*.sql.gz
gitignore

*.sql.gz keeps database dumps out of the repo. GitHub has a longer Drupal.gitignore.

Push to GitHub

Put the project on GitHub, here with the GitHub CLI:

git init
git add .
git commit -m "Init"
gh repo create --private --source=. --push
shell

Written by AI, lectured by a human.

AI use & editorial processEdit on GitHub ↗