generator-outrigger-drupal

Outrigger Drupal

Yeoman generator that weaves together Outrigger with other best-in-class tools for your Drupal project.

The Outrigger Cloud sub-generator is still tied to Phase2's internal Docker hosting solution. The next version will be more open.

This project helps create new Drupal projects fully outfitted with environment support, build processes, frontend tooling, and more. It operates as an umbrella Yeoman generator that asks questions, then passes the answers to multiple "child" generators that handle their own aspect of project scaffolding. As the name implies, this generator focuses on Outrigger practices, where some of the other generators in use are focused on broader industry best practices.

Installation & Usage

Using Docker Image

mkdir ~/PROJECT-NAME
cd ~/PROJECT-NAME
docker run -it --rm -v $PWD:/generated outrigger/generator

For more options check out outrigger/generator directly.

Using Docker for Development

Docker-based usage is available as of v3.0.0. It is the recommended approach as updates tend to be less prone to complication.

git clone [e-mail]:phase2/generator-outrigger-drupal.git
cd generator-outrigger-drupal
git checkout v4.0.0
docker-compose run --rm cli npm install
mkdir ~/path/to/empty/directory
YO_PROJECT_DIRECTORY=~/path/to/empty/directory docker-compose run --rm yo outrigger-drupal

Using npm

npm install -g generator-outrigger-drupal
mkdir ~/path/to/empty/directory
cd ~/path/to/empty/directory
yo outrigger-drupal

Command-line Options

• --replay: Re-run the generator against an existing project, using previously entered answers.
• --use-master: Will make a point of leveraging the master version of grunt-drupal-tasks.
• --skip-install: Will skip running npm install at the end of the generation process. (Applied by default when you opt-in for the Docker-based Outrigger Environment.)

Answering Yeoman Prompts

First-time Usage

Once Yeoman has been started, you will be prompted to answer six to a dozen questions about your project. These questions are used by the generator to select templates, create variables for use in the templates, and further execute any code or customizations on top of the templated scaffolding.

Please read the output at the end of the generator run, it has instructions on next steps.

Running on a Generated Project

When you use this to generate a project, all your answers are recorded by Yeoman in a .yo-rc.json file at the root of your repository. As long as you commit this to the codebase, from then if you run the generator targeting that directory it will use the previous answers as the defaults to every prompt. For even faster usage, you can run yo outrigger-drupal --replay and it will automatically run the generator without stopping to ask old questions.

If you run the generator, it will overwrite files. That's the idea in this case, as your goal is to cherrypick good new stuff the generator provides into your project. Run git add -p . to view each change one chunk at a time, and decide if it makes sense to discard or keep. Feel free to ask for help.

The extensive CHANGELOG notes are intended to help guide this process.

Retrofitting an Existing Project

If you have an existing project and want to retrofit it to use the scaffolding and tools this generator provides, there is no magical solution.

• Create a new empty project, answer the prompts to align as closely as possible with your current projects practices and the goals you have in using the generator.
• Copy all the pieces of your codebase into the new structure, including your .git directory.
• Adjust your scripts to the new structure, and adjust the generated configuration and scripts to the parts of your codebase that are not changing.

Next Steps

Read the generated TODOS.md file. Remove things as you work through mastering and running your vanilla Drupal system for the first time.

If you are not using the Docker-based development environment, you can get your codebase built by running grunt. From there you are on your own.

If you are using the Docker-based development environment, run rig project setup and your codebase will be built and a new site installed.

Child Generators

Backend Build Process, Testing, & Task Runner

Grunt Drupal Tasks manages backend development, continuous integration, and overall project tooling for the Drupal application.

A best practice setup of GDT with a few extra goodies are provided by Yo Outrigger Drupal's use of Generator Gadget to produce the top-level Drupal application scaffolding.

Component-driven Frontend

[Pattern Lab Starter](Pattern Lab Starter) is used to provide an optional Drupal theme with Pattern Lab for collaborative, design-driven development.

This is set up by Generator PLS.

Grunt Drupal Tasks manages theme compilation via the Theme Scripts of GDT so a full site compile can happen by running the project's default build task: grunt.

Docker-based Development Environment

