GovCMS local development setup for Lagoon

This article targets Drupal 8 developers or agencies intending to develop GovCMS websites for the new GovCMS Lagoon/OpenShift hosting environment.

<TL;DR>
# SETUP
git clone https://www.github.com/govcms/govcms8-scaffold.git {INSERT_PROJECT_NAME} && cd $_
ahoy up
ahoy install
ahoy login
ahoy cex
<?php print 'GovCMS is great!'; ?>

# SYNC DATABASE
ahoy refresh-db

# UPGRADE GOVCMS
ahoy down (will destroy your database)
ahoy pull
ahoy build

The new GovCMS hosting provider – Salsa Digital, partnered with Amazee.io, offers the next generation web hosting platform for GovCMS customers.

In this article, I would like to share my experience in building a GovCMS SaaS website that is using the new hosting platform. I will be outlining technical details of setting up of the local development environments and tips of getting some of the development tools running (such as behat, phpunit, phpcs).

GovCMS hosting with Lagoon and Kubernetes overview

The new GovCMS hosting platform is built on the next generation technology – Kubernetes. Utilising Docker container images, Lagoon and OpenShift, the hosting platform offers many benefits compared to the previous hosting environment. The two main differences, compared to the previous hosting environment, are:

The OpenSource hosting environment is bundled as part of the OpenSource distribution.
It uses Docker containers and most of the required infrastructure is included in the Git repository. What is important is that for the local development the exact same containers and configuration is utilised. The immediate benefits are:
– Minimise the website reconfiguration burden during the forklift.
– Minimise configuration-related failures of the CI/CD (Continuous Integration and Continuous Delivery) pipelines.
The GovCMS (7, 8 or 9) distribution is now shipped in pre-built containers, offering many benefits:
1. No more Drupal multisite is in use,
2. No more GovCMS upgrade headache.

What you get with the new GovCMS setup out of the box

Complete local setup, using Docker containers:
1. PHP
2. Nginx
3. MariaDB
4. Redis
5. Apache Solr server
6. CLI
7. Test
8. Headless Chrome
Code linting
Used for Drupal coding standards validation.
Drutiny validation.
Behat and unit testing framework – this may still be a WIP, watch this blog for the upcoming post with the steps to activate it locally.
Just start adding your tests right away.

Getting started with GovCMS local setup

Local software prerequisites

Before getting started with GovCMS you will need a few tools, preinstalled on your development computer:

Git client
Docker (direct install link for Mac or Windows)
Pigmy (how to install link)
Ahoy (installation instructions link); or use brew package manager: `brew install ahoy –HEAD`

Consider the type of the hosting – SaaS or PaaS

Note! This step is not required to run a GovCMS site in the local environment.

Things to get sorted if you plan to run your GovCMS website in the OpenShift cluster:

A hosting agreement and an account with GovCMS – visit https://www.govcms.gov.au/
GitLab account (to be set up by the GovCMS team).

GovCMS repository

To build a GovCMS website you will need a copy of the GovCMS8-Scaffold repository [https://github.com/govCMS/govcms8-scaffold]. Clone it into your project folder and run a few commands to get it running.

Starting your local GovCMS environment in 4 steps

Step 1: Getting the codebase into your dev environment

git clone https://www.github.com/govcms/govcms8-scaffold.git {INSERT_PROJECT_NAME}; cd {INSERT_PROJECT_NAME}

Step 2: Configure the local dev environment

Copy the .env.default file into the .env file and modify it as required:

cp .env.default .env

Update the LOCALDEV_URL variable, set it to your desired local URL. This URL will be used to run your local copy of the site:

# Local development URL.
LOCALDEV_URL=https://govcms8.docker.amazee.io

To disable local cache and twig cache, make sure your .env file has this line:

DEV_MODE=true

Step 3: Start your environment locally

The next command starts some helper containers, including DNS proxy:

pygmy up

The next command spins up the local environment:

ahoy up

Step 4. Install GovCMS

The next command installs vanilla GovCMS, run this command once:

ahoy install

After your GovCMS is installed, confirm you can access it – navigate to the URL configured in the LOCALDEV_URL variable.

Next, you may export your local configuration:

ahoy cex

and commit it to Git.

That’s it. Your new GovCMS website should be running on your local environment. Use ahoy login to get the login link.

As you work on the project and build your site structure – such as content types, block types, paragraph types, views and so on, GovCMS team made it easy to export your Drupal configuration with ahoy cex, or ahoy cim to import it. Apparently, ahoy down and ahoy build simplifies the environment reset when you switch to another Git branch to work on another feature, or maybe when you need to test your work in a fresh environment.

How to set local environment URL in GovCMS

This step is described the Step 2. Configure local environment above, just update the value of the LOCALDEV_URL variable in the .env file and rebuild your local environment by running ahoy build

Exploring GovCMS with Default Content

To explore GovCMS, activate a few example content modules. Once you installed your GovCMS website, enable the GovCMS Default Content module

ahoy drush en govcms8_default_content

How to synchronise the local database from your production website in GovCMS on Lagoon

Before you can start synchronising production database to your local environment, one-time setup is necessary. Refer to the steps below:

How to create a personal access token for GovCMS
How to add a personal public SSH key to GitLab for GovCMS
How to use the personal access token before pulling production database backup

Once your website is running in Kubernetes/OpenShift cluster (aka GovCMS SaaS), nightly database backups are available via an ahoy command:

ahoy refresh-db

The very first thing to get access to the latest nightly database dump, developers need to set up their personal access token:

Create personal access username and a personal access token from GovCMS GitLab website.
Add personal public SSH key to GitLab: https://projects.govcms.gov.au/profile/keys

How to create a personal access token for GovCMS

To create a personal access token, follow these simple steps:

Navigate to https://projects.govcms.gov.au/profile/personal_access_tokens
Set Token name
Set Token expiration date
Select read_registry in Scopes
Click the Create personal access token button.

How to add a personal public SSH key to GitLab for GovCMS8

Copy your public key (e.g. pbcopy < ~/.ssh/id_rsa.pub)
Login to your personal GitLab account
Navigate to https://projects.govcms.gov.au/profile/keys
Paste your public key and press the “Add key” button

How to use the personal access token before pulling production database backup

In order to use the personal access token created above, login into GitLab from a terminal application:

docker login gitlab-registry-production.govcms.amazee.io -u <user> -p <token>

How to override your local configuration in GovCMS

In some cases, you may need to have a local configuration different from the one run in the Lagoon. For example, you may have the shield module disabled and the stage_file_proxy module enabled.

As you configure your local environment and export local configuration with ahoy cex, just explore any new or modified configuration files that modify your local environment. Copy the files that are relevant to your local configuration into the config/dev/ directory and commit to the Git repository.

In order to use the local configuration overrides, your team has to run the ahoy cim dev command, which is an equivalent of running drush cim; drush cim dev —partial

How to use drush in the local GovCMS environment

Drush commands are available locally via ahoy – e.g. ahoy drush status

How to access PHP logs in GovCMS locally

If you run into any unexpected issues and receive a 5xx server error, you could explore PHP logs with this command:

ahoy logs php

GovCMS local development setup for Lagoon

GovCMS hosting with Lagoon and Kubernetes overview

What you get with the new GovCMS setup out of the box