Drupal Local Installation — Composer, DDEV and Lando Setup Guide

In this tutorial, you'll learn four ways to install Drupal locally: using Composer from scratch, with DDEV for containerized development, with Lando for config-driven setups, and via the traditional manual method for legacy environments.

What You'll Learn

• System requirements for running Drupal locally (PHP, MySQL, web server)
• Installing Drupal via Composer using composer create-project
• Setting up a Drupal development environment with DDEV
• Setting up Drupal with Lando for Docker-based local development
• Manual Drupal installation process and web installer walkthrough
• Drupal directory structure and settings.php configuration

Why It Matters

A reliable local development environment is the foundation of productive Drupal development. Knowing multiple installation methods lets you choose the right approach for each project -- whether you need a quick sandbox, a team-standardized Docker environment, or a production-matching setup. Misconfigured environments waste hours of debugging time.

Real-World Use

A Drupal agency managing 20 client sites uses DDEV with each project at different Drupal versions. Developers run ddev start in any project directory and immediately have the exact PHP version, PHP extensions, database, and tools configured for that specific project. No more "works on my machine" problems when handing off projects between developers.

Learning Path

flowchart LR
  A[What is Drupal] --> B[Local Installation]
  B --> C[Admin Dashboard]
  C --> D[Hosting]
  D --> E[Content Types]
  E --> F[Fields]

System Requirements

Before installing Drupal, ensure your system meets these requirements:

Verify your PHP version and available extensions using the command line:

php --version
php -m

Verify MySQL connection:

mysql --version
mysql -u root -p -e "SHOW DATABASES;"

Installing via Composer

Composer is the recommended way to install and manage Drupal and its dependencies. The drupal/recommended-project template provides the optimal starting point.

composer create-project drupal/recommended-project drupal-site
cd drupal-site

This command downloads Drupal core and all recommended dependencies including Drush (the Drupal CLI tool), and sets up the correct directory structure.

After Composer finishes, create your database:

mysql -u root -p -e "CREATE DATABASE drupal CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p -e "CREATE USER 'drupal'@'localhost' IDENTIFIED BY 'password';"
mysql -u root -p -e "GRANT ALL PRIVILEGES ON drupal.* TO 'drupal'@'localhost';"
mysql -u root -p -e "FLUSH PRIVILEGES;"

Now start the PHP built-in web server to run the installer:

cd web
php -S localhost:8080 .ht.router.php

Open http://localhost:8080 and follow the web installer. Select "Standard" installation profile and enter your database credentials.

Installing via DDEV

DDEV provides a containerized Drupal development environment using Docker. It manages PHP versions, databases, and web servers automatically.

First, install DDEV from https://ddev.com/get-started/

# Create a new Drupal project with DDEV
mkdir my-drupal-site
cd my-drupal-site
ddev config --project-type=drupal --docroot=web
ddev start

This configures DDEV with Drupal support and starts the containers. Now install Drupal via Composer inside the container:

ddev composer create-project drupal/recommended-project
ddev drush site:install --account-name=admin --account-pass=admin -y
ddev launch

DDEV provides additional useful commands:

ddev drush uli
ddev import-db --src=dump.sql
ddev export-db --file=dump.sql
ddev ssh
ddev php test.php

Your site will be available at https://my-drupal-site.ddev.site.

Installing via Lando

Lando is another Docker-based local development tool with a configuration file approach.

First, install Lando from https://lando.dev/download/

mkdir my-drupal-site
cd my-drupal-site
lando init --recipe drupal --webroot web
lando start

This creates a .lando.yml configuration file:

name: my-drupal-site
recipe: drupal
config:
  webroot: web
  php: '8.3'
  database: mysql:8.0

Install Drupal and run the installer:

lando composer create-project drupal/recommended-project . --no-interaction
lando drush site:install --account-name=admin --account-pass=admin -y
lando info

The lando info command shows your site URL, usually http://my-drupal-site.lndo.site.

Manual Installation

While Composer is recommended, understanding manual installation helps with legacy systems and troubleshooting.

1. Download Drupal from https://www.drupal.org/download

wget https://www.drupal.org/download-latest/tar.gz
tar -xzf drupal-*.tar.gz
mv drupal-* drupal-site

2. Create the database in MySQL:

mysql -u root -p -e "CREATE DATABASE drupal CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p -e "CREATE USER 'drupal'@'localhost' IDENTIFIED BY 'password';"
mysql -u root -p -e "GRANT ALL PRIVILEGES ON drupal.* TO 'drupal'@'localhost';"
mysql -u root -p -e "FLUSH PRIVILEGES;"

3. Copy sites/default/default.settings.php to sites/default/settings.php:

cp sites/default/default.settings.php sites/default/settings.php
chmod 644 sites/default/settings.php

