The correct way to work with Drupal distributions

Have you ever wondered how you can easily build your Drupal site on top of a distribution? And how to keep it up to date? And how to keep your Git repository clean and containing only your custom code? And how to reuse this distribution on other sites?

If so, you are not alone. There are many agencies and developers who would greatly benefit from having a simple and easy way to work with distributions when building their Drupal sites.

Since that Platform.sh natively supports Drush Make files and building distributions, you can push a single file which lists all the dependencies for your site, and Platform.sh will download them automatically when you push your changes.

Example with Commerce Kickstart

Let’s say you want to build your site on top of Commerce Kickstart which is a Drupal distribution based on Drupal Commerce.

Instead of downloading and extracting the whole Commerce Kickstart distribution in your Git repository, you can simply add it to your  project.make  file and define its type as:  profile . This will produce a Drupal site with  commerce_kickstart  inside  profiles/commerce_kickstart .

Then you can add any contributed modules, themes, libraries… to this make file, and even override the ones included in the distribution (to specify a new version, apply patches…).

Finally you simply add your custom code to your Git repository.

Your Git repository should look something like this:

.git/
.platform/
.platform.app.yaml
libraries/
modules/
project.make
themes/

And your  project.make :

api = 2
core = 7.x
projects[drupal][type] = core
projects[commerce_kickstart][type] = profile
projects[commerce_kickstart][download][type] = git
projects[commerce_kickstart][download][url] = "https://github.com/commerceguys/commerce_kickstart.git"
projects[commerce_kickstart][download][branch] = "7.x-2.x"
projects[commerce_kickstart][download][revision] = "94ec50f15cce56b45978eb444206244db1177c86"
; Example of a module override: Downgrade CTools from 1.7 (included in Kickstart) to 1.6
projects[ctools][version] = 1.6

Now, everytime you want to upgrade or apply a patch to the Commerce Kickstart distribution, or any contributed project, you simply need to change 1 line in your  project.make  file and push again.

Example with a private distribution

If you maintain your own distribution in a private Git repository and want to use it for your project, do it the same way.

In that case, make sure you have added the SSH key provided by Platform.sh so that it can pull from your private repository.

Building locally

When working locally, you can still use the Platform.sh CLI to build your site the same way as Platform.sh would do when pushing via Git:

platform build

Or simply use Drush:

mkdir -p web
drush make project.make web -y --concurrency=4

That’s it! Feel free to comment if you have any questions.