With so many govCMS sites under development by different development teams it's important to try and standardise some of the practices being used.
We have spent significant effort in trying to streamline processes and tools behind govCMS. The hope is with everybody working in a consistent manner the community contributions can extend beyond the codebase itself into the processes driving development.
This guide will outline how to get started developing on the govCMS platform. The assumption is that this is for sites that will be hosted on govCMS, but it may be useful for standalone projects as well.
Note: if you are an Acquia partner working on a govCMS project most of the below steps will be carried out for you. You should check with the Engagement Manager assigned to the project if you are unsure.
Introduction to govCMS development
govCMS is Drupal, however there are some key considerations to take into account that may different from building a 'standard' Drupal site:
- You cannot add custom modules per site
- this is a requirement from both a security and stability perspective. If you need to add modules to govCMS you should follow the appropriate process
- You may provide a custom theme per site
- you are not limited to using the themes that come with the govCMS distribution - rather they are intended to act as a sensible starting point for sub-theming.
- there is a starter-theme in the codebase which may be used, but there is nothing stopping you from building a theme from scratch if it makes sense to
- Once development is complete it will be moved to the govCMS hosted environment for you
- there are additional auditing steps that may take place at this stage to ensure compliance, security and performance considerations are met
- Configuration change must be manually maintained after launch
- you cannot use Features to maintain, see above note on custom modules
- Acquia Cloud account
- GitHub account
- Download and install Vagrant
- [Mac/Linux only] Install Ansible
- [Local dev only] Download and install VirtualBox
- [AWS dev only] AWS account
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.
Step 1: Create a new Acquia Free site
We use the Acquia free tier for base development of govCMS sites. This provides a base/master for your development activity in both dev and staging environments, as well as a git repository containing the core govCMS codebase.
For govCMS projects, you will need to configure your repository a little differently, in order to keep you theme separate from the underlying govCMS distribution. This allows you to deploy just the theme to the ACSF environment.
- Select 'add a new free site' (note: for very large sites you can also use a paid version of Acquia Cloud)
- Enter a site name (e.g 'govcmsdev')
- Select the govCMS distribution to install
- Choose 'Australia' as the region
You will also need to configure access to your new govCMS development environment by adding a SSH key. In order to do this follow the relevant Acquia guide.
Step 2: Create and configure theme repository (GitHub)
Due to the way your theme is pulled into the govCMS environment it is important to keep your theme in its own repository. This means that you actually need two repositories:
- the Acquia cloud repository (created above)
- the theme repository
Create a new GitHub repository to contain your site theme. It may be public or private, and it should contain one or more Drupal theme folders at the root of the repository.
Once you have created this repository you need to configure access by adding a ssh key within GitHub (see GitHub guide). You should use a different key for your Acquia Cloud and GitHub accounts.
Step 3: Link codebase and theme repositories
So! Now you have two git repositories, one has been created for you in Acquia Cloud, and one containing one or multiple themes in GitHub.
But, you can only deploy a single repository to Acquia Cloud. So how do you get around this problem? Enter git subtrees.
First you will need your Acquia Cloud git repository. This can be found in the Cloud dashboard by clicking the 'Git URL' button in the upper right corner.
Using the Acquia Cloud and new GitHub theme repository git URLs:
git clone [email protected]:sitename.git cd ./sitename git remote add govcms-subtree [email protected]:srowlands/[THEME_REPO_NAME].git git subtree add --prefix=docroot/sites/default/themes/[THEME_NAME] govcms-subtree master git push origin master
To update the govCMS theme in the Acquia Cloud git repository periodically:
cd /path/to/acquia/sitename git fetch govcms-subtree git subtree pull --prefix=docroot/sites/default/themes/[THEME_NAME] govcms-subtree master [ MERGE ] git push origin master
Congratulations, at this point you have a fully fledged development environment in Acquia Cloud.