WARNING - This is not an official GOV.UK repository. It is also a WIP and could receive breaking changes at any time.

govuk-docker

An alternative way to to develop on GOV.UK.

Introduction

The GOV.UK website is a microservice architecture, formed of many apps working together. Developing in this ecosystem is a challenge, due to the range of environments to maintain, both for the app being developed and its dependencies.

The aim of govuk-docker is to make it easy to develop any GOV.UK app. It achieves this by providing a variety of environments or stacks for each app, in which you can run tests, start a debugger, publish a document end-to-end e.g.

# Run whitehall rake plus any required dependencies (DBs)
whitehall$ gdr default rake

# Start content-tagger rails plus a minimal backend stack
content-tagger$ gdr backend

# Start content-publisher rails plus an end-to-end stack
content-publisher$ gdr e2e

The above examples make use of an alias to reduce the amount of typing; the full form is govuk-docker run-this. In the last two commands, the app will be available in your browser at app-name.dev.gov.uk.

Setup

First make sure the following are installed on your system:

• dnsmasq to make app-name.dev.gov.uk work
• docker and docker-compose, fairly obviously
• git if you're setting everything up from scratch
• A directory ~/govuk in your home directory

Start with the following in your bash config (aliases optional).

alias gd="govuk-docker"
alias gdr="govuk-docker run-this"
alias gdd="govuk-docker run-this default"
alias gdb="govuk-docker build-this"

export PATH=$PATH:~/govuk/govuk-docker/bin

Now in the govuk directory, run the following commands.

git clone git@github.com:benthorner/govuk-docker.git
cd govuk-docker

# Expect this to take some time (around 20 minutes)
make

Then create or append to the following and restart dnsmasq.

# /etc/resolver/dev.gov.uk
nameserver 127.0.0.1

# /usr/local/etc/dnsmasq.conf (bottom)
address=/dev.gov.uk/127.0.0.1

User Needs

The aim of govuk-docker is to meet the following primary need.

As a developer on GOV.UK apps
I want a GOV.UK environment optimised for development
So that I can develop GOV.UK apps efficiently

However, this high-level statement hides a great number of specific needs, which also help to clarify the design decisions for govuk-docker. These lower-level needs and associated decisions are set out in separate documents.

Compatibility

The following apps are supported by govuk-docker to some extent.

• ⚠ asset-manager
  • One failing spec for virus scanning
• ⚠ content-data-admin
  • TODO: Missing support for a webserver stack
• ✅ content-publisher
• ⚠ content-store
  • MongoDB config is overriden to use a different test DB
• ⚠ content-tagger
  • chromedriver-helper version lock is manually added
• ⚠ government-frontend
  • chromedriver-helper version lock is manually added
• ✅ govspeak
• ⚠ govuk-developer-docs
  • Some manuals require explicit UTF-8 support
  • One test fails due to an irrelevant ordering issue
  • Another test seems to be failing due fixture issues
• ✅ govuk-lint
• ✅ govuk_app_config
• ❌ govuk_publishing_components
  • Unable to run rake due to an old version of Jasmine
• ✅ miller-columns-element
• ✅ plek
• ✅ publishing-api
• ❌ router
  • Unable to run make test due to a hardcoded DB host
• ✅ router-api
• ✅ signon
• ⚠ static
  • JavaScript 404 errors when previewing pages, possibly related to analytics
• ✅ support
• ⚠ support-api
  • PostgreSQL config is overriden to set a non-localhost URL
• ⚠ whitehall
  • Who knows, really - several tests are failing, lots pass ;-)
  • Rake task to create a test taxon for publishing is not idempotent
  • Placeholder images don't work as missing proxy for /government/assets

FAQs

How to: diagnose and troubleshoot

Sometimes things go wrong or some investigation is needed. As govuk-docker is just a bunch of docker config and a CLI wrapper, it's still possible to use all the standard docker commands to help fix issues and get more info e.g.

# tail logs for running services
gd logs -f

# get all the running containers
docker ps -a

# cleanup all govuk-docker services
gdd

# get a terminal inside a service
gdrd bash

How to: add a new service

Here's an example commit that does just that.

https://github.com/benthorner/govuk-docker/commit/1cd31a5fa3469cce47637db81f17ca1b03d72f89

How to: change a service e.g. upgrade Ruby

This will usually involve editing a Dockerfile, for things like system packages or new language versions; or a docker-compose.yml file, for things like environment variables and dependencies on other services. When a Dockerfile changes, the associated image needs to be rebuilt, which can be done in the service directory by running gdb.

How to: setup a specific service

If a new service has been added to govuk-docker, first pull the latest version to get the changes. One way to setup the new service would be to run make, but this goes through every service and might take a while. A faster way is to do this:

# auto-clone any new services
make clone

# setup the specific service(s)
make -f my_service/Makefile

How to: update everything!

Sometimes it's useful to get all changes for all repos e.g. to support finding things with a govuk-wide grep. This can be done by running make pull, followed by make setup to ensure all services continue to run as expected.