Aquifer on Pantheon

Aquifer on Pantheon isn’t a feature that works out of the box, but it does work. In this tutorial I will teach you how in four steps:

1. Installing Aquifer
2. Creating a new Aquifer project
3. Preparing your project for Pantheon
4. Next steps

Node

If you don’t have nvm (node version manager) installed, it is highly recommended.

Installing Aquifer

The Aquifer documentation is officially hosted at http://aquifer.io/.

If you are looking to just get Aquifer working the Quick Start Guide will run you through the steps of getting Aquifer set up on your local environment.

WARNING: Until Aquifer releases a new version, the version installed when following the quick start guide will not work with the rest of this tutorial.

So, which version of Aquifer does work with this tutorial?

We will be using the Aquifer branch 1.0.0. This is the latest development branch until we get a full 1.0.0 release.

Setting up a development version of Aquifer:

This page contains a section called “Installing for development;” this will be the set of instructions we follow.

It basically says:

1. Run node --version to check that you are running node v6.3.1 or later. If not, use nvm to install a more recent version.
2. If you had a version of Aquifer already installed, delete the node_modules directory within the Aquifer directory.
3. If not, navigate to a directory you wish to install Aquifer in and clone the repository:
   a. git clone git@github.com:aquifer/aquifer.git # SSH version – or –
   b. git clone https://github.com/aquifer/aquifer.git # HTTPS if no github keys
4. IMPORTANT: Checkout the 1.0.0 branch git checkout 1.0.0
5. Run npm install to get the latest packages.
6. Then run npm link to tell node that you have a command line package outside of the normal node install directory. This will also create a symlink in your /usr/local/bin directory and your /usr/local/lib/node_modules directory for your new Aquifer command.
7. Verify your Aquifer version by running aquifer --version (this will return 1.0.0-beta1; that is correct as of 7-Sept-2016).

If you made it this far without errors, congratulations, you are doing good! You can now use this directory as a normal Git repository and can switch branches and update Aquifer as the latest updates come out.

Creating a New Aquifer Project

Now we’ll setup a new Aquifer project. You can use an existing Aquifer project but for purposes of this demo we will use a new project.

1. Navigate to a directory you want to install your Aquifer project in.
2. Create a new project named “test”: aquifer create test
3. Navigate into the project that was generated: cd test
4. Then, run aquifer build (This should complete without errors. If it doesn’t, your environment should be fixed at this stage before continuing).

Preparing Your Project for Pantheon

Editing drupal.make.yml

BIG PICTURE: We are replacing the standard Drupal core with Pantheon’s Drupal core based on Pressflow. Without this step your site won’t run on Pantheon. You can feel free to replace the reference to Pantheon’s core with Acquia’s core, Pressflow, another hosting provider’s core, or a distribution, depending upon your exact needs. This flexibility is one of the many benefits of using Aquifer.

1. Using your normal text, editor open the drupal.make.yml file
2. It should say core 7.x

This:

projects:
  drupal:
    version: ~
  admin_menu:
    version: ~

Should read:

projects:
  # Core version 7.50.
  drops_7:
    type: "core"
    download:
      type: "git"
      url: "git@github.com:pantheon-systems/drops-7.git"
      branch: "master"
      revision: "2f1c945d01cd03250e2b6668ad77bf24f54a5a56"
  # Contrib
  admin_menu:
    version: ~

For your convenience, this is Acquia’s configuration (UNTESTED):

projects:
  # Core version 7.50.
  drupal:
    type: "core"
    download:
      type: "git"
      url: "git://git.acquia.com/drupal/branches/7.x.git"
      branch: "master"
      revision: "837b8d22cd084b5c15f93ef6b65a98d9d20ee80f"
  # Contrib
  admin_menu:
    version: ~

For your convenience, this is Pressflow’s configuration (UNTESTED):

projects:
  # Core version 7.44.
  drupal:
    type: "core"
    download:
      type: "git"
      url: "git@github.com:pressflow/7.git"
      branch: "master"
      revision: "c3d3e3b7c07ff19bdbf8eddbafb9340c489ee23c"
  # Contrib
  admin_menu:
    version: ~

