quickstart-guide.md

Quick-start guide

You can easily get started using Aquifer with just a couple commands.

1. Install Aquifer

Aquifer is an npm module, and can be installed by running:

npm install -g aquifer

2. Create an Aquifer project

To create a Aquifer-based Drupal project, run:

aquifer create my_project_name

This command uses Aquifer's project scaffolding API to create a directory that holds all the files and folders for your project. It also creates an aquifer.json file, which contains settings and config for Aquifer.

3. Building a Drupal site

Aquifer has a system that constructs a Drupal site root from a Drush make file, settings files, and custom code. This can be invoked by running:

aquifer build

The directory that Aquifer builds into can be configured by editing the "build" property in the aquifer.json file. The value of that property should be a path, and can be relative to the project directory, or an absolute path (for example, build, or /var/www).

Overriding aquifer.json locally

Any property in aquifer.json can be overridden locally without modifying aquifer.json. For instance, the build directory is highly relative to the environment in which Aquifer is building.

To override properties, create an aquifer.local.json file in the root of your Aquifer project, and set any properties with the values you want. They will automatically take presidence over the values specified in aquifer.json. Note that only properties you want to override should be added to aquifer.local.json, as this file does not replace the main aquifer.json file entirely, but only overrides the values assigned to properties it contains.

4. Adding contrib code

To add contrib modules to your project, simply edit the drupal.make.yml file and add your contrib modules there. To learn more about Drush make, see the these docs.

Aquifer makes optional use of Drush make lock files. If you make a change to drupal.make.yml after you've already built your site, you'll need to add the --refresh-lock flag to the aquifer build command so that the lock file is recalculated when your site root is constructed.

5. Adding custom code.

Custom themes should be added to the themes folder within the Aquifer root, and likewise custom modules should be added to the modules/custom folder, or modules/features folder if the custom module is a feature. When you build the site, Aquifer will symlink those files into your site root.

6. Installing, removing, and loading extensions.

Installing extensions is very simple. You can add extensions from local directories, git repositories, or from the npm repository.

Installing from npm

aquifer extension-add extension-name

Installing from git

Installing from sources that are not npm require you to use the -s source flag.

aquifer extension-add extension-name -s git+ssh://[email protected]/username/reponame

Installing from local filesystem

You could even write an Aquifer extension and store it in your project if you wanted to.

aquifer extension-add extension-name -s /path/to/extension-name

Loading extensions

Aquifer will load all of the extensions specified in the aquifer.json file when this command is run:

aquifer extensions-load

Extensions are not checked into repositories, so this is useful when you have multiple people working on a project. If one adds an extension, the others can load the extensions in. Aquifer will notify you when you have extensions that are installed but not downloaded locally.