Skip to main content
 ●  28 September 2015

Developing with govCMS (Part 2 of 2)

This is part 2 of the govCMS development guide, it assumes you have already completed the steps outlined in part 1.

Step 1: Use govCMS-devkit to create local dev environments

govCMS-devkit allows for quick and easy local development in a VM, and automatically clones the latest master database from Acquia Cloud, and proxies assets (images, files) to the Acquia Cloud master preventing the need to sync files.

Check out the govCMS-devkit repository somewhere and copy the example 'local' config into place:

git clone [email protected]:srowlands/govcms-devkit.git
cd govcms-devkit; cp example.config.vm-acquiacloud.yml config.yml

 

Make the following adjustments to the config.yml file to customise to your site build:

# Acquia Cloud settings:
acquia_cloud_username: Set this to the email you use to login
acquia_cloud_password: Set this to the Cloud API key
acquia_cloud_git: Set this to the Git URL of the Acquia Cloud site
acquia_cloud_key: Point this to a copy of the key linked to your Acquia Cloud account (copy the key to ssh-keys in the govcms-drupal-vm folder)
acquia_cloud_sitename: Set this to the name of your site
 
# Stage File Proxy settings:
drupal_stage_file_proxy_url: Set this to the URL of your Acquia Cloud site

 

Build the local VM using Vagrant:

  1. Create a local directory (default /var/www/govcms-vm) where govCMS will be installed. You may change this location in config.yml (local_path, inside vagrant_synced_folders).
  2. Open Terminal, cd to this directory (containing the Vagrantfile and this README file).
  3. [Mac/Linux only] Install Ansible Galaxy roles required for this VM: $ sudo ansible-galaxy install -r provisioning/requirements.yml --force
  4. Run vagrant plugin install vagrant-hostmanager to add entries to your hosts file for you
  5. Type in vagrant up, and let Vagrant do its magic.
  6. Once complete open your browser and access http://govcms.dev/.

Note: If there are any errors during the course of running vagrant up, and it drops you back to your command prompt, just run vagrant provision to continue building the VM from where you left off. If there are still errors after doing this a few times, post an issue to this project's issue queue on GitHub with the error.

 

To periodically refresh a Vagrant development environment with latest database and codebase from the Acquia Cloud:

ansible-playbook -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory --private-key=~/.vagrant.d/insecure_private_key -u ubuntu provisioning/playbook.yml --tags="acquia-cloud"

 

Step 2: [Optionally] Configure GitHub Pull Request environment builder

The govCMS-devkit also provides options for spinning up a development environment in AWS EC2, and linking to GitHub for automated Pull Request environment building.

By the end of this process you will have an EC2 instance on AWS which will listen to new Pull Requests on the Github repo and create a cloned environment (based on the Acquia Cloud dev master) for each new pull request submitted.

This allows for segregation between features, and an enhancement to the UAT cycle whereby a client may perform UAT in a standalone environment, so only approved changes are merged back into the master theme.

Check out the govCMS-devkit repo and copy the example config into place:

git clone [email protected]:srowlands/govcms-devkit.git
cd govcms-devkit; cp example.config.aws-acquiacloud.yml config.yml

 

  1. Login to the EC2 console and generate a new key-pair in the region you wish to provision (default is Sydney ap-southeast-2).
  2. Create a new security group ensuring (at least) SSH access is allowed anywhere (port 22) to install.
  3. Make the following adjustments to the config.yml file to customise to your site build:
    # Acquia Cloud settings:
    acquia_cloud_username: Set this to the email you use to login to insight.acquia.com
    acquia_cloud_password: Set this to the Cloud API key
    acquia_cloud_git: Set this to the Git URL of the Acquia Cloud site
    acquia_cloud_key: Point this to a copy of the key linked to your Acquia Cloud account (copy the key to ssh-keys in the govcms-drupal-vm folder)
    acquia_cloud_sitename: Set this to the name of your site
     
    # Drupal theme settings:
    drupal_theme_repository: Set this to the Github repository containing govCMS theme
    drupal_theme_key: Point this to a copy of the key linked to your Github account (copy the key to ssh-keys in the govcms-drupal-vm folder
     
    # Stage File Proxy settings:
    drupal_stage_file_proxy_url: Set this to the URL of your Acquia Cloud site
     
    # Jenkins settings:
    jenkins_github_url: Set this to the URL of your Github theme repo
    jenkins_github_stub: Set this to the stub of the Github theme repo
     
    # AWS settings:
    aws_access_key_id: Set this to the AWS access key
    aws_secret_key: Set this to the AWS secret key
    aws_security_groups: Set this to a security group that allows relevant port access
    aws_elastic_ip: Set this to an elastic IP address if one is provisioned
    aws_keypair_name: Set this to the AWS keypair name
    aws_ssh_private_key: Point this to the key used to connect to your AWS account
    	
  4. Edit the config.yml file and provide AWS key, secret, and path to key-pair .pem file.
  5. Run vagrant plugin install vagrant-aws to install the AWS provider
  6. Run vagrant box add dummy https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box to add a dummy box
  7. Run vagrant plugin install vagrant-hostmanager to add entries to your hosts file for you
  8. Run vagrant up --provider=aws
  9. Visit http://govcms.dev/ in a browser

 

Configure Jenkins for Acquia Cloud connection:

Create a secret text credential containing the Acquia Cloud API key.

  1. Visit http://govcms.dev:8000/ in a browser to hit the Jenkins server (ensure your AWS security group allows this)
  2. Visit the Credentials > Global credentials > Add Credentials configuration screen
  3. Change 'kind' to Secret Text
  4. Paste your Acquia Cloud API key into the Secret field (same as acquia_cloud_password from config.yml)
  5. Give it a sensible description and click OK

Example Acquia Cloud Jenkins credentials

 

Configure the Jenkins Job to inject this password as a variable

  1. Go to the govcms_pull_request_builder job page, click Configure
  2. Ensure the build environment is using 'secret text(s) or files' and configured as per the below screenshot:

Example Acquia Cloud Jenkins configuration

 

Configure GitHub and Jenkins communication

Prepare GitHub

  1. Create a new GitHub 'bot' user and add an SSH key (or you can use your own user account if you wish).
    1. The bot user needs to have administrator rights for your repository (must be owner (user repo) or must have Push, Pull & Administrative rights (organization repo))
    2. Generate a new Personal Access Token and store somewhere safe.
      1. Needs repo, gist, notifications, user, admin:* scopes

Add the GitHub credentials to Jenkins

  1. Go to the credentials management screen.
  2. Click 'Add domain'
    • enter 'api.github.com' for Domain Name
    • add > Hostname > api.github.com (include)
    • add > URI scheme > https
  3. Click 'OK', then 'Add Credentials'
    • select 'Secret text' type
    • paste GitHub token into Secret field, and a useful description
      Add GitHub domain to Jenkins
  4. Go to the configure system screen (Manage Jenkins > Configure System).
  5. Under 'GitHub Pull Request Builder' select your token credential from the dropdown.
  6. Go to the job configuration screen
  7. Under 'Source Code Management' section add credentials (SSH Username with private key).
    This should be the SSH key allocated to the 'bot' user above. Remember to enter the passphrase if you entered one when generating.
    The username should be 'git'. You may either paste in your private key or copy to the machine and specify a location.
  8. Be sure to select the credentials you just created from the credentials dropdown. If it can connect successfully the red error message should disappear after a second or two.
  9. Under 'Build Environment > SSH Agent Credentials' select the same credentials created above.
  10. Go to your GitHub.com repo > Settings > Webhooks & Services and ensure a new webhook has been created.
    • Click the 'edit' icon and update the IP address to match the EC2 elastic IP.

Now that's done you should try creating a pull request against the GitHub theme repository. All going well you should see that a PR environment build has been triggered.

GitHub PR triggered

 

All going well you should see a success message, as well as a comment linking to the Pull Request environment.

Note: Unless you have configured a real domain you'll need to create an /etc/hosts record for n.stage.govcms.dev to resolve.

GitHub PR Success