We integrate with Outrigger (now http://outrigger.sh) to provide a quick, consistent, container-based, local development environment that can also be used on Phase2's centralized Outrigger hosting to provide integration, testing, and other environments.

This uses a sub-generator of generator-outrigger-drupal which can be separately executed as yo outrigger-drupal:environment.

Feature Breakdown

• docker-compose.yml which provides Docker configuration for the "operational" services needed to run your Drupal site locally.
  • Default support for Apache and MariaDB containers, with optional support for Redis or Memcache, Varnish, and Mailhog
  • Supports Outrigger's DNSDock-based DNS service for nice URLs.
  • Supports nginx-proxy for Outrigger Hosting nice URLs.
• build.yml which provides tailored use of the Outrigger Build container.
  • Persists command-line history on a per project/per environment basis.
  • Persists build tool cache for Drush, Behat/Gherkin, Drupal Console, npm, composer, yarn, bower, fontconfig, and any other tool which uses ~/.cache.
  • Defines easy-access use of grunt, drush, drupal console, and composer.
  • Defines a "CLI" service to open a standing BASH session with the build container.
• Default settings.php configuration that sets up Drupal environment configuration the "Docker way" to work out-of-the-box.
• Default Drush configuration for slim database exports and a nice project alias.
• Use Grunt Drupal Tasks via Docker, using minor configuration adjustments.
• Provides a range of shell scripts to run builds, verify aspects of the system, create default users, and more.

Outrigger Cloud: Project-specific CI & Environment Management

If you liked the Docker-based environments, you can also use our Docker-based Jenkins instance to manage your central test environments, complete with default jobs so you can start continuous integration with zero further configuration.

This uses a sub-generator of generator-outrigger-drupal which can be separately executed as yo outrigger-drupal:cloud.

Feature Breakdown

• Jenkins 1.x CI server pre-configured with various jobs:
  • CI job polling your git repo to run tests.
  • "dev-support" job to produce nightly database dumps of a fresh site install.
  • Optional Environment lifecycle management jobs for Development, QA, and Review environments, including: start/stop containers, deploy code, reset admin user password
  • Test jobs to confirm the system is working.
• Workspace details persisted in volume mounts inside repo:jenkins/env/workspace.

Changelog

v4.0.0 (October 11, 2017)

One of the big changes in this release is the removal/deprecation of the bin/start.sh script. For a longish explanation why please check out Deprecate the start.sh script in favor of using the underlying tools #59

For more on the breaking changes associated with this release read on past the change list.

• Moved generated .outrigger.yml to outrigger.yml for improved visibility. (:environment)
• Removed start.sh script and replaced with a deprecation message. (:environment)
• Added more robust rig project scripts instead of start.sh script. (:environment)
• Added documentation to repo on generated outrigger scripts.
• Fixed composer install or composer update process does not return failure if patches fail to apply.
• Added Drush defaults such that using drush via the cli service will target the site. (This removes the requirement to always use the alias via the cli service. Use drush @none to avoid Drupal bootstrap.)
• Added out-of-box configuration for Xdebug via the CLI. (Ready out of box with PHPStorm configuration)
• Added validation to domain prompt to disallow capital letters. (:environment)
• Refactored all things CI or remote-host oriented to the new cloud sub-generator.
• Added prompt to enter the remote CI host. (:cloud)
• Removed outrigger integration as optional (Jenkins integration is optional via :cloud) (:environment)
• Fixed generated grunt fetch-db task. (:environment)
• Fixed cli build service to default to use BASH. (:environment)
• Fixed --replay flag.
• Fixed Unison compatibility for bin/docker.sh. (:environment)

Technical Plumbing

• Upgraded generator-gadget to v1.2.0 (Release Notes)

Contributors

@grayside, @scottalan, @jhedstrom, @mike-potter, @febbraro, @tekante

Breaking Changes

Code Changes

To continue using the --replay flag with projects generated before v4, please make the following changes to your .yo-rc.json file, hidden at the root of your git repo.

• Replace useEnv with useCloud.
• Add cloudHost key set to the URL of your Docker host. (For example: ci.p2devcloud.com)

System Requirements

Upgrade rig CLI to at least version 1.3.2.