4. Set up files directory:

mkdir sites/default/files
chmod 777 sites/default/files

5. Navigate to your site URL and follow the web installer. The installer will ask for:

   • Database type (MySQL)
   • Database name, user, and password
   • Site name and email
   • Admin username, password, and email
   • Country and timezone

6. Select "Standard" installation profile for a full-featured site, or "Minimal" for a bare-bones starting point.

Directory Structure

Understanding the Drupal directory structure is essential for development:

drupal-site/
├── composer.json
├── composer.lock
├── vendor/                  # Composer dependencies (Symfony, Twig, etc.)
├── web/
│   ├── core/                # Drupal core system files
│   ├── modules/             # Contributed and custom modules
│   │   ├── contrib/         # Downloadable modules from Drupal.org
│   │   └── custom/          # Your custom modules
│   ├── profiles/            # Installation profiles
│   ├── themes/              # Contributed and custom themes
│   │   ├── contrib/         # Downloadable themes
│   │   └── custom/          # Your custom themes
│   ├── sites/
│   │   ├── default/
│   │   │   ├── settings.php   # Database and environment configuration
│   │   │   ├── services.yml   # Service container overrides
│   │   │   └── files/         # Uploaded files and generated assets
│   │   └── example.sites.php
│   ├── index.php            # Drupal entry point
│   ├── update.php           # Database update script
│   ├── autoload.php
│   └── .htaccess            # Apache rewrite rules
└── drush/
    └── Commands/            # Custom Drush commands

Settings.php Configuration

The sites/default/settings.php file contains database credentials and environment-specific settings:

<?php

$databases['default']['default'] = [
  'database' => 'drupal',
  'username' => 'drupal',
  'password' => 'password',
  'prefix' => '',
  'host' => 'localhost',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
];

$settings['hash_salt'] = 'your-unique-hash-salt';

Production settings typically include trusted host patterns and environment-specific configuration:

<?php

$settings['trusted_host_patterns'] = [
  '^example\.com$',
  '^.+\.example\.com$',
];

$settings['skip_permissions_hardening'] = FALSE;

ini_set('memory_limit', '256M');

Troubleshooting Installation

Common installation issues and their solutions:

White screen of death

Check PHP error logs:

tail -f /var/log/php_errors.log

Add to settings.php for debugging:

<?php

error_reporting(E_ALL);
ini_set('display_errors', TRUE);
ini_set('display_startup_errors', TRUE);

Database connection error

Verify credentials and database exists:

mysql -u drupal -p -e "SHOW DATABASES;"

Check settings.php database array.

Clean URLs not working

For Apache, ensure mod_rewrite is enabled:

sudo a2enmod rewrite
sudo systemctl restart apache2

For Nginx, ensure your configuration includes the correct rewrite rules.

PHP memory limit

Increase PHP memory limit in php.ini or settings.php:

<?php

ini_set('memory_limit', '512M');

Common Mistakes

1. Using composer create-project drupal/drupal instead of drupal/recommended-project: The drupal/drupal package includes all development dependencies not needed in production, including tests and Behat.
2. Not setting proper file permissions: The sites/default/files directory must be writable by the web server. Use chmod 755 or 777 as appropriate for your environment.
3. Hard-coding database credentials in settings.php for version control: Use environment variables or a .env file to keep credentials out of the Repository.
4. Ignoring the hash salt warning: The hash salt is used for CSRF protection and password hashing. If it changes, all existing sessions and one-time login links become invalid.
5. Running Drupal with the default PHP memory limit: Drupal needs at least 256 MB of memory allocation. The default PHP setting of 128 MB will cause white screens during installation.

Practice Questions

1. What is the difference between drupal/recommended-project and drupal/drupal when using Composer?
2. How do trusted host patterns protect a Drupal site, and how would you configure them for a site with multiple subdomains?
3. What steps would you take to move a Drupal site from a DDEV local environment to a production server?
4. Challenge: Create a bash script that automates a fresh Drupal installation using Composer, creates a MySQL database, installs the site with Drush, and sets up the files directory with correct permissions. The script should accept a site name as a parameter.

FAQ

Mini Project

Goal: Set up a complete Drupal development environment using three different methods.

1. Install Drupal using Composer on your local machine (use composer create-project drupal/recommended-project)
2. Set up the same project using DDEV in a separate directory
3. Set up the same project using Lando in a third directory
4. For each installation, note:
   • Time to complete
   • Commands required
   • URL where the site is accessible
   • Any issues encountered and how you resolved them
5. Create a table comparing the three approaches. Which would you recommend for a team of five developers?

What's Next

With Drupal installed locally, explore the admin dashboard to learn navigation and site configuration. Then set up proper hosting for moving your site to production.