Note: Change the revision to the commit SHA of any version. Then run:

aquifer build

If this succeeded and in your terminal output you see:

drops_7 cloned from git@github.com:pantheon-systems/drops-7.git.     [ok]
Checked out revision 2f1c945d01cd03250e2b6668ad77bf24f54a5a56.       [ok]

You now have a Pantheon ready project. Congratulations you just leveled up!!!

You could build this to a separate directory and use this as an artifact repo, but why don’t we upgrade you project one more time and make deployments easier?

Setting up Pantheon

If you have not already done so, this would be a good time to create a FREE developer’s account on Pantheon. Also, setup a new project and give it a name (we will need that shortly). Don’t worry too much about setup here, we are going to change things soon.

Editing aquifer.json

BIG PICTURE: We are going to build the project and have it overwrite and commit on the destination remote. Conceptually, a normal workflow for this ends up creating two repositories: (1) Your aquifer repository (where all the source code lives) and (2) your artifact repository (the built site with core, contrib, files, etc, ready to run).

1. Using your normal text editor open the aquifer.json file
2. The part we want to focus on here is the extensions.

In a new project, this reads:

  "extensions": {},

We need to update this to add the aquifer-git extension:

"extensions": {
  "aquifer-git": {
    "source": "aquifer/aquifer-git#1.0.0",
    "remote": "{copy and paste your git connection info from pantheon here}",
    "branch": "master"
  }
},

The code block above will deploy directly to Pantheon. If you would like to deploy to GitHub first instead change the remote info to point to your GitHub repository.

Additional details about the aquifer-git configuration:

On this line:

"source": "aquifer/aquifer-git#1.0.0",

We are specifically telling aquifer we want to use the 1.0.0 branch of the aquifer-git extension which is the latest development version as of the writing of this article.

On this line:

"remote": "{copy and paste your git connection info from Pantheon here}",

By doing this, you add the ability to deploy your Aquifer project to the specified Pantheon remote. A Pantheon remote string should look something like this:

ssh://codeserver.dev.hash@codeserver.dev.hash.drush.in:2222/~/repository.git

But don’t limit your imagination. The remote can be another directory on your local machine, a GitHub repository, or another remote host.

On this line:

"branch": "master"

We specify that aquifer-git will default to using the master branch.

NOTE: On Acquia you may need to set (SUPER UNTESTED – YOU SHOULD RESEARCH):

"folder": "docroot",

For additional information on configuring aquifer-git, see the README.

You now need to run aquifer extensions-load to download and install the new extension.

Once the extensions have loaded, you are ready to start deploying. Make sure your ssh keys are setup and type:

aquifer deploy-git

If this command succeeds then you now have a working Aquifer project on Pantheon. If you didn’t deploy straight to Pantheon you will have some additional configuration here.

Next Steps

Setup your database

If you haven’t already this would be a good time to setup your database.

Transfer your files

If you haven’t already this would be a good time to transfer your files.

Editing settings.php

---

OPTIONAL – EVERYTHING BELOW IS UNTESTED CODE IN DEMO

• You may wish to separate out your Pantheon configuration in a separate settings.php file named pantheon.settings.php. If so, you will need to add the following to your aquifer.json file:

"settings/pantheon.settings.php": {
  "destination": "sites/default/pantheon.settings.php",
  "method": "symlink",
  "conflict": "overwrite"
},

• If you choose to implement a new file for Pantheon settings then you will need to alter your settings.php file to include the following right before your normal last code block implementing local.settings.php:

// All Pantheon Environments.
if (defined('PANTHEON_ENVIRONMENT')) {
  include DRUPAL_ROOT . '/sites/default/pantheon.settings.php';
}
else {
  // We are not on a pantheon environment. This is for local.
}

• In your master module configuration you may wish to include pantheon specific modules like pantheon_apachesolr for dev, test, and live.

---

Congratulations

If you made it here, you rock!

Additional tech review by Jeff Tomlinson.