Setting up an environment to install and run Drupal on a Mac.
Notice.
This article was written when I was testing a local environment before publishing Drupal on Lightsail. After that, when I selected the Tokyo region blueprint on Lightsail, the Bitnami Drupal instance defaulted to version 10.3.3. After installing and updating, this website launched on Drupal 10.3.5. *As of September 30, 2024.
As the article describes, my local Mac environment was set up with Drupal 11.0.4. I had intended to run Drupal 11.0.4 on AWS, but the Drupal instance available through the Lightsail blueprint did not support 11.0.4, so the site launched on Drupal 10.3.5 instead. I apologize for the confusion this creates with the article.
Amazon Lightsail is covered in a separate article.
Setting Up an Environment to Run Drupal on a MacBook.
My MacBook Environment
- MacBook Pro M1 (2021)
- Local server (required to run Drupal on the Mac) — OrbStack Pro
- Local Docker environment — DDEV v1.23.4
- Running PHP 8.3.10, MariaDB 10.11.8, Drupal 11.0.4, Bootstrap5 4.0.3
- Terminal — iTerm / Shell: macOS default Zsh
- Package manager — Homebrew 4.3.22
- Composer 2.7.9
- Editor — VS Code 1.93.1
- GitHub Copilot 1.229.0
- Japanese Language Pack 1.93
- PHP Debug 1.35.0
- Remote SSH 0.114.3
- SSH: Editing Configuration Files 0.86.0
- Remote Explorer 0.4.3
- Vim 1.28.1
*As of September 16, 2024.
Drupal 11.0.4 and Bootstrap5 4.0.3
My original Drupal 10.x website was built with CivicTheme. When I updated to Drupal 11.x and checked compatibility, CivicTheme had not yet added support for 11.x, so I looked for other options. Bootstrap5 4.0.3 was already compatible, which is why I chose it as the theme.
1. Installing Drupal on a MacBook.
Drupal is a CMS that runs as a web application on PHP and a database, so you need to configure PHP and a database to run locally on the Mac.
When I was running WordPress, I used MAMP as a local server. For Drupal I wanted to use Docker containers, so I needed to set up an environment that can run them. For the Docker provider — essentially a packaged local Linux server with web server functionality — I use OrbStack. Docker Desktop is the more common option, but OrbStack is the recommended provider for DDEV, and it's faster and more stable, so I use OrbStack.
Orbstack
OrbStack's advantages are easy installation, fast startup and performance (page load speed and so on) even in a local environment, and built-in SSL support. MAMP can also handle SSL, but the configuration can be quite involved — for running WordPress locally I use the paid version, MAMP Pro.
2. Installing OrbStack.
OrbStack download page Download the zip file from here. Like any other app, just unzip the download and move it to your Applications folder. Installation via Homebrew is also available, making setup very straightforward.
OrbStack documentation After installation, click the icon to launch it. As noted in the documentation, it can also be launched from the terminal.
3. Installing DDEV.
Once OrbStack is installed, install DDEV. DDEV makes it quick and easy to get Docker containers running on a Mac.
DDEV
One of DDEV's strengths is its CMS quickstart feature. Drupal has a quickstart available, and using Composer, Drupal can be installed on the Mac in just a few steps and is ready to use immediately.
4. Installing Drupal.
With DDEV installed, it's time to install Drupal.
Installation Steps.
// Create a folder and navigate into it
% mkdir my-drupal-site && cd my-drupal-site// Write the Drupal configuration to the folder. --php-version=8.3 is specified because PHP 8.3 is the stable PHP version for Drupal 10.3 and later.
% ddev config --project-type=drupal --php-version=8.3 --docroot=web// Install Drupal: recommended-project:^11 installs the latest stable release of Drupal Core 11 or higher.
% ddev start ddev composer create drupal/recommended-project:^11// Update the configuration file
% ddev config --update// Install Drush
% ddev composer require drush/drush// Initial setup of the Drupal admin panel. --account-name=admin sets the login name, --account-pass=admin sets the password.
% ddev drush site:install --account-name=admin --account-pass=admin -y// use the one-time link (CTRL/CMD + Click) from the command below to edit your admin account details.
// Generate a one-time login URL for the Drupal admin account
% ddev drush uli// Launch Drupal
% ddev launch// Installation is now complete. Log in to the admin panel from your browser and you're ready to start building with Drupal.
// Once installation is complete and Drupal is running
% ddev describe// You can view the configuration. (Also visible in composer.json at the project root)
5. Additional DDEV Setup.
After installing DDEV, install nss and mkcert, and configure mutagen.
nss > client and server library for HTTPS
mkcert > library for issuing SSL certificates in a local environment
mutagen > high-speed directory sync tool
mksertやmutagenの設定
// Install nss
% brew install nss // Install mkcert
% mkcert -install// Configure mutagen
% ddev config global --mutagen-enabled Where I got stuck was that Homebrew's install directory was set to the Intel Mac path. I needed to change the path, but a Rosetta error was blocking me from moving forward. The settings from when I was using an Intel Mac had carried over after switching to the M1, so I took the opportunity to reinstall Homebrew to fix it.
Checking the Homebrew Install Location
/opt/homebrew/ — Homebrew install location for Apple Silicon
/usr/local/Homebrew — Homebrew install location for Intel Mac
6. PHP Versions Supported by Drupal Core.
If the PHP version required by Drupal Core doesn't match the PHP version active in your local environment, Drupal will not install. Make sure to use the PHP version specified by the Drupal Core version you're installing.
% php -v *Use this to check your PHP version.
Changing the PHP Version Per Project.
Drupal 11.x was relatively new at the time of writing, and some themes had compatibility issues or couldn't be installed or updated due to dependency checks. Depending on the theme you're using, you may need to work with a pre-11 version of Drupal — but since Drupal 11.x requires PHP 8.3 or later, if you need to run Drupal 11 alongside a Drupal 10.x project that uses an older PHP version, Direnv is useful.
Direnv lets you assign different PHP versions to different working directories, so you can match the PHP version to whatever Drupal Core version your theme requires, and run multiple projects with different versions side by side on your local Mac.
7. Conclude.
In this article, I configured my Mac to run Drupal and got it up and running. Here's a brief summary of what I did.
- Set up a local server environment — installed OrbStack
- Set up a container environment on the local server — installed DDEV
- Configured the local server environment, including mutagen
- Verified the environment before installing Drupal — PHP version, database version, etc.
- Updated or installed the necessary software via Homebrew
- Installed Drupal using DDEV's CMS quickstart feature
That's the sequence I followed to install Drupal 11.0.4 on my MacBook.
Why I Chose Drupal 11.x
My reason for installing Drupal 11 was that I was planning to use AWS down the line. Looking into AWS, I found that Lightsail had a partnership with Bitnami and offered a Drupal environment.
Checking the available Drupal installations across Lightsail regions, they were all on the latest version, with 10.3.5 and 11.0.4 as the standard options. Since I was planning to use AWS, I decided to go with the latest — Drupal 11.0.4.
I hadn't fully decided how to use AWS, but using EC2 and RDS together — the most AWS-native approach — felt like overkill for my setup, and the cost would be high. Lightsail was the candidate I had in mind.
Notice
This article was written when I was testing a local environment before publishing Drupal on Lightsail. After that, when I selected the Tokyo region on Lightsail, the Bitnami Drupal instance defaulted to version 10.3.3. After installing and updating, this website launched on Drupal 10.3.5. *As of September 30, 2024.
As the article describes, my local Mac environment was set up with Drupal 11.0.4. I had intended to run Drupal 11.0.4 on AWS, but the Tokyo region on Lightsail did not support 11.0.4, so the site launched on Drupal 10.3.5 instead. I apologize for the confusion this creates with the article.
Amazon Lightsail is covered in a separate article.
The next article covers selecting a theme compatible with Drupal 11.x and putting it to use.
Drupal's built-in Olivero theme is well-made, but Bootstrap5 offers more flexibility and works without issues on the 11.x series, so this article covers installing and configuring Bootstrap5.