Aquifer on Pantheon

Aquifer on Pantheon isn’t a feature that works out of the box but it does work and in this tutorial I will teach you how by covering:

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

Node

If you don’t have

1

nvm

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

   1	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

   1	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.

   1	git clone [email protected]:aquifer/aquifer.git

   # SSH version - or - b.

   1	git clone https://github.com/aquifer/aquifer.git

   # HTTPS if no github keys
4. IMPORTANT: Checkout the 1.0.0 branch

   1	git checkout 1.0.0

5. Run

   1	npm install

   to get the latest packages.
6. Then run

   1

   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

   1	/usr/local/bin directory

   and your

   1	/usr/local/lib/node_modules

   directory for your new Aquifer command.
7. Verify your Aquifer version by running

   1	aquifer --version

   (This will return 1.0.0-beta1 but that is correct as of the time of writing this article).

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”:

   1	aquifer create test

3. Navigate into the project that was generated:

   1

   cd test

4. Then, run

   1	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

   1	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: "[email protected]: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: "[email protected]: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 [email protected]: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 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

   1	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

1

aquifer

1

aquifer-git

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://[email protected]: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: here

You now need to run

1

aquifer extensions-load

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 FROM HERE IS UNTESTED CODE IN DEMO

• You may wish to separate out your Pantheon configuration in a separate settings.php file named

  1	pantheon.settings.php

  . If so, you will need to add the following to your

  1	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

  1	settings.php

  file to include the following right before your normal last code block implementing

  1	local.settings.php

  :

<?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

  1	pantheon_apachesolr

  for dev, test, and live.

Congratulations

If you made it here you rock!