Drupal Development on MacOS

By mbystedt on Jun 25, 2019, 5:39:55 PM

Drupal 8 development with Composer and Drush (or Drupal Console) can easily be done on MacOS (10.14.x) with minimal setup and configuration.

The first step is to eliminate having to make changes to MacOS with Docker. Docker makes it possible to run containers in a virtual environment on MacOS. A container, when active, runs an OS with installed software. By using a container, you have the safety of things (hopefully) being sandboxed in this virtual environment. Running a project becomes as simple as getting the project code and starting the needed containers.

Theoretically, you can also use the container to run the software on the server as well. We'll just be focusing on the ability to run a version of PHP (and database) that matches an existing server setup.

Docker Setup

Step one is to install Docker desktop. An account is required to download the free community edition.

Docker's install process is a pretty standard. So, we won't cover it. After installing, ensure it is running before moving on. Next, we need a Docker container to run.

PHPDocker.io

PHPDocker.io is a useful tool for building a PHP development environment with a couple clicks. It currently lacks the option to install Composer. Instead, we will need to modify the Dockerfile to install it afterwards.

Open up the generator tool and configure things as needed. Some advice is provided below.

Global configuration

Project name: Give it a name like 'drupaldev'
Base Port: Pick something like 8080.
Application Type: Keep it as 'Generic'.

PHP configuration

PHP version: Pick the version closest to you want to use.
Add git: Select On.
Application Type: Keep it as 'Generic'.
Extensions: Ensure 'GD' is checked. Add other extensions as needed.

Database configuration

Add a database. Enter the details. MySql v8 may have issues with it. You'll be able to find the entered values in the 'docker-compose.yml' this tool generates.

Click 'Generate project archive'. We'll be doing a couple modifications to the configuration before starting up the containers. The archive of the project I created is here.

Setup Composer

Composer is a dependency management tool that Drupal and many other PHP projects have adopted. Let's install it in the container we're using. To do this, open the 'phpdocker/php-fpm/Dockerfile' in an editor. Follow the install instructions for Composer. Add 'RUN ' in front of the commands. This will execute the command like you typed it into a console when the container is built. The Docker site has a full reference on how to write a Dockerfile to assemble a container image.

# Install composer
RUN php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
RUN php -r "if (hash_file('sha384', 'composer-setup.php') === '48e3236262b34d30969dca3c37281b3b4bbe3221bda826ac6a9a62d6444cdb0dcd0615698a5cbe587c3f0fe57a54d8f5') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
RUN php composer-setup.php
RUN php -r "unlink('composer-setup.php');"
# Move to directory included in PATH
RUN mv composer.phar /usr/bin/composer

Code 1. Follow latest Composer instructions and add to the end of 'phpdocker/php-fpm/Dockerfile'.

Awesome. Composer also provides projects templates. For Drupal, there's an excellent one that installs Drush and Drupal Console. The next two optional steps install launchers that assist with using them.

Drush Launcher

This optional step makes it easier to use Drush. Please follow the latest install instructions. This page may not be up-to-date. I modified the instructions to use PHP to download the file as the container image does not install other CLI tools for downloading files.

# Install Drush Launcher
RUN php -r "copy('https://github.com/drush-ops/drush-launcher/releases/download/0.6.0/drush.phar', 'drush.phar');"
RUN chmod +x drush.phar
RUN mv drush.phar /usr/bin/drush

Code 2. Add to end of 'phpdocker/php-fpm/Dockerfile'. Note wget changed to a php command.

Drupal Console Launcher

This optional step makes it easier to use Drupal Console. Please follow the latest install instructions. This page may not be up-to-date. Again, I modified the instructions to use PHP to download the file as the container image does not install other CLI tools for downloading files.

# Install Drupal Console Launcher
RUN php -r "copy('https://drupalconsole.com/installer', 'drupal.phar');"
RUN chmod +x drupal.phar
RUN mv drupal.phar /usr/bin/drupal

Code 3. Add to end of 'phpdocker/php-fpm/Dockerfile'. Note curl changed to a PHP command.

Update Nginx Config

There is one configuration change that can be done now if you know how you want to structure your project. Otherwise, this can be done later. The configuration is in 'phpdocker/nginx/nginx.conf'. Alter the 'root' location to where your project's files are. If you follow the remaining instructions, the location will be '/application/drupal/web'.

Start Container

Now for the fun part. Open a console and change the directory to the project. Use code 4 to start things up. The first time this is run it will take a bit to download and setup the container that will run the Drupal website. It will launch quickly next time.

docker-compose up -d

Code 4. Starts the docker containers in 'detached' mode. Execute in directory with 'docker-compose.yml'.

You should now be able to browse to http://localhost:8080. The port will be what was configured on PHPDocker.io. This may just give an error if the change to the Nginx configuration points to a directory that doesn't exist. We'll fix that shortly. A couple more useful docker commands are below.

docker-compose stop

Code 5. Shutdown the docker containers. Execute in directory with 'docker-compose.yml'. Use 'down' instead of 'stop' to reset container state. Save any database changes before using 'down'!

docker-compose build

Code 6. Rebuild the containers. Use if you make changes to the Dockerfile.

Build a Drupal Project with Composer

To use Composer, we need to attach a console to the container with it installed. To do this, we need to find the name or id of the container.

$ docker ps

Code 7. Enter in MacOS Terminal to see running containers. Copy name or id of the container with a name like 'drupaldev-php-fpm'.

docker exec -i -t container_name_or_id bash

Code 8. Enter in MacOS Terminal to start bash command line on specified container.

You should now be running a bash command inside the container. From here, you will have access to the installed PHP Composer. We'll use a project template to install Drupal. Once that's done, you'll have access to Drush and Drupal Console.

$ composer create-project drupal-composer/drupal-project:8.x-dev drupal --no-interaction

Code 9. Create a project with Composer. This will take a while...

You should now be able to load http://localhost:8080 and see Drupal running. You can go ahead and install Drupal. The database information will be in the 'docker-compose.yml' file. The database host will be the same as the name under 'services'. You'll be able to use the container to use Composer to install Drupal themes, extensions, etc. and use Drush or Drupal Console to do maintenance.