This article targets Drupal 8 developers or agencies intending to develop GovCMS 8 websites for the new GovCMS 8 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 8 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 8 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 8 hosting with Lagoon and OpenShift/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 or 8) distribution is now shipped in pre-built containers, offering many benefits:
- No more Drupal multisite is in use,
- No more GovCMS upgrade headache.
What you get with the new GovCMS 8 setup out of the box
- Complete local setup, using Docker containers:
- PHP
- Nginx
- MariaDB
- Redis
- Apache Solr server
- CLI
- Test
- 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 8 local setup
Local software prerequisites
Before getting started with GovCMS 8 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 8 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 8 repository
To build a GovCMS 8 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 8 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=http://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 8
The next command installs vanilla GovCMS 8, run this command once:
ahoy install
After your GovCMS 8 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 8 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 8
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 8 with Default Content
To explore GovCMS 8, activate a few example content modules. Once you installed your GovCMS 8 website, enable the GovCMS 8 Default Content module
ahoy drush en govcms8_default_content
How to synchronise the local database from your production website in GovCMS 8 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 8
- How to add a personal public SSH key to GitLab for GovCMS8
- 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 8
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 8
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 8 environment
Drush commands are available locally via ahoy – e.g. ahoy drush status
How to access PHP logs in GovCMS 8 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