search

stooit / govcms-devkit

govCMS dev environment builder (based on Drupal VM)
https://www.govcms.gov.au/
MIT License
2 stars 3 forks source link

readme

Drupal VM Logo

Build Status Documentation Status

govCMS-devkit is a development environment builder based off the excellent Drupal VM, built with Vagrant + Ansible.

This project aims to make spinning up a local (VM) or remote (AWS) govCMS test/development environment using a standardised toolset. It provides three options for install:

  1. Install in a local VM (VirtualBox, Parallels or VMware)
  2. Install on a remote AWS server
  3. Install on a remote AWS server (include CI with Jenkins)

It will install the following on an Ubuntu 14.04 (by default) linux environment:

It should take 10-15 minutes to build or rebuild the VM from scratch on a decent broadband connection.

Customizing the VM

This codebase comes with preconfigured config files for the govCMS distribution. There are a couple places where you can customize the VM for your needs:

Quick Start Guide

This Quick Start Guide will help you quickly build a govCMS environment using the Drupal.org release of govCMS.

Install dependencies (Vagrant, Ansible)

  1. Download and install Vagrant.

  2. [Mac/Linux only] Install Ansible.

    Note for Windows users: Ansible will be installed inside the VM, and everything will be configured internally (unlike on Mac/Linux hosts). See JJG-Ansible-Windows for more information.

    Note for Linux users: If NFS is not already installed on your host, you will need to install it to use the default NFS synced folder configuration. See guides for Debian/Ubuntu, Arch, and RHEL/CentOS.

    Note on versions: Please make sure you're running the latest stable version of Vagrant, VirtualBox, and Ansible, as the current version of Drupal VM is tested with the latest releases. As of June 2015: Vagrant 1.7.2, VirtualBox 4.3.26, and Ansible 1.9.2.

Install in a local VM (VirtualBox, Parallels or VMware)

  1. Download this project and put it wherever you want.
  2. Configure for each VM platform as below:
    • VirtualBox:
      • Download and install VirtualBox.
      • Open Terminal, cd to this directory (containing the Vagrantfile and this README file).
      • Copy example.config.vm-vbox.yml to config.yml
    • Parallels:
      • Open Terminal, cd to this directory (containing the Vagrantfile and this README file).
      • Copy example.config.vm-parallels.yml to config.yml
    • Type in vagrant plugin install vagrant-parallels
    • VMware
      • Download and install the Vagrant VMware integration plugin
      • Open Terminal, cd to this directory (containing the Vagrantfile and this README file).
      • Copy example.config.vm-vmware.yml to config.yml
  3. 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).
  4. Open Terminal, cd to this directory (containing the Vagrantfile and this README file).
  5. [Mac/Linux only] Install Ansible Galaxy roles required for this VM: $ sudo ansible-galaxy install -r provisioning/requirements.yml --force
  6. Run vagrant plugin install vagrant-hostmanager to add entries to your hosts file for you
  7. Type in vagrant up, and let Vagrant do its magic.
  8. Once complete open your browser and access http://govcms.dev/. The default login for this admin account is admin for both username and password.

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.

Extra software/utilities

By default, this VM includes the extras listed in the config.yml option installed_extras:

installed_extras:
  - adminer
  # - jenkins
  - mailhog
  - memcached
  - pimpmylog
  # - solr
  # - selenium
  - varnish
  - xdebug
  - xhprof

If you don't want or need one or more of these extras, just delete them or comment them from the list. This is helpful if you want to reduce PHP memory usage or otherwise conserve system resources.

Other Notes

Install on a remote AWS server

  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. Download this project and put it wherever you want.
  4. Open Terminal, cd to this directory (containing the Vagrantfile and this README file).
  5. Copy example.config.aws.yml to config.yml
  6. Edit the config.yml file and provide AWS key, secret, and path to key-pair .pem file.
  7. Run vagrant plugin install vagrant-aws to install the AWS provider
  8. Run vagrant box add dummy https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box to add a dummy box
  9. Run vagrant plugin install vagrant-hostmanager to add entries to your hosts file for you
  10. Run vagrant up --provider=aws
  11. Visit http://govcms.dev/ in a browser

Install on a remote AWS server (include CI with Jenkins)

This will install Jenkins and pre-configure with a pull-request environment builder, which will:

It makes the following assumptions:

Pre-build actions

In order to use the pre-configured Jenkins pull-request environment builder you will need to perform the following steps:

  1. Prepare AWS/EC2

    • Allocate a new elastic IP in the EC2 console, take note of this IP address to enter in config.yml.
    • Ensure you have a security group configured in EC2 that allows incoming TCP connections in port 22,80,8000 from valid IPs

  2. Prepare GitHub

    • Create a new GitHub repository containing 1 or more drupal themes at the root (public or private).
    • Create a new GitHub 'bot' user and add an SSH key.
      • The user needs to have administrator rights for your repository (must be owner (user repo) or must have Push, Pull & Administrative rights (organization repo))
    • Generate a new Personal Access Token and store somewhere safe.
      • Needs repo, gist, notifications, user, admin:* scopes

  3. Perform the same steps as above (remote AWS server), but copy the example.config.aws-jenkins.yml file instead at step 5.

  4. Update the additional variables in the config.yml file:

    • jenkins_github_repo (git URL to theme repository to monitor)
    • jenkins_github_url (URL to GitHub repository)
    • jenkins_github_stub (GitHub stub)
    • aws_elastic_ip (IP address allocated above)

  5. Once complete, visit http://govcms.dev:8000/ in a browser.

  6. Prepare Jenkins

    • [RECOMMENDED] Configure Jenkins security to avoid non-authenticated access.
    • Go to the credentials management screen.
    • Click 'Add domain'
      • enter 'api.github.com' for Domain Name
      • add > Hostname > api.github.com
      • add > URI scheme > https
    • Click 'OK', then 'Add Credentials'
      • select 'Secret text' type
      • paste GitHub token into Secret field, and a useful description
    • Go to the configure system screen.
    • Under 'GitHub Pull Request Builder' select your token credential from the dropdown.
    • Go to the job configuration screen.
    • 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.
    • Under 'Build Environment > SSH Agent Credentials' select the same credentials created above.
    • Go to your GitHub 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.

License

This project is licensed under the MIT open source license.

Author

Credits

Drupal VM Logo

About Drupal-VM

Please read the Drupal VM Wiki for help getting Drupal VM configured and integrated with your development workflow.

Jeff Geerling, owner of Midwestern Mac, LLC, created this project in 2014 so he could accelerate his Drupal core and contrib development workflow. This project, and others like it, are also featured as examples in Jeff's book, Ansible for DevOps.

Documentation

Full Drupal VM documentation is available at http://docs.drupalvm.com/

Using Drupal VM

Drupal VM is built to integrate with every developer's workflow. Many guides for using Drupal VM for common development tasks are available on the Drupal VM Wiki: